AS-centric AS - 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 securely authenticate without entering the authentication credentials in the client application. Client applications receive bearer tokens after successful authentication and consent of the user. To achieve this goal, the authorization code grant/flow is intended to be used with a browser that renders the HTML for a human actor.

Airlock IAM implements the authorization code grant/flow behind a single endpoint. The 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	/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	/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

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

URL Prefix for OAuth 2.0 and OIDC authorization servers

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

This AS-prefix has the following semantics:
●
/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 indicates that this endpoint is part of the new AS-centric implementation and separates it from the OAuth 2.0 client implementation in Airlock IAM.
●
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	rest/oauth2/authorization-servers/<as-id>/.well-known/oauth-authorization-server	Inquire all the relevant attributes of the OAuth 2.0 authorization server.
OIDC Discovery	OIDC	rest/oauth2/authorization-servers/<as-id>/.well-known/openid-configuration	Inquire all relevant attributes of the OIDC authorization server.
Token Endpoint	OAuth 2.0 & OIDC	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	rest/oauth2/authorization-servers/<as-id>/introspect	Use this endpoint to verify the validity of a token and to 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	rest/oauth2/authorization-servers/<as-id>/revoke	Use this endpoint to revoke refresh and access tokens. It is recommended to require client authentication.
Userinfo Endpoint	OIDC	rest/oauth2/authorization-servers/<as-id>/userinfo	Inquire about metadata about the user
JWKS	OAuth 2.0 & OIDC	rest/oauth2/authorization-servers/<as-id>/jwks	Inquire public cryptographic key material used by the authorization server. For use by clients to verify signatures.
Dynamic client registration	OAuth 2.0 & OIDC	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":

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

Airlock IAM proprietary endpoints

The following endpoints have not been 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	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 13.3.1.7. AS-centric AS - SSO tickets for more information on the purpose of session tickets.
Session Management	● rest/oauth2/authorization-servers/<as-id>/session ● rest/oauth2/authorization-servers/<as-id>/session/custom-attributes/ ● rest/oauth2/authorization-servers/<as-id>/sessions ● 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 have not been 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	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	public/authentication/oauth2/authorization-server/consent/[grant\|deny]	A user agent uses this endpoint to grant or deny consent to the requested scopes.
Authentication response endpoint	IAM as client	public/authentication/oauth2/client/authorization/check	A user agent uses this endpoint to deliver the authorization response of a remote authorization server.