Skip to main content

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 claim email 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:

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

OpenID Connect metadata endpoint​

The OpenId Connect metadata endpoint is a public read-only endpoint that returns metadata about the OpenID provider's configuration. It returns a JSON object containing all necessary endpoints and public key location information.

The URL of this endpoint is:

https://yourinstance.id.nevis.cloud/.well-known/openid-configuration