The OAuth 2.0 and OpenID Connect specifications are vast and there are several concepts which you should be familiar with. In this page we use the following terms:
- client: an application which relies on the OAuth / OpenID Connect protocol to acquire tokens.
- resource owner: a user who has to authenticate and grant access to client applications.
- resource server: a REST API which can be accessed using an access token.
- authorization grant: returned as an authorization code by the Identity Cloud authorization server.
- authorization code: can be requested from the authorization endpoint of the Identity Cloud authorization server.
- access token: can be requested from the token endpoint of the Identity Cloud authorization server.
- ID token: can be requested from the token endpoint of the Identity Cloud authorization server.
Clients may request an authorization code by redirecting the user to the Identity Cloud authorization endpoint.
The base URL is as follows:
The following query parameters are required:
expresses that an authorization code shall be returned.
must contain the Client ID of the application.
After successful authentication an authorization code will be generated and returned to the given
This authorization code can then be exchanged for an access token at the token endpoint.
This query parameter usually contains a URL, but it can also be a custom URI to trigger a mobile application. The URI has to be allowed for this application when you add the application to Identity Cloud.
The following optional query parameters are supported:
This query parameter is optional but should be added to protect against cross-site request forgery (CSRF).
The client has to generate an opaque random string which cannot easily be guessed.
To keep it simple, we recommend that you only use URL-safe characters (numbers and letters), and produce a string of reasonable length (32 characters or longer).
An easy way to generate such a string is to create a hash of client state (for example, hash the session cookie).
The authorization endpoint will send back this parameter by attaching it to the
If the returned value and the generated value are the same, the client can be sure that the request to the
redirect_uri was not triggered by an attacker.
A list of requested scopes separated by a URL-encoded space (
You can define which scopes shall be allowed on the detail view of your application.
Note that the user does not have to give consent to the requested scopes as the consent is implicitly given.
The OpenID Connect specification defines several standard scopes. Identity Cloud supports the following:
openid: an ID token will be returned by the token endpoint.
offline_access: a refresh token will be returned by the token endpoint.
profile: returns claims about the user (where available).
address: returns the address of the user (if available).
phone: returns the mobile phone of the user (if available).
SPA and native / mobile applications are expected to use the Authorization Code flow with PKCE which requires the following additional query parameters to be sent:
The URL of the Identity Cloud token endpoint is as follows:
Your apps can obtain tokens from this endpoint by sending an HTTP
Access tokens and ID tokens are signed JWTs, while refresh tokens have an opaque format.
Which parameters have to be included in the request depends on the OAuth 2.0 / OpenID Connect flow. See the flow descriptions for details:
- Authorization Code flow for classic Web applications.
- Authorization Code with PKCE flow for SPA and native applications.
- Refresh Token flow to obtain new tokens without forcing users to log in again.
- Client Credentials for machine-to-machine use cases.
Token Introspection endpoint
The introspection endpoint is an OAuth 2.0 endpoint that takes a parameter representing an OAuth 2.0 token and returns a JSON [RFC7159] document representing the meta information surrounding the token, including whether this token is currently active.
This endpoint is called by resource servers to validate received access tokens. The endpoint requires authentication (using client ID and secret) and thus resource servers are clients as well.
We represent resource servers in Identity Cloud as applications of type
The URL of this endpoint is as follows:
User info endpoint
The user info endpoint is an OAuth 2.0 protected resource that can return claims about a user.
It may be called by applications which have an access token to get further information about the user this access token has been issued for.
The URL of this endpoint is as follows:
To obtain the requested claims, the client has to make a request to this endpoint sending along an access token provided by the token endpoint.
Which claims are returned depends on the scopes requested at the authorization endpoint.
Note that that scope
openid must have been requested so that it is included in the access token.
The claims are returned as a JSON object that contains a collection of name and value pairs for the claims.
JWK Set endpoint
The JSON Web Key Set (JWKS) endpoint is a read-only endpoint that contains information about the key material used to sign tokens.
The URL of this endpoint is: