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

<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

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

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

  • This 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 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

<loginapp-uri>/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

<loginapp-uri>/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

<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 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

<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.

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 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",
"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 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

<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 AS-centric AS - 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 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

<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.