Sign-in and sessions
Raha Account signs users in on its own hosted pages rather than exposing password collection to client applications. Your application redirects to the authorization endpoint and receives an authorization code once the user is done.
What happens during sign-in
Depending on the user and your request, the hosted flow may include:
- Login or signup.
- Multi-factor authentication with OTP, TOTP, SMS, email, or recovery codes, when enabled for the account or required by the requested assurance level.
- Choosing between accounts remembered in the browser.
- Consent to the scopes your application requested.
- Password recovery, if the user has forgotten their password.
Your application does not need to handle any of these steps. Do not reproduce, embed, or automate the hosted screens.
Authorization request
Required parameters: client_id, redirect_uri, response_type=code, scope, code_challenge, and code_challenge_method=S256. Always send state and nonce as well.
Optional parameters:
| Parameter | Purpose |
|---|---|
prompt | none, login, consent, select_account, or create. See below. |
acr_values | Request an authentication assurance level supported by your client. |
id_token_hint | Pass a previous ID token to provide context for the user's existing session. |
ui_locales, ui_theme | Match the hosted pages to your application. See hosted UI preferences. |
Prompt values
| Value | Behavior |
|---|---|
none | Do not show any UI. Returns an error to your redirect URI if the user must sign in or consent. |
login | Ask the user to authenticate again, even with an active session. |
consent | Ask for consent again, even if it was previously granted. |
select_account | Let the user choose which remembered account to use. |
create | Start on the signup screen. |
Sessions
Raha Account keeps its own secure session cookie. Your application never receives it; you receive tokens for the completed authorization and manage your own session separately.
A browser may remember more than one Raha Account. If the user switches accounts in Raha Account, your application keeps its tokens for the account that signed in until you start a new authorization.
Protected APIs reject access tokens tied to revoked sessions, even before the tokens expire. Users can end sessions and revoke connected applications from their account at any time, so treat 401 responses and invalid_grant on refresh as a signal to sign the user in again.
Logout
Raha Account provides two logout endpoints. Both are listed in the discovery document and accept id_token_hint, post_logout_redirect_uri, and state.
| Endpoint | Use it to |
|---|---|
/api/oauth2/logout | Sign out the session behind the ID token. Other accounts remembered in the browser stay available. |
/api/oauth2/end-session | End the whole Raha Account session and notify other applications through front- and back-channel logout. |
post_logout_redirect_uri must be one of your registered post-logout redirect URIs. When you send state, it is appended to the redirect so you can correlate the logout.
const url = new URL(configuration.end_session_endpoint)
url.searchParams.set('id_token_hint', idToken)
url.searchParams.set(
'post_logout_redirect_uri',
'https://app.example.com/signed-out',
)
url.searchParams.set('state', state)
window.location.assign(url)
Clear your own application session as well; Raha Account logout does not remove your cookies.