Sign in
Native SSO

Native SSO Processing

This API should be called by the implementation of a token endpoint to generate the ID token and token response that comply with OpenID Connect Native SSO for Mobile Apps 1.0 (Native SSO) when Authlete’s /auth/token response indicates action = NATIVE_SSO (after you validate the session id and verify or generate the device secret as required by the flow). The token endpoint implementation should retrieve the value of action from the response and take the following steps according to the value.

OK

When the action is OK, it indicates that the /nativesso API processing has successfully completed. In this case, the token endpoint implementation should return a successful response (200 OK) to the client. The value of the responseContent property in the /nativesso API response can be used directly as the message body of the token response. Therefore, the success response can be constructed as follows:

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store

(Embed the value of responseContent here.)

INTERNAL_SERVER_ERROR

When the action is INTERNAL_SERVER_ERROR, it indicates that something has gone wrong on the Authlete side. For example, an issue such as a database error might have occurred when retrieving the access token specified by the accessToken parameter from the database.

In such cases, the token endpoint implementation should return an error response to the client. The simplest implementation would be to return a 500 Internal Server Error.

HTTP/1.1 500 Internal Server Error
Content-Type: application/json
Cache-Control: no-store

(Embed the value of responseContent here.)

However, in a production environment, it may be better to return a more abstract error (one that does not directly describe the nature of the issue), rather than a 500 error.

CALLER_ERROR

When the action is CALLER_ERROR, it indicates that the issue lies with the caller of the API (i.e., the implementation of the OpenID Provider). For example, this could be due to missing a required parameter such as accessToken.

If CALLER_ERROR is returned, please review the implementation of your OpenID Provider.

post/api/{serviceId}/nativesso

Path parameters

serviceIdstring required

A service ID.

Request body

accessTokenstring required

The value of this parameter should be: (a) the value of the jwtAccessToken parameter in a response from the /auth/token API when the value is available, or (b) the value of the accessToken parameter in the response from the /auth/token API when the jwtAccessToken parameter is not available.

refreshTokenstring

The value of this parameter should be the value of the refreshToken parameter in a response from the /auth/token API.

substring

The value that should be used as the value of the sub claim of the ID token. This parameter is optional. When omitted, the value of the subject associated with the access token is used.

claimsstring

Additional claims that should be embedded in the payload part of the ID token. The format is a JSON object. This parameter is optional.

idtHeaderParamsstring

Additional parameters that should be embedded in the JWS header of the ID token. The format is a JSON object. This parameter is optional.

idTokenAudTypestring

The type of the aud claim of the ID token being issued. Valid values of this parameter are as follows:

  • "array" The type of the aud claim becomes an array of strings.

  • "string" The type of the aud claim becomes a single string.

This parameter is optional, and the default value when omitted is "array". This parameter takes precedence over the idTokenAudType property of Service.

deviceSecretstring required

The device secret. The value of this parameter should be the value of the deviceSecret parameter in the response from the /auth/token API, if the parameter is present. Otherwise, the authorization server should generate a new device secret and specify it as the value of this parameter.

The specified device secret is included as the value of the device_secret property in the token response prepared by the /nativesso API.

Additionally, if the deviceSecretHash request parameter is omitted, the device secret is used to compute the value of the ds_hash claim. In this case, the ds_hash claim will be the base64url-encoded SHA-256 hash of the device secret.

deviceSecretHashstring

The device secret hash. The specified device secret hash is included as the value of the ds_hash claim in the ID token generated by the /nativesso API. If the deviceSecretHash request parameter is omitted, the value of the deviceSecret request parameter is used to compute the hash.

Response

Native SSO processing completed successfully

resultCodestring

The code which represents the result of the API call.

resultMessagestring

A short message which explains the result of the API call.

action'OK' | 'INTERNAL_SERVER_ERROR' | 'CALLER_ERROR'

The next action that the implementation of the token endpoint should take.

responseContentstring

The response content that can be used as the message body of the token response that should be returned from the token endpoint.

idTokenstring

The issued ID token.

Changes