Skip to content
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

feat(docs): update first_screen content in auth params doc #768

Merged
merged 1 commit into from
Aug 28, 2024
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
Expand Up @@ -9,15 +9,42 @@ In addition to the parameters required by the [OpenID Connect Core specification

## First screen

<Availability cloud oss={{ major: 1, minor: 15 }} />
<Availability cloud oss={{ major: 1, minor: 20 }} />

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
Expand All @@ -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
Expand Down
Loading