64 lines
2.9 KiB
Markdown
64 lines
2.9 KiB
Markdown
# Client-Side Onboarding Flow for New Users
|
|
|
|
This document outlines the steps for a client application to handle the onboarding of new users who authenticate via a third-party provider.
|
|
|
|
## 1. Initiate the OIDC Login Flow
|
|
|
|
This step remains the same as a standard OIDC authorization code flow. The client application redirects the user to the `/authorize` endpoint of the authentication server with the required parameters (`response_type=code`, `client_id`, `redirect_uri`, `scope`, etc.).
|
|
|
|
## 2. Handle the Token Response
|
|
|
|
After the user authenticates with the third-party provider and is redirected back to the client, the client will have an `authorization_code`. The client then exchanges this code for tokens at the `/token` endpoint.
|
|
|
|
The response from the `/token` endpoint will differ for new and existing users.
|
|
|
|
### For Existing Users
|
|
|
|
If the user already has an account, the token response will be a standard OIDC token response, containing:
|
|
- `access_token`
|
|
- `id_token`
|
|
- `refresh_token`
|
|
- `expires_in`
|
|
- `token_type: "Bearer"`
|
|
|
|
The client should proceed with the standard login flow.
|
|
|
|
### For New Users
|
|
|
|
If the user is new, the token response will contain a special `onboarding_token`:
|
|
- `onboarding_token`: A JWT containing information about the new user from the external provider.
|
|
- `token_type: "Onboarding"`
|
|
|
|
The presence of the `onboarding_token` is the signal for the client to start the new user onboarding flow.
|
|
|
|
## 3. Process the Onboarding Token
|
|
|
|
The `onboarding_token` is a JWT. The client should decode it to access the claims, which will include:
|
|
|
|
- `provider`: The name of the external provider (e.g., "Google", "Facebook").
|
|
- `provider_user_id`: The user's unique ID from the external provider.
|
|
- `email`: The user's email address (if available).
|
|
- `name`: The user's full name from the external provider (if available).
|
|
- `nonce`: The nonce from the initial authorization request.
|
|
|
|
Using this information, the client can now guide the user through a custom onboarding process. For example, it can pre-fill a registration form with the user's name and email, and prompt the user to choose a unique username for their new account.
|
|
|
|
## 4. Complete the Onboarding
|
|
|
|
To finalize the account creation, the client needs to send the collected information to the server. This requires a new API endpoint on the server that is not part of this change.
|
|
|
|
**Example Endpoint:** `POST /api/account/onboard`
|
|
|
|
The client would send a request to this endpoint, including:
|
|
- The `onboarding_token`.
|
|
- The username chosen by the user.
|
|
- Any other required information.
|
|
|
|
The server will validate the `onboarding_token` and create a new user account with the provided details.
|
|
|
|
## 5. Finalize Login
|
|
|
|
Upon successful account creation, the server's onboarding endpoint should return a standard set of OIDC tokens (`access_token`, `id_token`, `refresh_token`) for the newly created user.
|
|
|
|
The client can then use these tokens to log the user in, completing the onboarding and login process.
|