A guide to OAuth and OpenID Connect in ADSelfService Plus

Introduction

This document provides a detailed overview of the OAuth and OpenID Connect (OIDC) API endpoints available in ADSelfService Plus. OAuth is an authorization protocol that enables authenticated resource access between servers and applications without sharing login credentials. OIDC is an identity layer built on top of the OAuth framework.

The primary endpoints covered in this documentation include:

• Authorization endpoint: This endpoint initiates a user authentication or authorization request to the target identity provider.
• Token endpoint: This endpoint exchanges an authorization code for an access token.
• UserInfo endpoint: This endpoint retrieves the authenticated user's profile information for the provided access token.
• Keys endpoint: This endpoint provides public keys used for token verification.
• Token revocation endpoint: This endpoint revokes the provided token when the service provider decides to remove it.
• Well-known configuration endpoint: This OIDC endpoint provides metadata about the IdP, enabling clients to discover and interact with it.

You can refer to this document for more information on OAuth and OIDC.

Flow diagram of the OAuth authentication process

1. Authorization endpoint

Description: This endpoint initiates the authentication flow, allowing the client application to request user authentication and obtain an authorization code for session establishment. The user is redirected to the identity provider's (IdP) login page to authenticate. Upon successful authentication, the server responds with an authorization code that can later be exchanged for an ID token and access token.

URL: https://<ADSSP_SERVER_URL:PORT>/sso/oauth/e20.....5f7/authorize

Method: GET

Parameters:

• client_id: The client application's ID.
• redirect_uri: The URI to redirect to the service provider (SP), which is the target application, after authorization.
• response_type: The desired grant type, typically 'code', 'token', or 'id_token'.
• scope: The requested scopes for access. E.g., openid, email, profile, or offline_access.
• response_mode: Determines how the authorization response should be returned to the client. E.g., query, form_post, or fragment.

Sample request:

GET /authorize?client_id=<CLIENT_ID>&redirect_uri=<REDIRECT_URI>&response_type=code&response_mode=form_post&scope=openid profile email

Sample response:

Upon successful authentication: Redirects to the redirect_uri with the authorization code (e.g., code=<AUTHORIZATION_CODE>).

2. Token endpoint

Description: This endpoint is where the application exchanges the authorization code (obtained from the authorization endpoint) for an access token.

URL: https://<ADSSP_SERVER_URL:PORT>/sso/oauth/e20.....5f7/token

Method: POST

Headers:

• Content-Type: application/x-www-form-urlencoded (except for JSON web token (JWT) methods, where it may vary)
• Authorization: Varies based on the authentication mode.

Body parameters:

• grant_type: Specifies the grant type (e.g., authorization_code).
• code: The authorization code for the authorization_code grant type.
• redirect_uri: The redirection URI used in the authorization request (optional, depending on the grant type).
• client_id: The client application’s ID.
• client_secret: The client secret (if applicable).

Sample request:

Sample response:

{ "access_token": "<ACCESS_TOKEN>", "token_type": "Bearer", "expires_in": 3600, "refresh_token": "<REFRESH_TOKEN>", "id_token": "<ID_TOKEN>" }

Client authentication modes

Client authentication modes in OAuth offer various mechanisms for client applications to securely authenticate with the authorization server when exchanging authorization grants for tokens. The following are the OAuth client authentication modes that ADSelfService Plus supports:

• Client secret basic
• Client secret post
• Client secret JWT
• Proof key of code exchange (PKCE) code challenge
• Private key JWT

a. Client secret basic

Description: This authentication mode uses HTTP Basic Authentication to transmit the client_id and client_secret in the authorization header as a Base64-encoded string.

Headers:

• Authorization: Basic Base64(<CLIENT_ID>:<CLIENT_SECRET>)

Body parameters: grant_type, code, redirect_uri

Example request:

b. Client secret post

Description: This authentication mode includes both client_id and client_secret in the body of the POST request.

Body parameters: client_id, client_secret, grant_type, code, redirect_uri

Example request:

c. Client secret JWT

Description: This authentication mode uses a JWT signed with the client_secret in the body of the POST request.

Body parameters: client_assertion, client_assertion_type, grant_type, code, redirect_uri

Example request:

Steps to create a signed JWT:

• Construct a JWT:
  • The JWT payload typically contains:
    • iss (issuer): Your Client ID.
    • sub (subject): Your Client ID again.
    • aud (audience): The token endpoint URL of the authorization server.
    • exp (expiration): Expiry time of the token (e.g., current time + 5 minutes).
    • iat (issued at): The current timestamp.
  • The JWT header contains:
    • alg (algorithm): Algorithm used for signing.
    • typ as JWT
• Sign the JWT:
  • Use the client secret as the signing key.
  • Encode and sign the JWT using the specified algorithm (eg: RS256).
  • You can refer to the corresponding JWT library related to your application's native language.
• Include the signed_jwt in the client_assertion parameter when making requests to the token endpoint.

Example JWT header:

Example JWT payload:

3. UserInfo endpoint

Description : This endpoint provides profile details of the authenticated user, such as username, email, and other identity information. It requires an access token obtained from the token endpoint (refer to s.no.2) and returns information based on the granted scopes.

URL : https://<ADSSP_SERVER_URL:PORT>/sso/oauth/e20.....5f7/userinfo

Method: POST

Headers :

• Authorization: Bearer <ACCESS_TOKEN>

Sample response:

4. Keys endpoint

Description: This endpoint, which requires no authentication, publishes the public keys used by the OAuth server to sign tokens. Applications can use these keys to verify the authenticity and integrity of tokens, ensuring they haven't been tampered with and originate from a trusted source.

URL: https://<ADSSP_SERVER_URL:PORT>/sso/oauth/e20.....5f7/keys

Method: GET

Sample response:

5. Token revocation endpoint

Description: This endpoint allows the application to revoke a specific token, whether it is an access token or a refresh token. It requires client authentication using any of the authentication methods listed under the token endpoint (s.no.2) to verify the client's identity when requesting token revocation.

URL: https://<ADSSP_SERVER_URL:PORT>/sso/oauth/e20.....5f7/revoke

Method: POST

Headers:

• Content-Type: application/x-www-form-urlencoded
• Authorization: Basic Base64(<CLIENT_ID>:<CLIENT_SECRET>)

Body parameters:

• token: The token to be revoked.
• token_type_hint: Hint about the token type ('access_token' or 'refresh_token').

Sample request:

Sample response:

On Success: Returns HTTP 200.

6. Well-known configuration endpoint

Description: This OIDC endpoint provides metadata about the IdP, enabling clients to discover and interact with it. It is obtained when the application is configured in ADSelfService Plus and requires no authentication.

URL: https://<ADSSP_SERVER_URL:PORT>/sso/oauth/e20.....5f7/.well-known/openid-configuration

Method: GET

Key response parameters:

The response from this endpoint typically includes the following parameters in a JSON format:

• issuer: The URL that identifies the IdP.
• authorization_endpoint: The URL to which clients send authorization requests.
• token_endpoint: The URL for obtaining access tokens and ID tokens.
• userinfo_endpoint: The URL for retrieving user profile information.
• jwks_uri: The URL of the JSON web key set (JWKS) endpoint for retrieving public keys to verify tokens.
• token_revoke_endpoint: The URL to revoke a specific token.
• response_types_supported: An array of supported response types.
• id_token_signing_alg_values_supported: An array of supported algorithms for signing ID tokens.
• scopes_supported: An array of supported scopes.
• token_endpoint_auth_methods_supported: An array of supported authentication methods for the token endpoint.
• grant_types_supported: An array of supported grant types.
• response_modes_supported: An array of supported response modes.