Endpoints
Identity Cloud supports the OAuth 2.0 protocol acting as authorization server and provides endpoints, scopes, claims and tokens as required by the OpenID Connect specification.
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.
Authorization endpoint
Clients may request an authorization code by redirecting the user to the Identity Cloud authorization endpoint.
The base URL is as follows:
https://yourinstance.id.nevis.cloud/auth/oauth2/authorize
The following query parameters are required:
response_type=code
expresses that an authorization code shall be returned.
client_id
must contain the Client ID of the application.
redirect_uri
After successful authentication an authorization code will be generated and returned to the given redirect_uri
.
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:
state
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 redirect_uri
.
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.
scope
A list of requested scopes separated by a URL-encoded space (%20
).
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.email
: a claimemail
will be returned inside tokens.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:
code_challenge=...
code_challenge_method=S256
Token endpoint
The URL of the Identity Cloud token endpoint is as follows:
https://yourinstance.id.nevis.cloud/auth/oauth2/token
Your apps can obtain tokens from this endpoint by sending an HTTP POST
request.
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 REST API
.
The URL of this endpoint is as follows:
https://yourinstance.id.nevis.cloud/auth/oauth2/introspect
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:
https://yourinstance.id.nevis.cloud/auth/oidc/userinfo
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:
https://yourinstance.id.nevis.cloud/.well-known/jwks.json