-
Notifications
You must be signed in to change notification settings - Fork 71
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Add oauth docs #847
Open
bcbogdan
wants to merge
4
commits into
master
Choose a base branch
from
feat/oauth
base: master
Could not load branches
Branch not found: {{ refName }}
Loading
Could not load tags
Nothing to show
Loading
Are you sure you want to change the base?
Some commits from the old base branch may be removed from the timeline,
and old review comments may become outdated.
Open
Add oauth docs #847
Changes from all commits
Commits
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,166 @@ | ||
--- | ||
title: Create an authentication provider | ||
hide_title: true | ||
--- | ||
|
||
import BackendSDKTabs from "/src/components/tabs/BackendSDKTabs" | ||
import TabItem from '@theme/TabItem'; | ||
import CoreInjector from "/src/components/coreInjector" | ||
import FrontendPreBuiltUITabs from "/src/components/tabs/FrontendPreBuiltUITabs" | ||
|
||
# Multiple Frontend Domains Using a Single Backend | ||
|
||
You can use the following guide if you have multiple **`frontend applications`** on different domains, that use the same **`backend service`**. | ||
|
||
Using the actual **OAuth 2.0** terminology, we can say that each **`frontend`** can be considered a [**Client**](/docs/oauth/introduction#client) and the **`backend`** will act as both an [**Authorization Server**](/docs/oauth/introduction#authorization) and a [**Resource Server**](/docs/oauth/introduction#resource-server). | ||
|
||
:::info | ||
This guide assumes that you already have setup and configured **SuperTokens** in your [**Authentication Service**](/docs/oauth/introduction#authentication-service). | ||
|
||
For more information on how to do that please check our [quickstart guide](/docs/thirdparty/introduction). | ||
::: | ||
|
||
## 1. Create the OAuth2 Clients | ||
|
||
For each of your **`frontend`** applications you will have to create a separate [**OAuth2 client**](/docs/oauth/introduction#client). | ||
This can be done by directly calling the **SuperTokens Core** API. | ||
|
||
<CoreInjector defaultValue="https://example.com"> | ||
|
||
```bash | ||
curl -X POST ^{coreInjector_uri_without_quotes}/recipe/oauth2/admin/clients \ | ||
-H "Content-Type: application/json" \ | ||
-H "api-key: ^{coreInjector_api_key_without_quotes}" \ | ||
-d '{ | ||
"client_name": "<YOUR_CLIENT_NAME>", | ||
"response_types": ["code", "id_token"], | ||
"grant_types": ["authorization_code", "refresh_token"], | ||
"redirect_uri": ["https://<YOUR_DOMAIN>.com/oauth/callback"] | ||
}' | ||
``` | ||
|
||
</CoreInjector> | ||
|
||
|
||
- `client_name` - A human-readable name of the client that will be presented to the [**end-user**](/docs/oauth/introduction#authorization) during authorization. | ||
- `response_types` - Specifies the types of responses your client expects from the Authorization Server. | ||
- `code`: Indicates that the [**Client**](/#authorization) will receive an [**Authorization Code**](/#authorization) that will be exchanged for an [**Access Token**](/#authorization). | ||
- `id_token`: Indicates that the [**Client**](/#authorization) expects an [**ID Token**](/#authorization) | ||
- `grant_types` - The grant types that the [**Client**](/#authorization) will use. | ||
- `authorization_code`: Allows exchanging the [**Authorization Code**](/#authorization) for an [**Access Token**](/#authorization). | ||
- `refresh_token`: Allows exchanging the [**Refresh Token**](/#authorization) for a new [**Access Token**](/#authorization). | ||
- `redirect_uri` - A list of URIs to which the [**Authorization Server**](/#authorization) will send the user-agent (browser) after completing the authorization step | ||
|
||
If the creation was successful, the response will return a `201` status code. | ||
The response body will contain a **`client_id`** field which you will need to use in the next steps. | ||
|
||
## 2. Initialize the OAuth2 recipes on the backend | ||
|
||
|
||
In your **`backend`** application you will need to initialize both the **OAuth2Provider** and the **OAuth2Client** recipes. | ||
|
||
<BackendSDKTabs> | ||
<TabItem value="nodejs"> | ||
|
||
```typescript | ||
import supertokens from "supertokens-node"; | ||
import OAuth2Provider from"supertokens-node/recipe/oauth2provider"; | ||
import OAuth2Client from"supertokens-node/recipe/oauth2client"; | ||
|
||
supertokens.init({ | ||
framework: "express", | ||
supertokens: { | ||
connectionURI: "<YOUR_CONNECTION_URI>", | ||
apiKey: "<YOUR_API_KEY>", | ||
}, | ||
appInfo: { | ||
appName: "", | ||
apiDomain: "<YOUR_API_DOMAIN>", | ||
websiteDomain: "<YOUR_WEBSITE_DOMAIN>", | ||
apiBasePath: "/auth", | ||
websiteBasePath: "/auth" | ||
}, | ||
recipeList: [ | ||
OAuth2Provider.init(), | ||
// You will have to initialize the OAuth2Client recipe | ||
// for each of your previously created clients | ||
OAuth2Client.init({ | ||
clientId: '<CLIENT_ID>', | ||
oidcDiscoveryEndpoint: 'https://<AUTHENTICATION_SERVICE_DOMAIN>/auth/.well-known/openid-configuration' | ||
}), | ||
] | ||
}); | ||
``` | ||
|
||
</TabItem> | ||
|
||
<TabItem value="go"> | ||
|
||
:::caution | ||
|
||
At the moment we do not have support creating OAuth2 providers in the Go SDK. | ||
|
||
::: | ||
|
||
</TabItem> | ||
|
||
<TabItem value="python"> | ||
|
||
:::caution | ||
|
||
At the moment we do not have support creating OAuth2 providers in the Python SDK. | ||
|
||
::: | ||
|
||
</TabItem> | ||
|
||
</BackendSDKTabs> | ||
|
||
## 3. Initialize the recipe on the Frontend Applications | ||
|
||
:::info | ||
|
||
The `OAuth2Provider` recipe is available, at the moment, only when using the `supertokens-auth-react` package. | ||
|
||
::: | ||
|
||
Initialize the `OAuth2Provider` recipe on the frontend of each of your applications, ensuring you set the `authMode` to `header`. | ||
|
||
```tsx | ||
import OAuth2Provider from "supertokens-auth-react/recipe/oauth2provider"; | ||
import Session from "supertokens-auth-react/recipe/session"; | ||
|
||
|
||
export const SuperTokensConfig = { | ||
appInfo: { | ||
appName: "App Name", | ||
apiDomain: "<AUTHENTICATION_SERVICE_DOMAIN>", | ||
websiteDomain: "<FRONTEND_APPLICATION_DOMAIN>", | ||
}, | ||
recipeList: [ | ||
OAuth2Provider.init({ authMode: "header" }), | ||
Session.init(), | ||
], | ||
}; | ||
``` | ||
|
||
## 4. Update the login flow in your frontend applications | ||
|
||
In your `frontend applications` you will have to add a login action that will direct the user to the authentication page. | ||
You can just use a link for that. The link should be structured like this: | ||
|
||
``` | ||
<AUTHENTICATION_SERIVICE_DOMAIN>/auth/oauth/auth?client_id=<CLIENT_ID>&redirect_uri=<REDIRECT_URI> | ||
``` | ||
- `<AUTHENTICATION_SERIVICE_DOMAIN>` - The domain of your [**Authentication Service**](/docs/oauth/introduction#authentication-service). | ||
The example assumes that you didn't overwrite the default `apiBasePath`. | ||
If that's the case you will have to replace `/auth` with you custom base path. | ||
- `<CLIENT_ID>` - The corresponding client ID based on what you have created in the first step. | ||
- `<REDIRECT_URI>` - The corresponding redirect URI based on what you have created in the first step. | ||
|
||
## 5. Test the new authentication flow | ||
|
||
With everything set up, you can now test your login flow. | ||
Just use the link that you have created in the previous step and try to access a protected resource. | ||
|
||
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,9 @@ | ||
--- | ||
title: Add Custom Claims in Tokens | ||
hide_title: true | ||
--- | ||
|
||
# Add custom claims in the ID / access token | ||
|
||
If you want to properties in the token payloads you can do this by overriding either the `buildIdTokenPayload` or the `buildAccessTokenPayload` functions. | ||
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,6 @@ | ||
--- | ||
title: Implement a Custom UI | ||
hide_title: true | ||
--- | ||
|
||
# Implement a Custom UI |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,9 @@ | ||
--- | ||
title: Verify Tokens | ||
hide_title: true | ||
--- | ||
|
||
# Verify Tokens | ||
|
||
|
||
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,29 @@ | ||
--- | ||
title: Working with Scopes | ||
hide_title: true | ||
--- | ||
|
||
# Working with Scopes | ||
|
||
The allowed scopes are set during the creation process of an **OAuth2 Client**. | ||
|
||
By default, our **OAuth2** implementation adds the following built-in scopes: | ||
- `email`: adds the `email` and `email_verified` claims into the Id Token and the User Info. | ||
- `phoneNumber`: adds the `phoneNumber` and `phoneNumber_verified` claims into the Id Token and the User Info | ||
- `roles`: adds the roles claim into the Id Token and Access Token. | ||
- This will contain the roles returned by `getRolesForUser` | ||
- This only works if the `UserRoles` recipe is initialized | ||
- `permissions`: adds the `permissions` claim into the Id Token and Access Token. | ||
- This will contain the list of permissions obtained by concatenating the result of `getPermissionsForRole` for all roles returned by `getRolesForUser` | ||
- This only works if the `UserRoles` recipe is initialized | ||
|
||
## Requesting Specific Scopes | ||
|
||
The client can request specific scopes by adding `scope` query param to the Authorization URL. | ||
The requested scopes have to be a subset of what is allowed for the client, otherwise the authentication requst will fail. | ||
By default all scopes are granted to the client. | ||
|
||
## Overriding granted scopes | ||
|
||
If you want to manually modify the list of scopes that are granted to the client during the authentication flow you can do this by using overrides. | ||
You will have to add a custom implementation for `getConsentRequest` and change the value it returns for `requestedScope`. |
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
is this page relevant? Cause its not in the sidebar