Swarm/ONBOARDING_FLOW.md

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.