diff --git a/docs/docs/references/openid-connect/authentication-parameters/README.md b/docs/docs/references/openid-connect/authentication-parameters/README.md index eaaf1016087..87379005c51 100644 --- a/docs/docs/references/openid-connect/authentication-parameters/README.md +++ b/docs/docs/references/openid-connect/authentication-parameters/README.md @@ -9,15 +9,42 @@ In addition to the parameters required by the [OpenID Connect Core specification ## First screen - + + +This parameter allows you to customize the first screen that users see when they start the authentication process. +The value for this parameter can be: + +- `sign_in`: Allow users to directly access the sign-in page. +- `register`: Allow users to directly access the registration page. +- `single_sign_on`: Allow users to directly access the single sign-on (SSO) page. +- `identifier:sign_in`: Allow users to direct access a page that only display specific identifier-based sign-in methods to users. +- `identifier:register`: Allow users to direct access a page that only display specific identifier-based registration methods to users. +- `reset_password`: Allow users to directly access the password reset page. + +If omitted, the default value is `sign_in`. + +:::note +In OSS version, the `first_screen` parameter has been supported since version 1.15.0 for `signIn` and `register`. +However, now the `signIn` value has been deprecated and should now be replaced with `sign_in` +::: + +You can specify an additional `identifier` parameter to focus the screen on a specific identifier if you're using the following values for the `first_screen` parameter: -This parameter allows you to customize the first screen that users see when they start the authentication process. The value can be `signIn` or `register`. If omitted, the default value is `signIn`. +- `identifier:sign_in` +- `identifier:register` +- `reset_password` -Here's a non-normative example of the authentication request with the `first_screen` parameter: +Valid `identifier` values are `username`, `email`, and `phone`. Multiple identifiers can be specified by separating them with spaces. + +:::note +Unsupported identifiers in the sign-in experience configuration will be ignored. If all specified identifiers are unsupported, the default sign-in experience configuration will be used. If no identifier is supported in the sign-in experience configuration, the user will be redirected to the sign-in page. +::: + +Below is a non-normative example of an authentication request with the `first_screen` parameter: ```bash curl --location \ - --request GET 'https://[tenant-id].logto.app/oidc/auth?client_id=1234567890&...&first_screen=register' + --request GET 'https://[tenant-id].logto.app/oidc/auth?client_id=1234567890&...&first_screen=identifier:sign_in&identifier=email username' ``` :::info @@ -27,10 +54,19 @@ When `first_screen` is set, the legacy `interaction_mode` parameter is ignored. In supported Logto SDKs, you can set the `firstScreen` property when calling the `signIn` method: ```ts title="JavaScript" +/* For register screen */ logtoClient.signIn({ redirectUri: 'https://your-app.com/callback', firstScreen: 'register', }); + +/* For identifier sign-in screen */ +logtoClient.signIn({ + redirectUri: 'https://your-app.com/callback', + firstScreen: 'identifier:sign_in', + /* JavaScript SDK using `identifiers` option to specify the `identifier` parameter */ + identifiers: ['email', 'username'], +}); ``` :::note