Skip to content

Commit 14ff96f

Browse files
evgenykevgenyk
authored
Merge pull request #28 from kinde-oss/ev/management_api_doc
Implement memory session hooks and enhance Management API documentation
2 parents 39f4635 + 5aad341 commit 14ff96f

12 files changed

Lines changed: 1456 additions & 103 deletions

‎README.md‎

Lines changed: 40 additions & 96 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,8 @@
22

33
The Kinde SDK for Go.
44

5+
> **📚 Management API**: For comprehensive information about using the Kinde Management API, see [README_MANAGEMENT_API.md](README_MANAGEMENT_API.md).
6+
57
[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square)](https://makeapullrequest.com) [![Kinde Docs](https://img.shields.io/badge/Kinde-Docs-eee?style=flat-square)](https://kinde.com/docs/developer-tools) [![Kinde Community](https://img.shields.io/badge/Kinde-Community-eee?style=flat-square)](https://thekindecommunity.slack.com)
68

79
## Development
@@ -15,69 +17,16 @@ go get github.com/kinde-oss/kinde-go
1517
go mod tidy
1618
```
1719

18-
## Autorization code flow
19-
20-
`authorization_code` package, imported as `github.com/kinde-oss/kinde-go/oauth2/authorization_code`.
21-
22-
This is a backend authorization flow, which requires slient secret. It is designed to be used as a server-side auth flow and not exposes tokens to the browser. The user session needs to be managed by other means, for example via the session cookie.
23-
24-
```go
25-
26-
kindeAuthFlow, err := authorization_code.NewAuthorizationCodeFlow(
27-
"<issuer URL>", //Kinde subdomain or any auth provider conforming to the spec
28-
"<client_id>", "<client_secret>", "<callback URL>",
29-
authorization_code.WithSessionHooks(<ISessionHooks implementation>), //example of storage for gin framework is gin_kinde.UseKindeAuth(...)
30-
authorization_code.WithOffline(), //adds offline scope and starts managing refresh tokens
31-
authorization_code.WithAudience("<your API audience>"), //requesting an API audience
32-
authorization_code.WithTokenValidation(
33-
true, // will validate token signature via JWKS
34-
jwt.WillValidateAlgorithm(), // will validate the token alg is RS256
35-
jwt.WillValidateAudience("<your API audience>"), // will confirm that received token includes correct audience
36-
),
37-
)
38-
39-
```
40-
41-
`kindeAuthFlow` provides the following methods:
20+
## Authorization Code Flow
4221

43-
| Method | Description | Parameters | Returns |
44-
| --- | --- | --- | --- |
45-
| `GetAuthURL` | Returns the URL to redirect the user to start the authentication pipeline. | none | `string` |
46-
| `ExchangeCode` | Exchanges the authorization code for a token and establishes KindeContext. | ctx `context.Context`, authorizationCode `string`, receivedState `string` | `error` |
47-
| `GetClient` | Returns an HTTP client for calling external services, automatically refreshing tokens if offline is requested. | ctx `context.Context` | `(*http.Client, error)` |
48-
| `IsAuthenticated` | Checks if the user is authenticated. | ctx `context.Context` | `(bool, error)` |
49-
| `Logout` | Clears local tokens and logs the user out. | none | `error` |
50-
| `AuthorizationCodeReceivedHandler` | Helper handler middleware for the code exchanger. | w `http.ResponseWriter`, r `*http.Request` | none |
51-
52-
### Device authorization flow
22+
For comprehensive information about the authorization code flow and device authorization flow, see [oauth2/authorization_code/README.md](oauth2/authorization_code/README.md).
5323

54-
`authorization_code` package, imported as `github.com/kinde-oss/kinde-go/oauth2/authorization_code`.
24+
The `authorization_code` package provides OAuth2 authorization code flow implementations for Go applications, including:
5525

56-
This is an extension of authorization code flow, which separatees token requester and receiver. It is best used for devices and environment with the limited input capabilities, e.g. CLIs, TVs etc.
57-
58-
```go
59-
deviceFlow, err := authorization_code.NewDeviceAuthorizationFlow(
60-
"<issuer_domain>", // Kinde subdomain or any auth provider conforming to the spec
61-
authorization_code.WithClientID(), // optional, when business provides a default device applicaiton, otherwise required
62-
authorization_code.WithClientSecret(), // optional (used when device flow is used against backend application with a secret)
63-
authorization_code.WithSessionHooks(<ISessionHooks implementation>), // used for storing/retreiving tokens
64-
authorization_code.WithOffline(), // optional - include if you'd like to maintain refresh tokens and a long session
65-
authorization_code.WithTokenValidation(
66-
true, // will validate token signature via JWKS
67-
jwt.WillValidateAlgorithm(), // will validate the token alg is RS256
68-
)
69-
```
70-
71-
`deviceFlow` will provide following methods
72-
73-
| Method | Description | Parameters | Returns |
74-
| --- | --- | --- | --- |
75-
| `StartDeviceAuth` | Starts the device authorization flow and returns the device authorization response. | ctx `context.Context` | `(*oauth2.DeviceAuthResponse, error)` |
76-
| `ExchangeDeviceAccessToken` | Exchanges the device code for an access token. | ctx `context.Context`, da `*oauth2.DeviceAuthResponse`, opts `...oauth2.AuthCodeOption` | `error` |
77-
| `GetClient` | Returns an HTTP client for calling external services, automatically refreshing tokens if offline is requested. | ctx `context.Context` | `(*http.Client, error)` |
78-
| `IsAuthenticated` | Checks if the user is authenticated. | ctx `context.Context` | `(bool, error)` |
79-
| `Logout` | Clears local tokens and logs the user out. | none | `error` |
80-
| `GetToken` | Returns the token for the current session. | ctx `context.Context` | `(*jwt.Token, error)` |
26+
- Standard authorization code flow for web applications
27+
- Device authorization flow for devices with limited input capabilities
28+
- Session management and token validation
29+
- Offline support with refresh token management
8130

8231
## Client credentials flow
8332

@@ -94,7 +43,7 @@ kindeClient, err := client_credentials.NewClientCredentialsFlow(
9443
"<client_secret>", // required for client_credentials
9544
client_credentials.WithAudience("[your API audience]"), // optioanlly include your API audience
9645
client_credentials.WithScopes() // optional - request API scopes
97-
client_credentials.WithKindeManagementAPI("<https://my_kinde_tenant.kinde.com>"), // adds kinde management API audience
46+
client_credentials.WithKindeManagementAPI("<https://my_kinde_tenant.kinde.com>"), // adds kinde management API audience - see README_MANAGEMENT_API.md for details
9847
client_credentials.WithSessionHooks(<ISessionHooks implementation>), // example of CLI is cli.NewCliSession(...)
9948
client_credentials.WithTokenValidation( // validates tokens when a new token is aquired
10049
true, // will validate token signature via JWKS
@@ -113,50 +62,26 @@ kindeClient, err := client_credentials.NewClientCredentialsFlow(
11362

11463
#### Using client to request an authorized endpoint
11564

116-
Client willl manage tokens in the background, reading/persisting them to provided the session storage.
65+
Client will manage tokens in the background, reading/persisting them to provided the session storage.
11766

11867
When offline scope is requested, refresh tokens will be managed as well.
11968

12069
```go
121-
//This client will cache the token and re-fetch a new one as it expires
122-
client := kindeClient.GetClient(context.Background())
123-
124-
//example call to Kinde Management API (client needs WithKindeManagementAPI(...))
125-
response, err := client.Get("<an authorized URL>")
126-
70+
// This client will cache the token and re-fetch a new one as it expires
71+
client, err := kindeClient.GetClient(context.Background())
72+
if err != nil {
73+
// handle initialization error (e.g., invalid config or token source)
74+
log.Fatalf("failed to init client: %v", err)
75+
}
12776
```
12877

129-
### Calling Kinde Management API
130-
131-
`kinde` package, imported with `github.com/kinde-oss/kinde-go/kinde`.
132-
133-
Please note, Kinde management API is only accessible via M2M applications with Management API enabled and limited by the authorized scopes.
134-
135-
You can have multiple applications configured with different levels of access.
136-
137-
Kinde uses generated code to map OpenAPI specification to go.
78+
// example call to Kinde Management API (client needs WithKindeManagementAPI(...)) - see README_MANAGEMENT_API.md for details response, err := client.Get("<an authorized URL>")
13879

139-
```go
140-
managementApi, err := kinde.NewManagementAPI(ctx, "<kinde domain>", <client credentials flow>) //management API uses client credentials flow described earlier
141-
```
142-
143-
For example to create an application
144-
145-
```
146-
res, err := managementApi.CreateApplication(ctx, &management_api.CreateApplicationReq{
147-
Name: "Backend app",
148-
Type: management_api.CreateApplicationReqTypeReg,
149-
})
150-
```
80+
### Management API
15181

152-
This call returns `CreateApplicationRes` interface, which can be one of the following:
82+
For comprehensive information about using the Kinde Management API, including authentication, setup, and usage examples, see [README_MANAGEMENT_API.md](README_MANAGEMENT_API.md).
15383

154-
| Interface | Description |
155-
| ---------------------------------- | -------------------------- |
156-
| `CreateApplicationBadRequest` | Incorrect input parameters |
157-
| `CreateApplicationForbidden` | Usually missing scope |
158-
| `CreateApplicationTooManyRequests` | Throttled response |
159-
| `CreateApplicationResponse` | Successful response |
84+
The Management API allows you to programmatically manage your Kinde tenant, including creating applications, managing users, configuring settings, and more. It requires M2M applications with Management API enabled and appropriate scopes configured.
16085

16186
### JWT Package
16287

@@ -170,6 +95,21 @@ The `jwt` package provides comprehensive JWT parsing, validation, and management
17095
- Comprehensive token information access
17196
- Seamless integration with OAuth2 flows
17297

98+
## Examples
99+
100+
This repository includes several examples demonstrating different authentication flows:
101+
102+
- **CLI Example** (`examples/cli`): Demonstrates device authorization flow and secure token storage
103+
- **Gin Chat Example** (`examples/gin-chat`): Shows how to integrate Kinde authentication with a Gin web application
104+
105+
For detailed documentation on each flow:
106+
107+
- **Authorization Code Flow**: [oauth2/authorization_code/README.md](oauth2/authorization_code/README.md)
108+
- **Client Credentials Flow**: See the Client Credentials Flow section below
109+
- **Management API**: [README_MANAGEMENT_API.md](README_MANAGEMENT_API.md)
110+
111+
For Management API examples and detailed usage, see [README_MANAGEMENT_API.md](README_MANAGEMENT_API.md).
112+
173113
### SDK Development
174114

175115
1. Clone the repository to your machine:
@@ -205,3 +145,7 @@ Please refer to Kinde’s [contributing guidelines](https://github.com/kinde-os
205145
## License
206146

207147
By contributing to Kinde, you agree that your contributions will be licensed under its MIT License.
148+
149+
```
150+
151+
```

0 commit comments

Comments
 (0)