Skip to content

Commit 2b0cc15

Browse files
Rany0101charIeszhaoCopilot
authored
docs(console): update microsoft entra id oidc and okta readme (#7702)
* chore: update microsoft entra id oidc and okta readme Update enterprise SSO connector README for token storage: 1. Microsoft Entra ID (OIDC) 2. Okta * fix: typos Co-authored-by: Copilot <[email protected]> --------- Co-authored-by: Charles Zhao <[email protected]> Co-authored-by: Copilot <[email protected]>
1 parent 294b501 commit 2b0cc15

File tree

3 files changed

+80
-7
lines changed

3 files changed

+80
-7
lines changed

‎packages/console/src/assets/docs/single-sign-on/azure-oidc/README.mdx‎

Lines changed: 47 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@ import configApplication from './assets/config_application.webp';
66
import applicationDetails from './assets/application_details.webp';
77
import createSecret from './assets/create_secret.webp';
88
import endpoints from './assets/endpoints.webp';
9+
import permissions from './assets/add_api_permissions.webp';
910

1011
<Step index={0} title="Create an Microsoft EntraID OIDC application">
1112

@@ -69,9 +70,53 @@ Click `Save` to finish the configuration process
6970

7071
</Step>
7172

72-
<Step index={2} title="Set email domains and enable the SSO connector">
73+
<Step index={2} title="Additional scopes (Optional)">
7374

74-
Provide the email `domains` of your organization on the connector `experience` tab. This will enabled the SSO connector as an authentication method for those users.
75+
Scopes define the permissions your app requests from users and control which data your app can access from their Microsoft Entra ID accounts. Requesting Microsoft Graph permissions requires configuration on both sides:
76+
77+
**In Microsoft Entra admin center:**
78+
79+
1. Navigate to **Microsoft Entra ID > App registrations** and select your application.
80+
2. Go to **API permissions > Add a permission > Microsoft Graph > Delegated permissions**.
81+
3. Select only the permissions your app requires:
82+
- OpenID permissions:
83+
- `openid` (Required) - Sign users in
84+
- `profile` (Required) - View users' basic profile
85+
- `email` (Required) - View users' email address
86+
- `offline_access` (Optional) - Required only if you enable **Store tokens for persistent API access** in the Logto connector and need to obtain refresh tokens for long-lived access to Microsoft Graph APIs.
87+
- API access (Optional): Add any additional permissions needed for your app. Common Microsoft Graph permissions include `Mail.Read`, `Calendars.Read`, `Files.Read`, etc. Browse the [Microsoft Graph permissions reference](https://docs.microsoft.com/en-us/graph/permissions-reference) to find available permissions.
88+
4. Click **Add permissions** to confirm the selection.
89+
5. If your app requires admin consent for certain permissions, click **Grant admin consent for [Your Organization]**.
90+
91+
<center>
92+
<img src={permissions} alt="Add Microsoft API permissions" />
93+
</center>
94+
95+
**In Logto Microsoft Entra ID connector:**
96+
97+
1. Logto automatically includes `openid`, `profile`, and `email` scopes to retrieve basic user identity information. You can leave the `Scopes` field blank if you only need basic user information.
98+
2. Add `offline_access` to the `Scopes` field if you plan to store tokens for persistent API access. This scope enables refresh tokens for long-lived API access.
99+
3. Add additional scopes (separated by spaces) in the `Scopes` field to request more data from Microsoft Graph. Use standard scope names, for example: `User.Read Mail.Read Calendars.Read`
100+
101+
**Tip**: If your app requests these scopes to access the Microsoft Graph API and perform actions, make sure to enable **Store tokens for persistent API access** in Logto Microsoft Entra ID connector. See the next section for details.
102+
103+
</Step>
104+
105+
106+
<Step index={3} title="Store tokens to access Microsoft APIs (Optional)">
107+
108+
If you want to access [Microsoft Graph APIs](https://docs.microsoft.com/en-us/graph/api/overview) and perform actions with user authorization, Logto needs to get specific API scopes and store tokens.
109+
110+
1. Add the required scopes in your Microsoft Entra admin center API permissions configuration and Logto Microsoft Entra ID connector.
111+
2. Enable **Store tokens for persistent API access** in Logto Microsoft Entra ID connector. Logto will securely store Microsoft access and refresh tokens in the Secret Vault.
112+
3. To ensure refresh tokens are returned, add the `offline_access` scope to your Microsoft Entra ID application permissions and include it in your Logto Microsoft Entra ID connector scopes. This scope allows your application to maintain access to resources for extended periods.
113+
114+
</Step>
115+
116+
117+
<Step index={4} title="Set email domains and enable the SSO connector">
118+
119+
Provide the email `domains` of your organization on the connector `experience` tab. This will enable the SSO connector as an authentication method for those users.
75120

76121
Users with email addresses in the specified domains will be exclusively limited to use your SSO connector as their only authentication method.
77122

‎packages/console/src/assets/docs/single-sign-on/azure-oidc/assets/add_api_permissions.webp‎

200 KB
Loading

‎packages/console/src/assets/docs/single-sign-on/okta/README.mdx‎

Lines changed: 33 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -64,17 +64,45 @@ If the `issuer` link you provided is valid, you will see a parsed full list of O
6464

6565
</Step>
6666

67-
<Step index={4} title="Additional Scopes (Optional)">
67+
<Step index={4} title="Additional scopes (Optional)">
6868

69-
Use the `Scope` field to add additional scopes to your OAuth request. This will allow you to request for more information from the Okta OAuth server. Please refer to the [Okta documentation](https://developer.okta.com/docs/reference/api/oidc/#scopes) for more details about the available scopes.
69+
Scopes define the permissions your app requests from users and control which data your app can access from their Okta accounts. Requesting additional Okta permissions requires configuration on both sides:
7070

71-
\*Regardless of the custom scope settings, Logto will always send the `openid`, `profile` and `email` scopes to the IdP. This is to ensure that Logto can retrieve the user's identity information and email address properly.
71+
**In Okta admin console:**
72+
73+
1. Navigate to **Applications > Applications** and select your OIDC application.
74+
2. Go to the **Assignments** tab to ensure your app has access to the required users and groups.
75+
3. For custom scopes, navigate to **Security > API > Authorization Servers** and select your authorization server.
76+
4. Add custom scopes if needed:
77+
- Click **Scopes** and then **Add Scope**
78+
- Define scope names like `okta.users.read` or `okta.groups.read` for accessing Okta APIs
79+
- Configure consent requirements for each scope
80+
81+
For a complete list of available scopes and their descriptions, please refer to the [Okta OIDC documentation](https://developer.okta.com/docs/api/openapi/okta-oauth/guides/overview/#scopes).
82+
83+
**In Logto Okta connector:**
84+
85+
1. Logto automatically includes `openid`, `profile`, and `email` scopes to retrieve basic user identity information. You can leave the `Scopes` field blank if you only need basic user information.
86+
2. Add `offline_access` to the `Scopes` field if you plan to store tokens for persistent API access. This scope enables refresh tokens for long-lived API access.
87+
3. Add additional scopes (separated by spaces) in the `Scopes` field to request more data from Okta. For example: `okta.users.read okta.groups.read`
88+
89+
**Tip:** If your app requests these scopes to access Okta APIs and perform actions, make sure to enable **Store tokens for persistent API access** in Logto Okta connector. See the next section for details.
90+
91+
</Step>
92+
93+
<Step index={5} title="Store tokens to access Okta APIs (Optional)">
94+
95+
If you want to access [Okta scopes](https://developer.okta.com/docs/guides/request-user-consent/main/#enable-consent-for-scopes) and perform actions with user authorization, Logto needs to get specific scopes and store tokens.
96+
97+
1. Add the required scopes in your Okta developer console API permissions configuration and Logto Okta connector.
98+
2. Enable **Store tokens for persistent API access** in Logto Okta connector. Logto will securely store Okta access and refresh tokens in the Secret Vault.
99+
3. To ensure refresh tokens are returned, add the `offline_access` scope to your Okta application permissions and include it in your Logto Okta connector scopes. This scope allows your application to maintain access to resources for extended periods.
72100

73101
</Step>
74102

75-
<Step index={5} title="Set email domains and enable the SSO connector">
103+
<Step index={6} title="Set email domains and enable the SSO connector">
76104

77-
Provide the email `domains` of your organization on the connector `experience` tab. This will enabled the SSO connector as an authentication method for those users.
105+
Provide the email `domains` of your organization on the connector `experience` tab. This will enable the SSO connector as an authentication method for those users.
78106

79107
Users with email addresses in the specified domains will be exclusively limited to use your SSO connector as their only authentication method.
80108

0 commit comments

Comments
 (0)