URLs and endpoints
13.3.1.1. 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.