OIDC and OAuth 2.0

Download OpenAPI specification:Download

OpenID Connect (OIDC) extends the authentication and authorization mechanisms of OAuth 2.0 with identity-focused security features like ID tokens and user profiles. Mosaic supports an OIDC-based integration option for hosted login using secure FIDO2 WebAuthn biometrics, and social providers like Google, Facebook, Apple, and LINE.

Decoupled authentication flows are supported using Client-Initiated Backchannel Authentication (CIBA) or using the OAuth Device Flow for input-limited devices.

Authorization

Start an authentication process. If the process is successful, an authorization code is returned to the redirect URI specified in the request. (See OIDC spec). For pushed authorization requests (PAR), provide request_uri returned by the PAR endpoint instead of authorization parameters.

Request
query Parameters
client_id
required
string

Client ID for which authentication is requested. For pushed authorization requests (PAR), the client ID should match the ID of the client that initiated the PAR flow.

redirect_uri
string

Required for authorization code flow. URI to redirect to upon completion of the authentication flow. This is the server GET endpoint used to call the token endpoint, and should accept code as a query parameter. This URI must also be configured as an allowed redirect URI in the Mosaic Admin Portal

scope
string

Required for authorization code flow. Scope of the requested access. Used to request specific user details like email. Must include openid and can include additional values (space delimited). offline_access scope allows refreshing access tokens.

Enum: "openid" "email" "phone" "offline_access"
loginType
string
Deprecated

For authorization code flow. Authentication method to be used for this process, where centralized is used to request authentication via the Authentication Hub.

Enum: "google-direct" "apple-direct" "facebook-direct" "webauthn-direct" "line-direct" "centralized"
response_type
string
Default: "code"

Required for authorization code flow. Response type requested for the authentication flow.

Value: "code"
prompt
string

For authorization code flow. Space-delimited, case-sensitive list of string values that specifies whether the Authorization Server prompts the end-user for reauthentication and consent.

Enum: Description
login

Prompts the user to authenticate.

consent

Prompts the user for consent if required. Must be passed to receive a refresh token and when trying to perform silent authentication to the app you haven't logged in before.

none

Checks for an existing session (and consent if required). Used for silent authentication to the same app as initially logged in to.

nonce
string

For authorization code flow. A random value that is included in the authentication request from the client (e.g. browser) to mitigate replay attacks. It will be added to the id_token and the backend service should only accept id_tokens that include the same nonce value as the one included in the original request.

state
string

For authorization code flow. An opaque string that is used to maintain state between the request and the callback. It will be added to the redirect URI as a query parameter, which should be validated by your server to protect against cross-site request forgery (CSRF) attacks

code_challenge
string

A hashed value of the 'code_verifier' required for PKCE

code_challenge_method
string

The hashing mechanism used to transform a code_verifier into the code_challenge in PKCE flows, must be 'S256'

resource
string

For authorization code flow. Resource URI the authentication request is attempting to access, which is reflected in the audience (aud claim) of the access token. This must be configured as resource for the application.

claims
string

For authorization code flow. A stringified object used to request additional claims in the ID token, such as roles, permissions, and other user profile data. The structure is per the OIDC Standard. For supported claims and how to request custom claims, see the ID Token Reference. Note: You should stringify the value.

Example: claims={"id_token":{"roles":null}}
acr_values
string

For authorization code flow. Requested ACR values, specified as a space-separated string. The acr claim of the resulting ID token will indicate which requirements were satisfied.

Enum: Description
mfa

Requires multi-factor authentication. If it isn't satisfied, an error is returned indicating how to satisfy it via email/SMS authentication.

phone_number

Requires a verified phone number for a WebAuthn login. If it isn't yet verified, an SMS verification process will occur.

urn:transmit:google_direct

Requires Google authentication method to be used for this process.

urn:transmit:apple_direct

Requires Apple authentication method to be used for this process.

urn:transmit:facebook_direct

Requires Facebook authentication method to be used for this process.

urn:transmit:webauthn_direct

Requires WebAuthn authentication method to be used for this process.

urn:transmit:line_direct

Requires Line authentication method to be used for this process.

urn:transmit:centralized

Requires centralized authentication method to be used for this process, centralized is used to request authentication via the Authentication Hub.

createNewUser
boolean
Default: false

For authorization code flow. Indicates if a new user should be created if one doesn't already exist (or associated with the app if the user isn't already). Public sign up must be enabled for this application.

login_hint
string

For authorization code flow. Hint for the user's login identifier for WebAuthn login.

Example: login_hint=user@acme.com
custom_message
string

For authorization code flow. Custom message to present on the consent screens for WebAuthn login, which provides authentication context details.

Example: custom_message=Welcome to Acme
ui_locales
string

For authorization code flow. Preferred languages for the user interface for WebAuthn login, specified as a space-separated list of language tag values [RFC5646], ordered by preference.

org_id
string

For authorization code flow. Organization ID, used for member login in B2B scenarios

request_uri
string

Required for PAR flow. The URI returned by the PAR request. The request_uri value is bound to the client that sent the PAR authorization request.

Responses
303

Redirects with authentication result.

400
500
get/oidc/auth
Request samples
Response samples
application/json
{
  • "message": "Bad request",
  • "error_code": 400
}

Backchannel authentication

Start a backchannel authentication process (See CIBA spec). The request can either be used to obtain a direct link (for example, to embed in a QR code) or to send the user a link by SMS or email. When opened, this link will initiate an authentication process. The request returns the authentication request ID that will be used to complete the process on the authenticating device (by calling /auth/backchannel/complete) and obtain the token. If the link channel was specified, the response will also include the link.

Request
Request Body schema: application/x-www-form-urlencoded
required
client_id
required
string

Client ID for which authentication is requested.

client_secret
required
string

Client secret.

scope
required
string

Scope of the requested access. Used to request specific user details like email. Must include openid and can include additional values (space delimited). offline_access scope allows refreshing access tokens.

Enum: "openid" "email" "phone" "offline_access"
login_hint
required
string

Identifier of a user for whom authentication is requested (email, phone or user_id)

binding_message
string^[a-zA-Z0-9-._+/!?#]{1,20}$

A message intended to be displayed on both consumption and authentication devices so the end-user can see how they are interconnected for the transaction.

The message needs to be 1 - 20 characters in length and should contain only digits, alphabet and the characters: -._+/!?#

requested_expiry
integer
Default: 600

Requested expiration of the authentication request in seconds.

request_context
string

A stringify object that contains more data about the request

example of object:

{
    "channel": "email", 
    "login_hint_type": "email", 
    "custom_message": "click on the following link to approve the access: "
}

Note: You should stringify the value.

property description
channel The channel to use for triggering the authentication device, one of the values: sms (default), email, link
login_hint_type The login_hint identifier type, one of the values: phone (default), email, user_id
custom_message Custom message to be sent when triggering the authentication device (default: To verify it's you, click this link:)
Responses
200

The authentication request has been accepted

400
500
post/oidc/backchannel
Request samples
application/x-www-form-urlencoded
client_id=string&client_secret=string&scope=openid&login_hint=string&binding_message=string&requested_expiry=600&request_context=%7B%22channel%22%3A%20%22email%22%2C%20%22login_hint_type%22%3A%20%22email%22%2C%20%22custom_message%22%3A%20%22click%20on%20the%20following%20link%20to%20approve%20the%20access%3A%20%22%7D
Response samples
application/json
{
  • "auth_req_id": "string",
  • "expires_in": 600
}

Device authorization

Initiate the device flow (See OAuth 2.0 Device Authorization Grant (RFC 8628)). This call returns a user code and verification URI for the user to approve or deny access on a separate device. Additionally, a device code is provided to obtain the token.

Request
Request Body schema: application/x-www-form-urlencoded
required
client_id
required
string

Client ID for which authentication is requested.

client_secret
required
string

Client secret.

scope
required
string

Scope of the requested access. Used to request specific user details like email. Must include openid and can include additional values (space delimited). offline_access scope allows refreshing access tokens.

Enum: "openid" "email" "phone" "offline_access"
loginType
string
Deprecated

Authentication method to be used for this process, where centralized is used to request authentication via the Authentication Hub.

Enum: "google-direct" "apple-direct" "facebook-direct" "webauthn-direct" "line-direct" "centralized"
acr_values
required
string

Requested ACR values, specified as a space-separated string. The acr claim of the resulting ID token will indicate which requirements were satisfied.

Enum: Description
urn:transmit:google_direct

Requires Google authentication method to be used for this process.

urn:transmit:apple_direct

Requires Apple authentication method to be used for this process.

urn:transmit:facebook_direct

Requires Facebook authentication method to be used for this process.

urn:transmit:webauthn_direct

Requires WebAuthn authentication method to be used for this process.

urn:transmit:line_direct

Requires Line authentication method to be used for this process.

urn:transmit:centralized

Requires centralized authentication method to be used for this process, centralized is used to request authentication via the Authentication Hub.

Responses
200

The authorization request has been accepted

400
500
post/oidc/device/auth
Request samples
application/x-www-form-urlencoded
client_id=string&client_secret=string&scope=openid&loginType=google-direct&acr_values=urn%3Atransmit%3Agoogle_direct
Response samples
application/json
{
  • "device_code": "string",
  • "user_code": "string",
  • "verification_uri": "string",
  • "verification_uri_complete": "string",
  • "expires_in": 600
}

Token

Retrieves tokens in various OIDC/OAuth flows. It's used to retrieve an ID token and user access token upon successful user authentication (for an authorization code flow), or to retrieve client access tokens for API authorization (in a client credentials flow).

Request
Request Body schema: application/x-www-form-urlencoded
required
One of:
client_id
required
string

Client ID for which authentication is requested.

client_secret
required
string

Client secret.

code
required
string

Authorization code received from a successful authentication flow.

grant_type
required
string

Should be set to authorization_code to identify users upon successful authentication.

Value: "authorization_code"
redirect_uri
required
string

Redirect URI passed in the authorization request.

Responses
200

Returns user tokens

400
500
post/oidc/token
Request samples
application/x-www-form-urlencoded
client_id=string&client_secret=string&code=string&grant_type=authorization_code&redirect_uri=string
Response samples
application/json
{
  • "access_token": "string",
  • "id_token": "string",
  • "expires_in": 3600,
  • "scope": "string",
  • "token_type": "string",
  • "refresh_token": "string"
}

Revocation

Revoke a specific refresh token, making it no longer valid and forcing the user to re-authenticate if they need a new one.

Request
Request Body schema: application/x-www-form-urlencoded
required
client_id
required
string

Client ID.

client_secret
required
string

Client secret.

token
required
string

Token to revoke.

token_type_hint
string

A hint about the type of the token submitted for revocation.

Enum: "access_token" "refresh_token"
Responses
200

Token revoked successfully

400
500
post/oidc/token/revocation
Request samples
application/x-www-form-urlencoded
client_id=string&client_secret=string&token=string&token_type_hint=access_token
Response samples
application/json
{
  • "message": "Bad request",
  • "error_code": 400
}

Logout

Logs out the user by terminating all their sessions for this tenant. See OIDC RP-Initiated Logout

Request
query Parameters
client_id
string

Recommended. Client ID initiating the logout request. If not passed, our default logout success page will be shown instead.

id_token_hint
string

Previously issued ID Token passed as a hint about the user's current authenticated session with the client.

post_logout_redirect_uri
string

Recommended. URI to which the user should be redirected after the logout has been performed. If not passed, our default logout success page will be shown instead.

state
string

Opaque value used to maintain state between the logout request and the post logout redirect URI (which will receive it via the state query parameter).

Responses
200

Returns HTML that when parsed by the browser, will finish the logout flow.

400
500
get/oidc/session/end
Request samples
Response samples
application/json
{
  • "message": "Bad request",
  • "error_code": 400
}

JWKS

Returns the signing key used to validate the signature of the authorization request (per OIDC spec)

Responses
200
500
get/oidc/jwks
Request samples
Response samples
application/json
{
  • "keys": [
    ]
}

Discovery

Get all metadata for the OIDC server, including paths to relevant endpoints. (see OIDC spec)

Responses
200
500
get/oidc/.well-known/openid-configuration
Request samples
Response samples
application/json
{
  • "message": "Something went wrong - Internal server error",
  • "error_code": 500
}

PAR

Pushed authorization request (PAR) is a secure way to initiate the authorization flow. All parameters are sent in the body of the request (see OAuth 2.0 Pushed Authorization Requests RFC).

Request
Request Body schema: application/x-www-form-urlencoded
required
client_id
required
string

Client ID for which authentication is requested.

client_secret
required
string

Client secret.

redirect_uri
required
string

URI to redirect to upon completion of the authentication flow. This is the server GET endpoint used to call the token endpoint, and should accept code as a query parameter. This URI must also be configured as an allowed redirect URI in the Admin Portal

response_type
required
string

Response type requested for the authentication flow.

Value: "code"
scope
string

Scope of the requested access. Used to request specific user details like email. Must include openid and can include additional values (space delimited). offline_access scope allows refreshing access tokens.

Enum: "openid" "email" "phone" "offline_access"
prompt
string

Space-delimited, case-sensitive list of string values that specifies whether the Authorization Server prompts the end-user for reauthentication and consent.

Enum: "none" "login" "consent"
nonce
string

A random value that is included in the authentication request from the client (e.g. browser) to mitigate replay attacks. It will be added to the id_token and the backend service should only accept id_tokens that include the same nonce value as the one included in the original request.

state
string

An opaque string that is used to maintain state between the request and the callback. It will be added to the redirect URI as a query parameter, which should be validated by your server to protect against cross-site request forgery (CSRF) attacks

resource
string

Resource URI the authentication request is attempting to access, which is reflected in the audience (aud claim) of the access token. This must be configured as resource for the application.

claims
string

A stringified object used to request additional claims in the ID token, such as roles, permissions, and other user profile data. The structure is per the OIDC Standard. For supported claims and how to request custom claims, see the ID Token Reference. Note: You should stringify the value.

acr_values
string

Requested ACR values, specified as a space-separated string. The acr claim of the resulting ID token will indicate which requirements were satisfied.

Enum: "mfa" "phone_number" "urn:transmit:google_direct" "urn:transmit:apple_direct" "urn:transmit:facebook_direct" "urn:transmit:webauthn_direct" "urn:transmit:line_direct" "urn:transmit:centralized"
createNewUser
boolean
Default: false

Indicates if a new user should be created if one doesn't already exist (or associated with the app if the user isn't already). Public sign up must be enabled for this application.

login_hint
string

Hint for the user's login identifier for WebAuthn login.

custom_message
string

Custom message to present on the consent screens for WebAuthn login, which provides authentication context details.

ui_locales
string

Preferred languages for the user interface for WebAuthn login, specified as a space-separated list of language tag values [RFC5646], ordered by preference.

org_id
string

Organization ID, used for member login in B2B scenarios

Responses
200

The request has been accepted

400
500
post/oidc/request
Request samples
application/x-www-form-urlencoded
client_id=string&client_secret=string&redirect_uri=string&response_type=code&scope=openid&prompt=none&nonce=string&state=string&resource=string&claims=string&acr_values=mfa&createNewUser=false&login_hint=string&custom_message=Welcome%20to%20Acme&ui_locales=string&org_id=string
Response samples
application/json
{
  • "request_uri": "string",
  • "expires_in": 60
}