URLs and endpoints

URL for OAuth 2.0 grants and OIDC flows

The authors of the OAuth 2.0 and OIDC specifications have designed a system that allows users to authenticate securely without entering the authentication credentials in the client application. Client applications receive bearer tokens via back channel after successful authentication and consent of the user (resource owner). To achieve this goal, the authorization code grant/flow is intended to be used with a browser that renders the HTML for a human user.

Airlock IAM implements the authorization code grant/flow behind a single endpoint. The IAM configuration and the parameters provided by the initial request define which grant or flow is used.

Grant and Flows	Type	URL	Authentication	Comment
Authorization Code Grant & Flow	OAuth 2.0 & OIDC	`<loginapp-uri>/oauth2/v3/<as-id>/authorize`	none	This is a public endpoint to start an authorization workflow. No existing authentication is required. For OIDC the client must add the scope `openid` in the request.
Session Management 1.0	OIDC	`<loginapp-uri>/oauth2/v3/<as-id>/check-session`	none	URL of the OP iframe that supports cross-origin communications for session state information with the RP Client.

URL Prefix for OAuth 2.0 and OIDC authorization servers

All OAuth 2.0 and OIDC endpoints are provided with the same base URL. This URL uniquely identifies the authorization server and is named AS-prefix for this documentation.

URL Prefix for OAuth 2.0 and OIDC authorization servers

<loginapp-uri>/rest/oauth2/authorization-servers/<authorization-server-id>

The AS-prefix has the following semantics:
<loginapp-uri>/rest/oauth2 indicates that the API is part of the Airlock IAM REST API and in particular, the OAuth 2.0 and OIDC implementation.
Authorization servers indicate that this endpoint is part of the authorization server implementation and separates it from the OAuth 2.0 client implementation in Airlock IAM.
The authorization-server-id must be supplied to uniquely identify the authorization server that should handle the client request.

OAuth 2.0 and OIDC standard endpoints

Endpoint	Type	URL	Purpose
OAuth 2.0 AS Metadata	OAuth 2.0 & OIDC	`<loginapp-uri>/rest/oauth2/authorization-servers/<as-id>/.well-known/oauth-authorization-server`	Inquire the relevant attributes of the OAuth 2.0 authorization server.
OIDC Discovery	OIDC	`<loginapp-uri>/rest/oauth2/authorization-servers/<as-id>/.well-known/openid-configuration`	Inquire the relevant attributes of the OIDC authorization server.
Token Endpoint	OAuth 2.0 & OIDC	`<loginapp-uri>/rest/oauth2/authorization-servers/<as-id>/token`	Use this endpoint to: execute a token refresh for new access and refresh tokens. exchange an authorization_code for access and refresh tokens. execute a client credentials grant.
Token introspection	OAuth 2.0 & OIDC	`<loginapp-uri>/rest/oauth2/authorization-servers/<as-id>/introspect`	Use this endpoint to verify a token's validity and retrieve metadata on the user of a specific token. This is particularly useful if opaque tokens are used. This endpoint is intended to be used by resource providers and not by clients.
Token revocation	OAuth 2.0 & OIDC	`<loginapp-uri>/rest/oauth2/authorization-servers/<as-id>/revoke`	Use this endpoint to revoke refresh and access tokens. It is recommended to require client authentication.
Pushed Authorization Request	OAuth 2.0 & OIDC	`<loginapp-uri>/rest/oauth2/authorization-servers/<as-id>/par`	Use this endpoint to push request parameters to the authorization server before starting an authorization code flow.
Userinfo Endpoint	OIDC	`<loginapp-uri>/rest/oauth2/authorization-servers/<as-id>/userinfo`	Inquire about metadata about the user
JWKS	OAuth 2.0 & OIDC	`<loginapp-uri>/rest/oauth2/authorization-servers/<as-id>/jwks`	Inquire the public cryptographic key material used by the authorization server. For use by clients to verify signatures.
Dynamic client registration	OAuth 2.0 & OIDC	`<loginapp-uri>/rest/public/tech-client-registration/oauth2/<as-id>/register`	Register a client with the authorization server. The URL of this endpoint differs since DCR is not the only method to register a technical client in Airlock IAM

The following table gives an example of all the URLs returned by the discovery endpoint of an authorization server named myAS and assuming the <loginapp-url> is https://oidc.airlock.com/auth:

{
"authorization_endpoint": "https://oidc.airlock.com/auth/oauth2/v3/myAS/authorize", 
"token_endpoint": "https://oidc.airlock.com/auth/rest/oauth2/authorization-servers/myAS/token",
"pushed_authorization_request_endpoint": "https://oidc.airlock.com/auth/rest/oauth2/authorization-servers/myAS/par",
"registration_endpoint": "https://oidc.airlock.com/auth/rest/public/tech-client-registration/oauth2/myAS/register",
"introspection_endpoint": "https://oidc.airlock.com/auth/rest/oauth2/authorization-servers/myAS/introspect",
"revocation_endpoint": "https://oidc.airlock.com/auth/rest/oauth2/authorization-servers/myAS/revoke",
"jwks_uri": "https://oidc.airlock.com/auth/rest/oauth2/authorization-servers/myAS/jwks",
"userinfo_endpoint": "https://oidc.airlock.com/auth/rest/oauth2/authorization-servers/myAS/userinfo",
}

Airlock IAM proprietary endpoints

The following endpoints are not defined in the OAuth 2.0 or OIDC standards. They are, therefore, not reported in the discovery or the metadata responses.

Endpoint	URL	Purpose
Resource Endpoint	`<loginapp-uri>/rest/oauth2/authorization-servers/<as-id>/resources/<resource-name>`	Exposes Airlock IAM data as a resource. Handles multiple resources. Each resource is fully configurable. May be used to issue session tickets. See SSO tickets for more information on the purpose of session tickets.
Session Management	`<loginapp-uri>/rest/oauth2/authorization-servers/<as-id>/session` `<loginapp-uri>/rest/oauth2/authorization-servers/<as-id>/session/custom-attributes/` `<loginapp-uri>/rest/oauth2/authorization-servers/<as-id>/sessions` `<loginapp-uri>/rest/oauth2/authorization-servers/<as-id>/sessions/<session-id>`	Provide access for clients to manage sessions: session → handle requests about the current session only. Provides support for updating custom attributes in the current session. sessions → handle requests including all the sessions of this user with this authorization server Provides support for managing a select session identified by <session-id>.

Airlock IAM endpoints for public flows

The following endpoints are not defined in the OAuth 2.0 or OIDC standards. They are, therefore, not reported in the discovery or the metadata responses.

Endpoint	Role	URL	Purpose
Authentication request endpoint	IAM as AS	`<loginapp-uri>/rest/public/authentication/oauth2/authorization-servers/<as-id>/authorize/`	A user agent uses this endpoint to start the authentication flow in an OIDC authorization code flow.
Consent endpoint	IAM as AS	`<loginapp-uri>/rest/public/authentication/oauth2/authorization-server/consent/local/[grant\|deny]`	A user agent uses this endpoint to grant or deny consent to the requested scopes.
Authentication response endpoint	IAM as client	`<loginapp-uri>/rest/public/authentication/oauth2/client/authorization/check`	A user agent uses this endpoint to deliver the authorization response of a remote authorization server.