Auth Flow
#
IntroductionPerforming an auth flow is the only to obtain an access token and ID token. This section provides all the routes the frontend SSO application might use.
All routes described in the sequence diagram are not specified in this document. Most of them do no reuqire specific frontend logic. Only the user's agent redirect is required.
Routes are ordered consedering the expected way they should be called.
An auth flow is linked to both authorization and authentication. A description of these concepts can be found in the Authorization & Authentication specification. It is probably worth to read before implement following routes.
Authentication information:
The final ID Token contains information about the authentication performed by the user.
See the list of Authentication Method References and corresponding Authentication Context Classes for more info.
#
Overall auth flowAs of today:
app.misakey.com
: the frontend clientauth.misakey.com/_
: the Ory Hydra serviceapi.misakey.com
: the backend service responsible for authentication
#
Initiate an authorization code flow#
RequestQuery Parameters:
- see Open ID Connect RFC.
#
ResponseCode:
Headers:
HTML Body:
The Location
header contains the same URL than the HTML body. The user's agent should be redirected to this URL to continue the auth flow to the login flow.
#
Login Flow#
Get Login InformationThis route is used to retrieve information about the current login flow using a login challenge.
#
RequestQuery Parameters:
login_challenge
(string): the login challenge corresponding to the current auth flow.
#
ResponseCode:
JSON Body:
client
(object): information about the SSO client involved in the auth flow:id
(uuid string): the unique id.name
(string): the name.logo_uri
(string) (nullable): web-address of the logo file.policy_uri
(string) (nullable): web-address of client privacy policy.tos_uri
(string) (nullable): web-address of the client TOS.
scope
(string): list of scope sent during the auth flow init.acr_values
(string) (nullable): list of acr values sent during the auth flow init.login_hint
(string): the login_hint sent during the auth flow init.
#
Require an identity for a given identifierThis request is idempotent.
This route is used to retrieve information the identity the end-user will log in.
The identity can be a newly created one for the occasion or an existing one. See Response below for more information.
#
RequestHeaders:
- The request doesn't require an authorization header.
JSON Body:
login_challenge
(string): can be found in preivous redirect URL.identifier_value
(string): the identifier value the end-user has entered.
#
ResponseThis route returns the identity the end-user will login as.
Code:
JSON Body:
identity
(object): the identity linked to the received identifier value.display_name
(string): a customizable display name.avatar_url
(string) (nullable): the web address of the end-user avatar file.has_crypto
(bool): if the identity has setup crypto or not.
authn_state
(json): the state of the authentication. This is computed from the identity and NOT from the real current state, so that no information can leak from this unauthenticated endpoint. This therefore can refer to incorrect values if the auth flow is in progress.
#
Perform an authentication step in the login flowThe next step to authenticate the end-user is to let them enter some information assuring they own the identity. This is called an authentication step.
Some login flow will require many steps later but as of today, we only have one step even for our most secure flows.
The metadata field contained in the authentication step depends of the method name.
#
RequestHeaders:
- The request doesn't require an authorization header.
JSON Body:
login_challenge
(string): can be found in previous redirect URL.authn_step
(object): the performed authentication step information:identity_id
(uuid string): the identity id.method_name
(string) (one of: identity:emailed_code, identity:prehashed_password, webauthn:webauthn, totp:totp, totp:recovery): the authentication method used.metadata
(json object): metadata containing step information.
The list of possible formats is defined in the next section.
#
Metadata field formats as inputThis section describes the possible metadata format, as a JSON object, which is a field contained in the JSON body of the previous section.
The context of this specification is the performing of an authentication step only.
tip
Metadata as output formats are described here and differ a bit.
Expected method formats descriptions 🔗 |
---|
identity:emailed_code |
identity:prehashed_password |
webauthn:webauthn |
totp:totp |
totp:recovery |
#
emailed_code method format as inputJSON Body:
#
prehashed_password method format as input⚠️ Warning, the metadata has not the exact same shape as the metadata returned requiring
an identity with the prehashed_password
value as preferred method, which contains only the hash parameters of the password.
#
webauthn method format as inputThe metadata content is explained in the webauthn documentation
#
totp method format as inputThe code
must be the otp given by the external app.
#
totp recovery method format as inputThe recovery_code
must be in the user recovery codes set.
#
ResponseOn success, the route can return two possible json body:
#
the "redirect" responseWhat is returned is the next URL the user's agent should be redirected to. This response is given when the authentication server consider the end-user has proven its identity sufficiently.
The access token is sent and stored in an http-only cookie.
Code:
JSON Body:
next
(oneof: redirect, authn_step): the next action the authentication server is waiting for.redirect_to
(string): the URL the user's agent should be redirected to.
#
The "more authentication required" responseWhat is returned is the next authentication step the end-user should perform. This response is given when the authentication server requires more authentication step to proove the end-user identity.
Technically, it happens when the current ACR, corresponding to previously validated authentication steps (a.k.a. AMRs), is below the expected ACR.
The expected ACR can be set by:
- the Relying Party expectations:
acr_values
paramenter on the init of the auth flow. - the choosen identity configuration.
Also part of the response, an access token that must be used for the next request as an accesstoken
cookie. This token allows us to authorize more advanced calls.
Code:
JSON Body:
next
(oneof: redirect): the next action the authentication server is waiting for.authn_step
(object): the next expected authn step to end the login flow.
Cookies:
authnaccesstoken
: (string) an access token allowing more advanced requests while being still in the login flow.authntokentype
: (string) the token type.
#
Notable error responsesOn error during an authentication step, some information might be displayed to the end-user.
1. Received code is invalid:
This error occurs when the code received in metadata does not match any stored code.
Code:
JSON Body:
2. Received code has expired:
This error occurs when the code received in metadata is correct but the timebox to use it is expired.
Code:
JSON Body:
3. The Authorization headers do not correspond to the login_challenge:
Situation when the error is returned:
- The end-user has performed an authentication step in a login flow A.
- The end-user refreshes their agent, it inits a new login flow B.
- The client has still the access token bound to the login flow A in headers.
The access token is valid for the login flow A but cannot be used in the login flow B.
Code:
JSON Body:
#
Init a new authentication stepThis endpoint allows to init an authentication step:
- to get information about the step (e.g.:
identity:prehashed_password
,webauthn:webauthn
) - to init a new step (e.g.:
identity:emailed_code
)
#
RequestHeaders:
- The request doesn't require an authorization header.
JSON Body:
login_challenge
(string): can be found in previous redirect URL.authn_step
(object): the initiated authentication step information:identity_id
(uuid string): the identity ID for which the authentication step will be initialized.method_name
(string) (one of: identity:emailed_code, identity:prehashed_password, webauthn:webauthn, totp:totp, totp:recovery): the method used by the authentication step.
#
ResponseThe response is the step metadata, described in the next section.
Code:
#
Notable error responsesOn errors, some information should be displayed to the end-user.
1. A similar authn step already exists:
This error occurs when an authentication step already exists for this identity_id
and method_name
Code:
2. Impossible to perform a prehashed_password method with the identity:
This error occurs when the identity has no linked account. The password being attached to the account, such an authentication method is impossible to be handled.
Code:
#
Metadata field formats as outputConsidering the preferred/expected authentication method, the metadata on output can contain additional information.
tip
Metadata as input formats are defined here and differ a bit.
Expected method formats descriptions 🔗 |
---|
identity:emailed_code |
identity:prehashed_password |
webauthn:webauthn |
totp:totp |
totp:recovery |
#
emailed_code method format as output#
prehashed_password method format as outputOn identity:prehashed_password
, the metadata
field contains information about how the password is supposed to be prehashed.
⚠️ Warning, the metadata has not the exact same shape as the metadata used to perform
an authentication step using the prehashed_password
method, which also contains the hash of the password.
#
webauthn method format as outputThe metadata content is defined and explained in the webauthn documentation.
#
totp method format as output#
totp recovery method format as output#
Consent Flow#
Get Consent InformationThis route is used to retrieve information about the current consent flow using a consent challenge.
#
RequestQuery Parameters:
consent_challenge
(string): the consent challenge corresponding to the current auth flow.
#
ResponseCode:
JSON Body:
subject
(uuid string): unique id of the account getting the tokenacr
(string): the acr level for the current flowscope
(string): list of scope sent during the auth flow init.context
(object): context of the current consent flowclient
(object): information about the SSO client involved in the auth flow:id
(uuid string): the unique id.name
(string): the name.url
(string) (nullable): web-address of the logo file.
#
Accept the consent request in the consent flowThis lets the user choose the scopes they want to accept.
For the moment, those scopes are limited to tos
and privacy_policy
#
RequestHeaders:
- The request doesn't require an authorization header.
JSON Body:
consent_challenge
(string): can be found in previous redirect URL.identity_id
(uuid string): the identity id bound to the identifier of the flow.consented_scopes
(list of string) (one of: tos, privacy_policy): the accepted scopes.
#
ResponseOn success, the route returns the next URL to redirect the user's agent.
Code:
JSON Body:
redirect_to
(string): the URL the user's agent should be redirected to.
#
Notable error responses1 - A mandatory scope is missing from consent
If some legal scopes have been requested at the init of the auth flow, they must be consented in all cases on this request.
Here is the error to expect if the client didn't send these scopes:
#
Others#
Reset the auth flowThis requests allow the complete restart of the auth flow. It triggers a redirection to the initial
auth request if found (using the login_challenge
sent in parameter).
If no auth request is found, it redirects the end-user to a blank connection screen on the Misakey main app (without any information about the initial flow).
⚠️ be aware this action invalidates the session for the whole account in this case.
#
RequestQuery Parameters:
login_challenge
(string) (optional): the login challenge corresponding to the current auth flow. On invalid or missing, the user's agent will be redirected to the home page.
#
ResponseCode:
Headers:
Location
: https://auth.misakey.com/_/oauth2/auth
HTML Body:
The Location
header contains the same URL than the HTML body. The user's agent should be redirected to this URL to continue the auth flow to the login flow.
#
LogoutThis request logouts a user from their authentication session.
An authentication session is valid for an identity but it potentially links other identities through the account relationship, be aware this action invalidates the session for the whole account in this case.
#
Requestaccesstoken
(opaque token) (ACR >= 0):mid
claim as the identity id sent in body.tokentype
: must bebearer
Headers:
X-CSRF-Token
: a token to prevent from CSRF attacks.
#
ResponseThis route does not return any content.
Code:
#
Get Secret StorageThis endpoint allows to get the account secret storage during the auth flow.
This endpoint needs a valid process token.
#
RequestQuery Parameters:
login_challenge
(string): the login challenge corresponding to the current auth flow.identity_id
(string) (uuid4): the id of the identity corresponding to the current auth flow.
Headers:
Authorization
: should beBearer {opaque_token}
with opaque token being thelogin_challenge
of the auth flow.
#
ResponseCode:
JSON Body:
account_id
(string) (uuid4): the id of the account related to the current auth flow.secrets
(object): the content of the account's secret storage.
#
Get BackupThis endpoint allows to get the account backup during the auth flow.
(Note that secret backup system is not used anymore, but this endpoint is needed for the frontend to migrate account still using it to the new secret storage system)
This endpoint needs a valid process token.
#
RequestQuery Parameters:
login_challenge
(string): the login challenge corresponding to the current auth flow.identity_id
(string) (uuid4): the id of the identity corresponding to the current auth flow.
Headers:
Authorization
: should beBearer {opaque_token}
with opaque token being thelogin_challenge
of the auth flow.
#
ResponseCode:
JSON Body:
data
(string): the user backup data.version
(integer): the current backup version.account_id
(string) (uuid4): the id of the account owning the backup.
#
Creating a Root Key ShareThis endpoint allows to create a root key share in the auth flow.
#
RequestHeaders:
Authorization
: should beBearer {opaque_token}
with opaque token being the access token given during the auth flow.
JSON Body:
share
(string) (base64): one of the shares.user_local_share_hash
(string) (unpadded url-safe base64): a hash of the other share.
#
ResponseCode:
JSON Body:
#
OIDC endpointsThese endpoints are openid RFC-compliant endpoints.
#
Get User InfoThis endpoint basically allow to get some of the ID token info.
It must be authenticated.
#
RequestCookies:
accesstoken
(opaque token) (ACR >= 1)tokentype
: must bebearer
#
ResponseCode:
JSON Body:
acr
(string): ACR corresponding to the currrent token,amr
(string array): the way the user got the tokenemail
(string): the user email,sco
(string): list of space separated scopes linked to the token,sid
(string): the session identifier,sub
(string): the user identifier,mid
(string): the Misakey specific identifier,aid
(string): the user account identifier,