Skip to content

Commit cc666aa

Browse files
xiaoyijunxiaoyijun
authored
docs: add Custom ID token docs and rename Custom token claims to Custom access token (#1359)
1 parent af311f6 commit cc666aa

File tree

13 files changed

+156
-54
lines changed

13 files changed

+156
-54
lines changed

‎docs/developers/README.mdx‎

Lines changed: 11 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -19,9 +19,18 @@ import Settings from '@site/docs/developers/assets/icons/gear.svg';
1919
items={[
2020
{
2121
type: 'link',
22-
label: 'Custom token claims',
22+
label: 'Custom access token',
2323
href: '/developers/custom-token-claims',
24-
description: 'Expand the capabilities of access control by attaching additional claims, which can help achieve ABAC or reject token issuance.',
24+
description: 'Use custom scripts to attach additional claims to access tokens, enabling ABAC or rejecting token issuance.',
25+
customProps: {
26+
icon: <JwtClaims />,
27+
}
28+
},
29+
{
30+
type: 'link',
31+
label: 'Custom ID token',
32+
href: '/developers/custom-id-token',
33+
description: 'Control which extended claims are included in ID tokens, following the OIDC specification.',
2534
customProps: {
2635
icon: <JwtClaims />,
2736
}

‎docs/developers/audit-logs/README.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
---
2-
sidebar_position: 6
2+
sidebar_position: 7
33
---
44

55
# Audit logs

‎docs/developers/custom-id-token/README.mdx‎

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
---
2+
sidebar_position: 3
3+
---
4+
5+
# Custom ID token
6+
7+
## Introduction \{#introduction}
8+
9+
[ID token](https://auth.wiki/id-token) is a special type of token defined by the [OpenID Connect (OIDC)](https://auth.wiki/openid-connect) protocol. It serves as an identity assertion issued by the authorization server (Logto) after a user successfully authenticates, carrying claims about the authenticated user's identity.
10+
11+
Unlike [access tokens](/developers/custom-token-claims) which are used to access protected resources, ID tokens are specifically designed to convey authenticated user identity to client applications. They are [JSON Web Tokens (JWTs)](https://auth.wiki/jwt) that contain claims about the authentication event and the authenticated user.
12+
13+
## How ID token claims work \{#how-id-token-claims-work}
14+
15+
In Logto, ID token claims are divided into two categories:
16+
17+
1. **Standard OIDC claims**: Defined by the OIDC specification, these claims are entirely determined by the scopes requested during authentication.
18+
2. **Extended claims**: Claims extended by Logto to carry additional identity information, controlled by a **dual-condition model** (Scope + Toggle).
19+
20+
```mermaid
21+
flowchart TD
22+
A[User authentication request] --> B{Requested scopes}
23+
B --> C[Standard OIDC scopes]
24+
B --> D[Extended scopes]
25+
C --> E[Standard claims included in ID token]
26+
D --> F{Console toggle enabled?}
27+
F -->|Yes| G[Extended claims included in ID token]
28+
F -->|No| H[Claims not included]
29+
```
30+
31+
## Standard OIDC claims \{#standard-oidc-claims}
32+
33+
Standard claims are completely governed by the OIDC specification. Their inclusion in the ID token depends solely on the scopes your application requests during authentication. Logto does not provide any option to disable or selectively exclude individual standard claims.
34+
35+
The following table shows the mapping between standard scopes and their corresponding claims:
36+
37+
| Scope | Claims |
38+
| --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
39+
| `openid` | `sub` |
40+
| `profile` | `name`, `family_name`, `given_name`, `middle_name`, `nickname`, `preferred_username`, `profile`, `picture`, `website`, `gender`, `birthdate`, `zoneinfo`, `locale`, `updated_at` |
41+
| `email` | `email`, `email_verified` |
42+
| `phone` | `phone_number`, `phone_number_verified` |
43+
| `address` | `address` |
44+
45+
For example, if your application requests the `openid profile email` scopes, the ID token will include all claims from the `openid`, `profile`, and `email` scopes.
46+
47+
## Extended claims \{#extended-claims}
48+
49+
Beyond the standard OIDC claims, Logto extends additional claims that carry identity information specific to the Logto ecosystem. These extended claims follow a **dual-condition model** to be included in the ID token:
50+
51+
1. **Scope condition**: The application must request the corresponding scope during authentication.
52+
2. **Console toggle**: The administrator must enable the claim's inclusion in the ID token through Logto Console.
53+
54+
Both conditions must be satisfied simultaneously. The scope serves as the protocol-layer access declaration, while the toggle serves as the product-layer exposure control — their responsibilities are clear and non-substitutable.
55+
56+
### Available extended scopes and claims \{#available-extended-scopes-and-claims}
57+
58+
| Scope | Claims | Description | Included by default |
59+
| ------------------------------------ | ------------------------------ | --------------------------------------- | ------------------- |
60+
| `custom_data` | `custom_data` | Custom data stored on the user object | |
61+
| `identities` | `identities`, `sso_identities` | User's linked social and SSO identities | |
62+
| `roles` | `roles` | User's assigned roles | ✅ |
63+
| `urn:logto:scope:organizations` | `organizations` | User's organization IDs | ✅ |
64+
| `urn:logto:scope:organizations` | `organization_data` | User's organization data | |
65+
| `urn:logto:scope:organization_roles` | `organization_roles` | User's organization role assignments | ✅ |
66+
67+
### Configure in Logto Console \{#configure-in-logto-console}
68+
69+
To enable extended claims in the ID token:
70+
71+
1. Navigate to <CloudLink to="/customize-jwt">Console > Custom JWT</CloudLink>.
72+
2. Toggle on the claims you want to include in the ID token.
73+
3. Ensure your application requests the corresponding scopes during authentication.
74+
75+
## Related resources \{#related-resources}
76+
77+
<Url href="/developers/custom-token-claims">Custom access token</Url>
78+
79+
<Url href="https://openid.net/specs/openid-connect-core-1_0.html#IDToken">
80+
OpenID Connect Core - ID Token
81+
</Url>

‎docs/developers/custom-token-claims/README.mdx‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,9 +2,9 @@
22
sidebar_position: 2
33
---
44

5-
# Custom token claims
5+
# Custom access token
66

7-
Logto provides the flexibility to add customize claims within access tokens (JWT / Opaque token). With this feature, you can include additional information for your business logic, all securely transmitted in the tokens and retrievable via introspection in the case of opaque tokens.
7+
Logto provides the flexibility to add custom claims within access tokens (JWT / Opaque token). With this feature, you can include additional information for your business logic, all securely transmitted in the tokens and retrievable via introspection in the case of opaque tokens.
88

99
## Introduction \{#introduction}
1010

‎docs/developers/custom-token-claims/common-use-cases.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@ sidebar_position: 2
77

88
# Common use cases
99

10-
In this section, we will provide some examples to help you understand some scenarios where [custom token claims](/developers/custom-token-claims) can be useful, offering you some references. This way, when you encounter difficulties in access management, you can assess whether custom token claims can bring you convenience.
10+
In this section, we will provide some examples to help you understand some scenarios where [custom access token claims](/developers/custom-token-claims) can be useful, offering you some references. This way, when you encounter difficulties in access management, you can assess whether custom access token claims can bring you convenience.
1111

1212
## Make attribute-based access control (ABAC) possible \{#make-attribute-based-access-control-abac-possible}
1313

‎docs/developers/custom-token-claims/create-script.mdx‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,11 @@
11
---
22
id: create-script
3-
title: Create a custom token claims script
4-
sidebar_label: Create a custom token claims script
3+
title: Create a custom access token script
4+
sidebar_label: Create a custom access token script
55
sidebar_position: 3
66
---
77

8-
# Create a custom token claims script
8+
# Create a custom access token script
99

1010
To [add custom claims](/developers/custom-token-claims) to the [access token](https://auth.wiki/access-token), you need to provide a script that returns an object containing those claims. The script should be written as a `JavaScript` function that returns an object with the custom claims.
1111

‎docs/developers/sdk-conventions/README.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
id: sdk-conventions
33
title: Platform SDK conventions
44
sidebar_label: Platform SDK conventions
5-
sidebar_position: 7
5+
sidebar_position: 8
66
---
77

88
# Platform SDK conventions

‎docs/developers/signing-keys.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
id: signing-keys
33
title: Signing keys
44
sidebar_label: Signing keys
5-
sidebar_position: 4
5+
sidebar_position: 5
66
---
77

88
# Signing keys

‎docs/developers/user-impersonation.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
id: user-impersonation
33
title: User impersonation
44
sidebar_label: User impersonation
5-
sidebar_position: 3
5+
sidebar_position: 4
66
---
77

88
import TokenExchangePrerequisites from './fragments/_token-exchange-prerequisites.mdx';

‎docs/developers/webhooks/README.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
---
2-
sidebar_position: 5
2+
sidebar_position: 6
33
---
44

55
# Webhooks

0 commit comments

Comments
 (0)