How it works: OIDC Flow with QR Code
This document explains our modified OpenID Connect (OIDC) flow that incorporates QR code scanning for a seamless user experience across devices.
Client app initiates the flow
The client application (typically a web app) redirect the user to the Authorization Server's /authorize endpoint. This can be done by redirecting the user in the same tab, opening a new tab, or opening an iframe. Check the Authorize endpoint documentation for more details.
It's crucial to ensure that the client ID, redirect URI, state parameter, and other parameters are correctly set in this request. The state parameter should be included here and validated later to prevent CSRF attacks.
Authorization Server generates session URL
The Authorization Server creates a unique session, together with more useful information to use for displaying the modal. Also sets the session status to initialized.
Ensure that the session URL is short-lived and single-use to prevent potential replay attacks.
Authorization Client displays QR code
The authorization client app displays the QR code containing the session URL with the additional information (scopes, etc..). This QR code serves as a bridge between the web app and the mobile app.
If the session expires, the refetch the session URL from the Authorization Server and update the QR code displayed on the web app. This ensures that the user can still scan the QR code and complete the flow.Check Worldcoin for an example: https://docs.worldcoin.org/try (opens in a new tab)
User scans QR code
The user scans the QR code displayed on the client app. This action transfers the session information to the Didit's native app.
Didit Native app processes the session URL
Upon scanning, the mobile app extracts and opens the session URL, establishing a connection with the Authorization Server, and ask the authorization server /session/{session_id}/information endpoint for more information regarding the session, to display a confirmation screen.
The authorization server will update the sessions status to retrieved so we can display in the UI of the website something like "Confirming data sharing request".
Mobile app returns session info
The mobile app returns the session information to the user, including the requested scopes and data sharing details. The user can review this information and decide whether to proceed with the data sharing request.
Didit native app presents confirmation screen
The Didit's native app displays a screen in the mobile app, asking the user to confirm the data sharing request. This screen typically shows which data will be shared and with whom.
Ensure that requested scopes are clearly presented to the user during this confirmation step.
User confirms data sharing
The user reviews the information and confirms their willingness to share the requested data. The mobile app sends a POST request to the Didit API's /session/{session_id}/update endpoint. This request includes:
- The user's access token for authentication
- The session identifier
- The shared data accepted by the user
We also update the session status to confirmed.
Ensuring the security of this step is crucial. The access token proves that the user is authenticated in the mobile app. We must make sure that the access token is from an internal organization and not from a third-party. Also, the session status must be retrieved in the Didit API to ensure that the session is still valid.
Authorization client polls for session status
The authorization client regularly polls the /session/{session_id}/status endpoint to check for updates.
We can also use a WebSocket connection for real-time updates.
Authorization Server generates an authorization code
The authorization client then makes a request again to auth/session/{session_id}/status, and since it's confirmed, the server generates a unique authorization code and includes the state (if applicable), and then redirects the user to the redirect_uri with the authorization code as a query parameter.
If an iframe was used to open the auth/authorizeendpoint, the auhorization client needs to redirect the user to the redirect_uri using window.top.location.href = 'https://your-redirect-uri.com/callback?code={authorization_code}&state={authorization_state}'
Redirect_uri endpoint receives the authorization code
The application server handling the redirect_uri receives the request with the authorization code.
Validate the state parameter here to ensure it matches the one sent in step 1. This helps prevent CSRF attacks.
Exchange code for tokens
The application server sends a request to the Authorization Server's token endpoint auth/token, including:
- The authorization code
- The redirect URI (must match the one used in step 1)
- Basic authentication (client ID and secret)
Authorization Server validates and returns tokens
The authorization server verifies the authorization code and, if valid, responds with:
- An access token
- An ID token (if OpenID scope was requested)
- Optionally, a refresh token (if offline scope was requested)
Ensure that issued tokens only cover approved scopes. If a nonce was included in the initial request, validate it when receiving the ID token.
Application client gets user info
The application server and application client can now use the access token to make authenticated requests to the resource server, and the ID token to obtain information about the user.
Check the Get User Info endpoint documentation for more details.
Note that the OIDC flow also creates a data session, like in the data transfer product, so we have consistency on the data shared either in authentication or data transfer.