From 0d5401667001eb610f34f7648c80c421a8c04df9 Mon Sep 17 00:00:00 2001 From: Rany Date: Wed, 29 Oct 2025 14:29:07 +0800 Subject: [PATCH 1/3] chore: update doc details from feedback --- docs/authorization/global-api-resources.mdx | 30 ++++++++++++++++++ docs/customization/localized-languages.mdx | 13 ++++++++ .../account-settings/by-account-api.mdx | 12 ++++++- .../first-screen.mdx | 10 ++++-- .../authentication-parameters/ui-locales.mdx | 1 + .../sign-up-and-sign-in/sign-in.mdx | 3 +- .../sign-up-and-sign-in/sign-up.mdx | 10 ++++++ .../application-data-structure.mdx | 4 +++ .../README.mdx | 15 +++++++++ .../third-party-applications/README.mdx | 4 +-- docs/logto-cloud/custom-domain.mdx | 31 +++++++++++++++++++ docs/logto-oss/get-started-with-oss.mdx | 4 +++ docs/secret-vault/federated-token-set.mdx | 2 +- docs/user-management/manage-users.mdx | 11 +++++-- docs/user-management/user-data.mdx | 4 +++ 15 files changed, 144 insertions(+), 10 deletions(-) diff --git a/docs/authorization/global-api-resources.mdx b/docs/authorization/global-api-resources.mdx index 23ae3a12670..9e0db69028a 100644 --- a/docs/authorization/global-api-resources.mdx +++ b/docs/authorization/global-api-resources.mdx @@ -245,6 +245,36 @@ Use a [personal access token](/user-management/personal-access-token) to simulat +
+ + +### Can I use scope prefixes or shortened versions when requesting permissions? \{#can-i-use-scope-prefixes-or-shortened-versions} + + + +No. Scope names must **exactly match** the permission names defined in your API resource. Prefixes and shortened versions do not work as wildcards. + +**Example:** + +If your API resource defines: + +- `read:elections` +- `write:elections` + +You must request: + +```swift +scopes: ["read:elections", "write:elections"] +``` + +This will **NOT work**: + +```swift +scopes: ["read", "write"] // ❌ Doesn't match permission names +``` + +
+ ## Further reading \{#further-reading} How to validate access tokens diff --git a/docs/customization/localized-languages.mdx b/docs/customization/localized-languages.mdx index 0d0a270c0e7..699d153e4d2 100644 --- a/docs/customization/localized-languages.mdx +++ b/docs/customization/localized-languages.mdx @@ -99,6 +99,19 @@ Suppose, that you only want to make adjustments to a subset of the original cont +
+ + +### How can I set a default phone number country code for the sign-in experience? \{#how-can-i-set-a-default-phone-number-country-code-for-the-sign-in-experience} + + + +The phone number country code in the [sign-in experience](/end-user-flows/sign-up-and-sign-in/sign-up) defaults to the user's browser locale. For example, if a user's browser language is set to `fr`, the country code will default to France (+33). + +To programmatically control the default country code for specific users or regions, you can use the [`ui_locales`](/end-user-flows/authentication-parameters/ui-locales) authentication parameter. For instance, setting `ui_locales=ja` will default the country code to Japan (+81). + +
+ ## Related resources \{#related-resources} diff --git a/docs/end-user-flows/account-settings/by-account-api.mdx b/docs/end-user-flows/account-settings/by-account-api.mdx index 7da48af3f32..4c7eea52e33 100644 --- a/docs/end-user-flows/account-settings/by-account-api.mdx +++ b/docs/end-user-flows/account-settings/by-account-api.mdx @@ -353,7 +353,17 @@ curl -X PATCH https://[tenant-id].logto.app/api/account-center \ --data-raw '{"webauthnRelatedOrigins":["https://account.example.com"]}' ``` -To learn more about the related origins, please refer to [Related Origin Requests](https://passkeys.dev/docs/advanced/related-origins/) documentation. +:::note + +WebAuthn supports up to 5 unique eTLD+1 labels for Related Origins. The eTLD+1 (effective top-level domain plus one label) is the registrable domain portion. For example: + +- `https://example.com`, `https://app.example.com`, and `https://auth.example.com` count as **one** label (`example.com`) +- `https://shopping.com`, `https://shopping.co.uk`, and `https://shopping.co.jp` also count as **one** label (`shopping`) +- `https://example.com` and `https://another.com` count as **two** labels + +If you need to support more than 5 different domains as the Related Origins, refer to the [Related Origin Requests](https://passkeys.dev/docs/advanced/related-origins/) documentation for details. + +::: **Step 2: Request new registration options** diff --git a/docs/end-user-flows/authentication-parameters/first-screen.mdx b/docs/end-user-flows/authentication-parameters/first-screen.mdx index 227f37978a0..c488ebf9fb8 100644 --- a/docs/end-user-flows/authentication-parameters/first-screen.mdx +++ b/docs/end-user-flows/authentication-parameters/first-screen.mdx @@ -14,12 +14,12 @@ A set to custom authentication parameters that allow you to tailor the desired f The `first_screen` parameter is the key parameter that determines the first screen that the users will see when they redirect to the Logto's sign-in page. By default, the universal sign-in form will be displayed. Use this parameter to customize the first screen based on your application's requirements. Supported values are: -- `sign_in`: Displays the sign-in form. (Default) +- `sign_in`(Default): Displays the sign-in form. - `register`: Displays the sign-up form. - `reset_password`: Displays the password reset form. - `single_sign_on`: Displays the enterprise SSO sign-in form. (A email address will be asked to determine the enabled SSO providers) -- `identifier:sign-in`: Displays a identifier specific sign-in form. The identifier type can be specified using the `identifier` parameter. This is useful when you have multiple identifier sign-in methods enabled. -- `identifier:register`: Displays a identifier specific sign-up form. The identifier type can be specified using the `identifier` parameter. This is useful when you have multiple identifier sign-up methods enabled. +- `identifier:sign-in`: Displays a identifier specific sign-in form. The identifier type can be specified using the `identifier` parameter (optional). This is useful when you have multiple identifier sign-in methods enabled. +- `identifier:register`: Displays a identifier specific sign-up form. The identifier type can be specified using the `identifier` parameter (optional). This is useful when you have multiple identifier sign-up methods enabled. First screen parameter @@ -30,6 +30,10 @@ curl --location \ --request GET 'https://.logto.app/oidc/auth?client_id=&...&first_screen=single_sign_on' ``` +:::tip +The first screen will follow the settings configured in Console > Sign-in experience. You need to enable the required authentication methods first, and configure branding, terms and privacy policies, and internationalization (i18n). Note that only the `sign-in` and `register` pages display the logo by default. +::: + ## identifier \{#identifier} The `identifier` parameter is used to specify the identifier types that the sign-in or sign-up form will take. This parameter is only applicable when the `first_screen` parameter is set to `identifier:sign-in`, `identifier:register`, or `reset_password`. Supported values are: `username`, `email`, and `phone`. Separate multiple values with a empty space to allow multiple identifier types. diff --git a/docs/end-user-flows/authentication-parameters/ui-locales.mdx b/docs/end-user-flows/authentication-parameters/ui-locales.mdx index 190755f74fa..fb47c21a722 100644 --- a/docs/end-user-flows/authentication-parameters/ui-locales.mdx +++ b/docs/end-user-flows/authentication-parameters/ui-locales.mdx @@ -11,6 +11,7 @@ Logto supports the standard OIDC authentication parameter `ui_locales` to contro - Determines the UI language of the Logto-hosted sign-in experience at runtime. Logto picks the first language tag in `ui_locales` that is supported in your tenant's language library. - Affects email localization for messages triggered by the interaction (e.g., verification code emails). See [Email template localization](/connectors/email-connectors/email-templates#email-template-localization). - Exposes the original value to email templates as a variable `uiLocales`, allowing you to include it in the email subject/content if needed. +- Sets the default phone number country code in the sign-in experience. For example, if `ui_locales=fr`, the phone number input field will default to France (+33). This is useful when you want to control the default country code programmatically for specific user groups or regions. ## Parameter format \{#parameter-format} diff --git a/docs/end-user-flows/sign-up-and-sign-in/sign-in.mdx b/docs/end-user-flows/sign-up-and-sign-in/sign-in.mdx index 71fe48680e9..c333b236946 100644 --- a/docs/end-user-flows/sign-up-and-sign-in/sign-in.mdx +++ b/docs/end-user-flows/sign-up-and-sign-in/sign-in.mdx @@ -36,7 +36,8 @@ If both factors are enabled, users can choose either method to complete the sign The sign-in experience adapts based on the chosen identifier and available authentication factors. - **Smart input for multiple identifiers:** - If more than one identifier sign-in method is enabled, Logto build-in sign-in page will automatically detect the type of identifier entered by the user and display the corresponding verification options. For example, if both **Email address** and **Phone number** are enabled, the sign-in page will automatically detect the type of identifier entered by the user and display the corresponding verification options. It switches to a phone number format with region code if numbers are entered consecutively or an email format when a “@” symbol is used. + If more than one identifier sign-in method is enabled, Logto build-in sign-in page will automatically detect the type of identifier entered by the user and display the corresponding verification options. For example, if both **Email address** and **Phone number** are enabled, the sign-in page will automatically detect the type of identifier entered by the user and display the corresponding verification options. It switches to a phone number format with region code if numbers are entered consecutively or an email format when a "@" symbol is used. + - The phone number country code defaults to the user's browser locale; users can switch manually. You can use the [`ui_locales`](/end-user-flows/authentication-parameters/ui-locales) parameter to set a specific default country code. See [Localized languages](/customization/localized-languages#how-can-i-set-a-default-phone-number-country-code-for-the-sign-in-experience) for more details. - **Enabled verification factors:** - **Password only:** Both identifier and password fields will be displayed on the first screen. - **Verification code only:** The identifier field appears on the first screen, followed by the verification code field on the second screen. diff --git a/docs/end-user-flows/sign-up-and-sign-in/sign-up.mdx b/docs/end-user-flows/sign-up-and-sign-in/sign-up.mdx index c70948cac10..b876e650824 100644 --- a/docs/end-user-flows/sign-up-and-sign-in/sign-up.mdx +++ b/docs/end-user-flows/sign-up-and-sign-in/sign-up.mdx @@ -25,6 +25,16 @@ If no identifiers are selected, it applies to the [social](/end-user-flows/sign- You can adjust the order of sign-up identifiers to prioritize the one you want users to provide first during sign-up. This order is reflected in the sign-up process, where the first identifier appears on the initial registration screen, and the rest are collected in subsequent steps. +:::tip +To block specific types of email addresses during sign-up (such as disposable emails, subaddressing with plus signs (+), specific email addresses, or entire domains), use the **blocklist** feature in the Security section. See [Blocklist](/security/blocklist) for more details. +::: + +:::tip +The phone number **country code** defaults to the user's browser locale. For example, if a user's browser language is set to `fr`, the country code will default to France (+33). + +You can also use the [`ui_locales`](/end-user-flows/authentication-parameters/ui-locales) authentication parameter to set the sign-in experience language, which will also determine the default country code. +::: + ## Set up the sign-up verification settings \{#set-up-the-sign-up-verification-settings} To ensure the security of the user sign-up and future sign-in process, you also need to configure the verification settings for the identifiers that you collect during the sign-up process. The available settings are: diff --git a/docs/integrate-logto/application-data-structure.mdx b/docs/integrate-logto/application-data-structure.mdx index e85de72b97b..5b0f5ce3eab 100644 --- a/docs/integrate-logto/application-data-structure.mdx +++ b/docs/integrate-logto/application-data-structure.mdx @@ -33,6 +33,10 @@ An _Application_ can be one of the following application types: _Application secret_ is a key used to authenticate the application in the authentication system, specifically for private clients (Traditional Web and M2M apps) as a private security barrier. +:::tip +Single Page Apps (SPAs) and Native apps don't provide App secret. SPAs and Native apps are "public clients" and cannot keep secrets (browser code or app bundles are inspectable). Instead of an app secret, Logto protects them with PKCE, strict redirect URI/CORS validation, short-lived access tokens, and refresh-token rotation. +::: + ### Application name \{#application-name} _Application name_ is a human-readable name of the application and will be displayed in the admin console. diff --git a/docs/integrate-logto/integrate-logto-into-your-application/README.mdx b/docs/integrate-logto/integrate-logto-into-your-application/README.mdx index fc6f8ca04e0..23adc7f6f23 100644 --- a/docs/integrate-logto/integrate-logto-into-your-application/README.mdx +++ b/docs/integrate-logto/integrate-logto-into-your-application/README.mdx @@ -25,6 +25,21 @@ The guide in the console is only for quick start with Logto using our SDK. For c Authorization Organizations +## FAQs + +
+ + ### How can my backend service validate user tokens and manage users with Logto? + +To securely validate access tokens in your backend API (e.g., Python, Node.js, Go, Java, PHP, etc.), and to programmatically manage users, please refer to the guide: [How to validate access tokens in your API service or backend](/authorization/validate-access-tokens). + +This documentation covers: + +- How to check the validity of bearer tokens in every API call +- Best practices for integrating Logto with multiple frontend apps and a backend service + +
+ ## Related resources \{#related-resources} diff --git a/docs/integrate-logto/third-party-applications/README.mdx b/docs/integrate-logto/third-party-applications/README.mdx index de25978b25d..42f58ec4efe 100644 --- a/docs/integrate-logto/third-party-applications/README.mdx +++ b/docs/integrate-logto/third-party-applications/README.mdx @@ -22,8 +22,8 @@ Thus due to OIDC builds upon [OAuth 2.0](https://auth.wiki/oauth-2.0) adding an ## Create an third-party application in Logto \{#create-an-third-party-application-in-logto} -1. Go to Console > Applications -2. Select "Third-party app" as the application type and choose one of the following integration protocols: +1. Go to Console > Applications. +2. Click on the "Create application" button. Select "Third-party app" as the application type and choose one of the following integration protocols: - OIDC / OAuth 3. Enter a name and description for your application and click on the “Create” button. A new third-party application will be created. diff --git a/docs/logto-cloud/custom-domain.mdx b/docs/logto-cloud/custom-domain.mdx index c23663bc142..e92d32410e1 100644 --- a/docs/logto-cloud/custom-domain.mdx +++ b/docs/logto-cloud/custom-domain.mdx @@ -75,6 +75,37 @@ If your domain is hosted on Cloudflare, disable the Cloudflare proxy for the CNA +
+ + +### "Redirect URI does not match" error after setting up custom domain \{#redirect-uri-mismatch} + + + +If you get a "redirect URI does not match" error after adding your custom domain, you need to update your SDK configuration to use the custom domain as the endpoint. + +**About "primary domain":** + +There is no separate "primary domain" setting in Logto. After adding a custom domain, both your custom domain and the default `{tenant-id}.logto.app` domain remain valid. The domain you configure in your SDK's `endpoint` parameter determines which domain will be used for authentication flows. + +**Solution:** + +Update the `endpoint` parameter in your SDK initialization to use your custom domain: + +```typescript +const client = new LogtoClient({ + endpoint: 'https://auth.example.com', // Use your custom domain + appId: 'your-app-id', + // ... other options +}); +``` + +Also verify that the redirect URIs registered in Console → Applications match the domain you're using. + +**Note:** Logto automatically provisions and manages SSL certificates for your custom domain. You don't need to configure your own certificates. + +
+ ## Use custom domain \{#use-custom-domain} Once you've configured your settings, both your custom domain name and the default Logto domain name will be available for your tenant. However, certain configurations are required to activate your custom domain name. diff --git a/docs/logto-oss/get-started-with-oss.mdx b/docs/logto-oss/get-started-with-oss.mdx index f85552fab43..0c07b44ef3a 100644 --- a/docs/logto-oss/get-started-with-oss.mdx +++ b/docs/logto-oss/get-started-with-oss.mdx @@ -277,6 +277,10 @@ Please note that we do not provide customer support for third-party service prov Once you have successfully hosted Logto on your server, click on "Create account" on the welcome page. Keep in mind that the open-source version of Logto only allows for one account creation during the initial launch and does not support multiple accounts. The account creation process is limited to username and password combinations. +:::tip +Logto OSS (self-hosted) does not support configuring multiple administrators. For team collaboration and projects requiring multiple admin users, we recommend using [Logto Cloud](https://cloud.logto.io), which provides full team management features. +::: + ## Related resources \{#related-resources} Dealing with local HTTPS development diff --git a/docs/secret-vault/federated-token-set.mdx b/docs/secret-vault/federated-token-set.mdx index 0c15489848d..12846657107 100644 --- a/docs/secret-vault/federated-token-set.mdx +++ b/docs/secret-vault/federated-token-set.mdx @@ -101,7 +101,7 @@ Once token storage is enabled and tokens are securely stored in Logto’s secret - `GET /my-account/sso-identities/:connectorId/access-token`: Retrieve the access token for an enterprise SSO identity by specifying the connector ID. :::info -Learn how to [enable](/end-user-flows/account-settings/by-account-api#how-to-enable-account-api) and [access](/end-user-flows/account-settings/by-account-api#access-account-api-using-access-token) the Account API using the Logto issued access token. +To retrieve third-party access tokens, you must first enable the Account API for end users at Console > Sign-in & Account > Account center. Learn how to [enable the Account API](/end-user-flows/account-settings/by-account-api#how-to-enable-account-api) and [access it using a Logto-issued access token](/end-user-flows/account-settings/by-account-api#access-account-api-using-access-token). ::: ### Token rotation \{#token-rotation} diff --git a/docs/user-management/manage-users.mdx b/docs/user-management/manage-users.mdx index 5f2faa16de6..5313a240fb8 100644 --- a/docs/user-management/manage-users.mdx +++ b/docs/user-management/manage-users.mdx @@ -43,10 +43,17 @@ To view the details of a user, simply click on the corresponding row in the user - **Phone number** ([primary_phone](/user-management/user-data#primary_phone)): Editable - **Username** ([username](/user-management/user-data#username)): Editable - **Password** ([has_password](/user-management/user-data#has_password)): You can regenerate a random password. Learn more about "[Reset user password](#reset-user-password)". - - **Social connections** ([identities](/user-management/user-data#social-identities)): View linked social accounts and social IDs. For example, if the user has signed in using their Facebook account, you will see a "Facebook" item in the list. You can remove a linked social identity in the Console. But you cannot link a new one on behalf of the end user. - - **Enterprise SSO connections** ([sso_identities](/user-management/user-data#sso-identities)): View linked enterprise identities. You cannot add or remove SSO identities in the Console. - **Multi-factor authentication** ([mfa_verification_factor](/user-management/user-data#mfa_verification_factors)): View all authentication factors (e.g., passkeys, authenticator apps, backup codes) this user has set up. Factors can be removed in the Console. - **Personal access token**: Create, view, rename, and delete [personal access tokens](/user-management/personal-access-token). +- **Connection**: + - **Social connections** ([identities](/user-management/user-data#social-identities)): + - View the user's linked social accounts, including social IDs and profile details synced from their social providers (e.g., a "Facebook" entry will appear if the user signed in via Facebook). + - You can remove existing social identities, but you cannot link new social accounts on behalf of the user. + - For social connectors with [token storage](/secret-vault/federated-token-set) enabled, you can view and manage access tokens and refresh tokens in the connection detail page. + - **Enterprise SSO connections** ([sso_identities](/user-management/user-data#sso-identities)): + - View the user's linked enterprise identities, including enterprise IDs and profile details synced from their enterprise identity providers. + - You cannot add or remove enterprise SSO identities in the Console. + - For OIDC-based enterprise connectors with [token storage](/secret-vault/federated-token-set) enabled, you can view and delete tokens in the connection detail page. - **User profile data**: name, avatar URL, custom data, and additional OpenID Connect standard claims that are not included. All these profile fields are editable. :::warning diff --git a/docs/user-management/user-data.mdx b/docs/user-management/user-data.mdx index 76e384bf3d3..de8e0f8ed0e 100644 --- a/docs/user-management/user-data.mdx +++ b/docs/user-management/user-data.mdx @@ -70,12 +70,16 @@ _primary_email_ is the user's email address, used for sign-in with the email and Its value is usually from the email address that the user first registered with. It may be `null`. Its max length is 128. +Only verified email addresses from social or enterprise SSO identity providers can be synced and saved as the `primary_email`. + ### primary_phone \{#primary_phone} _primary_phone_ is the user's phone number, used for sign-in with the phone number and password / verification code from SMS. Its value is usually from the phone number that the user first registered with. It may be `null`. Its non-null value should contain numbers prefixed with the [country calling code](https://en.wikipedia.org/wiki/List_of_country_calling_codes) (excluding the plus sign `+`). +Only verified phone number from social or enterprise SSO identity providers can be synced and saved as the `primary_phone`. + ### name \{#name} _name_ is the user's full name. Its max length is 128. From 2a34e38945d7e11f8ecf109ca77068cb59b288c7 Mon Sep 17 00:00:00 2001 From: Rany Date: Thu, 30 Oct 2025 22:31:27 +0800 Subject: [PATCH 2/3] chore: update docs/user-management/user-data.mdx Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- docs/user-management/user-data.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/user-management/user-data.mdx b/docs/user-management/user-data.mdx index de8e0f8ed0e..ef947a11986 100644 --- a/docs/user-management/user-data.mdx +++ b/docs/user-management/user-data.mdx @@ -78,7 +78,7 @@ _primary_phone_ is the user's phone number, used for sign-in with the phone numb Its value is usually from the phone number that the user first registered with. It may be `null`. Its non-null value should contain numbers prefixed with the [country calling code](https://en.wikipedia.org/wiki/List_of_country_calling_codes) (excluding the plus sign `+`). -Only verified phone number from social or enterprise SSO identity providers can be synced and saved as the `primary_phone`. +Only verified phone numbers from social or enterprise SSO identity providers can be synced and saved as the `primary_phone`. ### name \{#name} From 87e57233d372a87f11026f8a757a49f682b8ba17 Mon Sep 17 00:00:00 2001 From: Rany Date: Thu, 30 Oct 2025 22:31:43 +0800 Subject: [PATCH 3/3] chore: update docs/end-user-flows/authentication-parameters/first-screen.mdx Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- docs/end-user-flows/authentication-parameters/first-screen.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/end-user-flows/authentication-parameters/first-screen.mdx b/docs/end-user-flows/authentication-parameters/first-screen.mdx index c488ebf9fb8..dbd9a881d90 100644 --- a/docs/end-user-flows/authentication-parameters/first-screen.mdx +++ b/docs/end-user-flows/authentication-parameters/first-screen.mdx @@ -14,7 +14,7 @@ A set to custom authentication parameters that allow you to tailor the desired f The `first_screen` parameter is the key parameter that determines the first screen that the users will see when they redirect to the Logto's sign-in page. By default, the universal sign-in form will be displayed. Use this parameter to customize the first screen based on your application's requirements. Supported values are: -- `sign_in`(Default): Displays the sign-in form. +- `sign_in` (Default): Displays the sign-in form. - `register`: Displays the sign-up form. - `reset_password`: Displays the password reset form. - `single_sign_on`: Displays the enterprise SSO sign-in form. (A email address will be asked to determine the enabled SSO providers)