> ## Documentation Index
> Fetch the complete documentation index at: https://developers.authlete.com/llms.txt
> Use this file to discover all available pages before exploring further.
# 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](https://openid.net/specs/openid-connect-native-sso-1_0.html) (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.
## OpenAPI
````yaml https://spec.speakeasy.com/authlete/sdk-workspace/authlete-api-explorer-with-code-samples post /api/{serviceId}/nativesso
openapi: 3.0.3
info:
title: Authlete API
description: ''
version: 3.0.16
license:
name: Apache 2.0
url: https://www.apache.org/licenses/LICENSE-2.0.html
servers:
- description: 🇺🇸 US Cluster
url: https://us.authlete.com
- description: 🇯🇵 Japan Cluster
url: https://jp.authlete.com
- description: 🇪🇺 Europe Cluster
url: https://eu.authlete.com
- description: 🇧🇷 Brazil Cluster
url: https://br.authlete.com
security:
- bearer: []
tags:
- name: Service Management
description: >-
API endpoints for managing services, including creation, update, and
deletion of services.
x-tag-expanded: false
- name: Client Management
description: >-
API endpoints for managing OAuth clients, including creation, update, and
deletion of clients.
x-tag-expanded: false
- name: Authorization Endpoint
description: API endpoints for implementing OAuth 2.0 Authorization Endpoint.
x-tag-expanded: false
- name: Pushed Authorization Endpoint
description: >-
API endpoints for implementing OAuth 2.0 Pushed Authorization Requests
(PAR).
x-tag-expanded: false
- name: Token Endpoint
description: API endpoints for implementing OAuth 2.0 Token Endpoint.
x-tag-expanded: false
- name: Token Operations
description: >-
API endpoints for various token related operations, including creating,
revoking and deleting access_tokens with specified scopes.
x-tag-expanded: false
- name: Introspection Endpoint
description: API endpoints for implementing OAuth 2.0 Introspection Endpoint.
x-tag-expanded: false
- name: Revocation Endpoint
description: API endpoint for implementing OAuth 2.0 Revocation Endpoint.
x-tag-expanded: false
- name: UserInfo Endpoint
description: API endpoints for implementing OpenID Connect UserInfo Endpoint.
x-tag-expanded: false
- name: JWK Set Endpoint
description: API endpoints for to generate JSON Web Key Set (JWKS) for a service.
x-tag-expanded: false
- name: Discovery Endpoint
description: API endpoints for implementing OpenID Connect Discovery.
x-tag-expanded: false
- name: Configuration Endpoint
description: API endpoint for accessing configuration settings for a service.
x-tag-expanded: false
- name: Dynamic Client Registration
description: API endpoints for implementing OAuth 2.0 Dynamic Client Registration.
x-tag-expanded: false
- name: CIBA
description: >-
API endpoints for implementing Client-Initiated Backchannel Authentication
(CIBA).
x-tag-expanded: false
- name: Grant Management Endpoint
description: >-
API endpoint for implementing OAuth 2.0 grants, including grant management
actions like updating and revoking grants.
x-tag-expanded: false
- name: Jose Object
description: API endpoints for JOSE objects.
x-tag-expanded: false
- name: Device Flow
description: API endpoints for implementing OAuth 2.0 Device Flow
x-tag-expanded: false
- name: Federation Endpoint
description: API endpoints for implementing OpenID Federation using Authlete.
x-tag-expanded: false
- name: Verifiable Credential Issuer
description: >-
API endpoints for implementing and running a Verifiable Credential Issuer
(VCI).
x-tag-expanded: false
- name: Hardware Security Key
description: API endpoints for managing hardware security keys (HSK).
x-tag-expanded: false
- name: Utility Endpoints
description: API endpoints for various utility operations.
x-tag-expanded: false
- name: Native SSO
description: API endpoints for Native SSO
x-tag-expanded: false
paths:
/api/{serviceId}/nativesso:
post:
tags:
- Native SSO
summary: Native SSO Processing
description: >
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](https://openid.net/specs/openid-connect-native-sso-1_0.html)
(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.
operationId: native_sso_api
parameters:
- in: path
name: serviceId
description: A service ID.
required: true
schema:
type: string
example: '715948317'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/native_sso_request'
example:
accessToken: _kh1aygxZ5NKLYKCJRM8M_AYvDg2wCWoprQDjfO87ZWq
refreshToken: kHUGSt_d3LSgiCQzH7wa5TpwIHWgjAZGw14zZV7hRqw
deviceSecret: my-ds
claims: >-
{"given_name":"John","family_name":"Brown","email":"test@example.com"}
responses:
'200':
description: Native SSO processing completed successfully
content:
application/json:
schema:
$ref: '#/components/schemas/native_sso_response'
example:
resultCode: A501001
resultMessage: >-
[A501001] A Native SSO-compliant ID token and a token response
were generated successfully.
action: OK
responseContent: >-
{\"access_token\":\"_kh1aygxZ5NKLYKCJRM8M_AYvDg2wCWoprQDjfO87ZWq\",\"token_type\":\"Bearer\",\"expires_in\":86400,\"scope\":\"openid
device_sso\",\"refresh_token\":\"kHUGSt_d3LSgiCQzH7wa5TpwIHWgjAZGw14zZV7hRqw\",\"id_token\":\"eyJraWQiOiItc1RSWDc5YnEyOEhyYkxBV0w2N3k4T1VJdXdrTms2ZFFkbzItSExZMkxvIiwiYWxnIjoiRVMyNTYifQ.eyJpc3MiOiJodHRwczovL2F1dGhsZXRlLmNvbSIsInN1YiI6ImpvaG4iLCJhdWQiOlsibmF0aXZlX2FwcF8xIl0sImV4cCI6MTc1NjcxNzY3MywiaWF0IjoxNzU2NzE3MzczLCJkc19oYXNoIjoic0luWlNhY1luRkR1Y1dwckRqZmtYeENRZl9mWGhsVDY1ZDduS0VYNzc2OCIsInNpZCI6Im15LXNpZCIsImdpdmVuX25hbWUiOiJKb2huIiwiZmFtaWx5X25hbWUiOiJCcm93biIsImVtYWlsIjoidGVzdEBleGFtcGxlLmNvbSJ9.RASuwd4KYPe8b3vNNwIYJgoXzUadDFFHO1wYWD70Z3EsZd8qcxxkPmJKs3dRitvYTX8DDqf5zvAm1jlIeEuvRQ\",\"device_secret\":\"my-ds\"}
idToken: >-
eyJraWQiOiItc1RSWDc5YnEyOEhyYkxBV0w2N3k4T1VJdXdrTms2ZFFkbzItSExZMkxvIiwiYWxnIjoiRVMyNTYifQ.eyJpc3MiOiJodHRwczovL2F1dGhsZXRlLmNvbSIsInN1YiI6ImpvaG4iLCJhdWQiOlsibmF0aXZlX2FwcF8xIl0sImV4cCI6MTc1NjcxNzY3MywiaWF0IjoxNzU2NzE3MzczLCJkc19oYXNoIjoic0luWlNhY1luRkR1Y1dwckRqZmtYeENRZl9mWGhsVDY1ZDduS0VYNzc2OCIsInNpZCI6Im15LXNpZCIsImdpdmVuX25hbWUiOiJKb2huIiwiZmFtaWx5X25hbWUiOiJCcm93biIsImVtYWlsIjoidGVzdEBleGFtcGxlLmNvbSJ9.RASuwd4KYPe8b3vNNwIYJgoXzUadDFFHO1wYWD70Z3EsZd8qcxxkPmJKs3dRitvYTX8DDqf5zvAm1jlIeEuvRQ
links:
authz_process:
$ref: '#/components/links/authz_process'
token_exchange:
$ref: '#/components/links/token_exchange'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
'500':
$ref: '#/components/responses/500'
x-codeSamples:
- lang: typescript
label: Typescript (SDK)
source: |-
import { Authlete } from "@authlete/typescript-sdk";
const authlete = new Authlete({
bearer: process.env["AUTHLETE_BEARER"] ?? "",
});
async function run() {
const result = await authlete.nativeSso.process({
serviceId: "715948317",
nativeSsoRequest: {
accessToken: "_kh1aygxZ5NKLYKCJRM8M_AYvDg2wCWoprQDjfO87ZWq",
refreshToken: "kHUGSt_d3LSgiCQzH7wa5TpwIHWgjAZGw14zZV7hRqw",
claims: "{\"given_name\":\"John\",\"family_name\":\"Brown\",\"email\":\"test@example.com\"}",
deviceSecret: "my-ds",
},
});
console.log(result);
}
run();
- lang: ruby
label: Ruby (SDK)
source: >-
require 'authlete_ruby_sdk'
Models = ::Authlete::Models
s = ::Authlete::Client.new(
bearer: ''
)
res = s.native_sso.process_request(service_id: '715948317',
native_sso_request: Models::Components::NativeSsoRequest.new(
access_token: '_kh1aygxZ5NKLYKCJRM8M_AYvDg2wCWoprQDjfO87ZWq',
refresh_token: 'kHUGSt_d3LSgiCQzH7wa5TpwIHWgjAZGw14zZV7hRqw',
claims: '{"given_name":"John","family_name":"Brown","email":"test@example.com"}',
device_secret: 'my-ds'
))
unless res.native_sso_response.nil?
# handle response
end
- lang: go
label: Go (SDK)
source: "package main\n\nimport(\n\t\"context\"\n\t\"os\"\n\tauthlete \"github.com/authlete/authlete-go-sdk\"\n\t\"github.com/authlete/authlete-go-sdk/models/components\"\n\t\"log\"\n)\n\nfunc main() {\n ctx := context.Background()\n\n s := authlete.New(\n authlete.WithSecurity(os.Getenv(\"AUTHLETE_BEARER\")),\n )\n\n res, err := s.NativeSso.Process(ctx, \"715948317\", components.NativeSsoRequest{\n AccessToken: \"_kh1aygxZ5NKLYKCJRM8M_AYvDg2wCWoprQDjfO87ZWq\",\n RefreshToken: authlete.Pointer(\"kHUGSt_d3LSgiCQzH7wa5TpwIHWgjAZGw14zZV7hRqw\"),\n Claims: authlete.Pointer(\"{\\\"given_name\\\":\\\"John\\\",\\\"family_name\\\":\\\"Brown\\\",\\\"email\\\":\\\"test@example.com\\\"}\"),\n DeviceSecret: \"my-ds\",\n })\n if err != nil {\n log.Fatal(err)\n }\n if res.NativeSsoResponse != nil {\n // handle response\n }\n}"
x-code-samples:
- lang: shell
label: curl
source: >
curl -v -X POST https://us.authlete.com/api/21653835348762/nativesso
\
-H 'Content-Type:application/json' \
-H 'Authorization: Bearer
V5a40R6dWvw2gMkCOBFdZcM95q4HC0Z-T0YKD9-nR6F' \
-d '{ "accessToken": "_kh1aygxZ5NKLYKCJRM8M_AYvDg2wCWoprQDjfO87ZWq",
"refreshToken": "kHUGSt_d3LSgiCQzH7wa5TpwIHWgjAZGw14zZV7hRqw",
"deviceSecret": "my-ds", "claims":
"{\"given_name\":\"John\",\"family_name\":\"Brown\",\"email\":\"test@example.com\"}"
}'
- lang: java
label: java
source: >
AuthleteConfiguration conf = ...;
AuthleteApi api = AuthleteApiFactory.create(conf);
NativeSsoRequest req = new NativeSsoRequest();
req.setAccessToken("_kh1aygxZ5NKLYKCJRM8M_AYvDg2wCWoprQDjfO87ZWq");
req.setRefreshToken("kHUGSt_d3LSgiCQzH7wa5TpwIHWgjAZGw14zZV7hRqw");
req.setDeviceSecret("my-ds");
req.setClaims("{\"given_name\":\"John\",\"family_name\":\"Brown\",\"email\":\"test@example.com\"}")
api.nativeSso(req);
components:
schemas:
native_sso_request:
type: object
required:
- accessToken
- deviceSecret
properties:
accessToken:
type: string
description: >
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.
refreshToken:
type: string
description: >
The value of this parameter should be the value of the
`refreshToken` parameter in a response
from the `/auth/token` API.
sub:
type: string
description: >
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.
claims:
type: string
description: >
Additional claims that should be embedded in the payload part of the
ID token. The format is a
JSON object. This parameter is optional.
idtHeaderParams:
type: string
description: >
Additional parameters that should be embedded in the JWS header of
the ID token. The format is
a JSON object. This parameter is optional.
idTokenAudType:
type: string
description: >
The type of the `aud` claim of the ID token being issued. Valid
values of this parameter are
as follows:
x-mint:
metadata:
description: >-
The type of the `aud` claim of the ID token being issued. Valid
values of this parameter are as follows:
content: >
- `"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`.
deviceSecret:
type: string
description: >
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.
x-mint:
metadata:
description: >-
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.
content: >
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.
deviceSecretHash:
type: string
description: >
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.
native_sso_response:
type: object
properties:
resultCode:
type: string
description: The code which represents the result of the API call.
resultMessage:
type: string
description: A short message which explains the result of the API call.
action:
type: string
enum:
- OK
- INTERNAL_SERVER_ERROR
- CALLER_ERROR
description: >
The next action that the implementation of the token endpoint should
take.
responseContent:
type: string
description: >
The response content that can be used as the message body of the
token response that should be
returned from the token endpoint.
idToken:
type: string
description: |
The issued ID token.
result:
type: object
properties:
resultCode:
type: string
description: The code which represents the result of the API call.
resultMessage:
type: string
description: A short message which explains the result of the API call.
responses:
'400':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/result'
example:
resultCode: A001201
resultMessage: '[A001201] /auth/authorization, TLS must be used.'
'401':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/result'
example:
resultCode: A001202
resultMessage: '[A001202] /auth/authorization, Authorization header is missing.'
'403':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/result'
example:
resultCode: A001215
resultMessage: >-
[A001215] /auth/authorization, The client (ID = 26837717140341) is
locked.
'500':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/result'
example:
resultCode: A001101
resultMessage: '[A001101] /auth/authorization, Authlete Server error.'
securitySchemes:
bearer:
type: http
scheme: bearer
bearerFormat: JWT
description: >
Authenticate every request with a **Service Access Token** or
**Organization Token**.
Set the token value in the `Authorization: Bearer ` header.
**Service Access Token**: Scoped to a single service. Use when
automating service-level configuration or runtime flows.
**Organization Token**: Scoped to the organization; inherits permissions
across services. Use for org-wide automation or when managing multiple
services programmatically.
Both token types are issued by the Authlete console or provisioning
APIs.
````