OAuth API authorization - BlueCat Integrity - 26.1.0

Address Manager Administration Guide
ft:locale
en-US
Product name
BlueCat Integrity
Version
26.1.0

OAuth is an authorization protocol that secures API endpoints as part of machine-to-machine communication between API clients. Unlike SAML, which focuses on authentication of web clients, OAuth focuses on what actors have access to, not who the actor is. The OAuth 2.0 specification includes four actors: the Resource Owner (the user), the Client (an application or script that needs access to the Address Manager API), the Authorization Server (OAuth2 Server, Open ID Connect), and the Resource Server (Address Manager API). The authorization server issues access tokens (used to authenticate a request to an API endpoint) to the client and an authorization grant defines how the client obtains the access token. For more information on authorization grants, refer to https://tools.ietf.org/html/rfc6749.

How OAuth works with Address Manager

Address Manager allows the following authorization grants:
  • Authorization Code Grant
  • Implicit Grant
  • Resource Owner Password Credentials Grant
  • Client Credentials Grant

Authorization Code Grant

In this authorization grant, the user is authenticated through a login page (the user-agent) hosted by the authorization server.

The following diagram explains the Authorization Code grant:

  1. Client redirects user-agent to authorization server
  2. Authorization server authenticates the user through the user-agent
  3. If authentication of the user is successful and the user grants access to the requested resource, the authorization server returns an authorization code and redirects the user to the client
  4. Client requests an access token from authorization server by including authorization code
  5. Authorization server authenticates client
  6. Client uses access token to access the resource on the resource server

Implicit Grant

Similar to the Authorization Code grant, the user is authenticated through a login page (the user-agent) hosted by the authorization server, but instead of an authorization code, the access token is directly returned to the client.

The following diagram explains the Implicit grant:

  1. Client redirects user-agent to authorization server
  2. Authorization server authenticates the user through the user-agent
  3. If authentication of the user is successful and the user grants access to the requested resource, the authorization server returns an access token in fragment and redirects the user to the client
  4. User-agent makes a request to web-hosted client resource without fragment
  5. Web-hosted client returns a script to user-agent that can extract access token
  6. User-agent executes script to extract access token
  7. User-agent passes access token to the client
  8. Client uses access token to access the resource on the resource server

Resource Owner Password Credentials Grant

In this authorization grant, the client requires credentials from the user––this grant does not involve a login page hosted by the authorization server.

The following diagram explains the Resource Owner Password Credentials:

  1. User enters username and password in client application
  2. Client forwards credentials to authorization server
  3. Authorization server returns access token to client application
  4. Client application calls Address Manager with access token

Client Credentials Grant

The Client Credentials Grant is used for client-to-service (machine-to-machine) communication. The client authenticates using its own credentials, and no end user is involved in the authentication flow. Address Manager requires that OAuth access tokens include a sub (subject) claim and groups claims for authorization. These claims may not be included by default in Client Credentials Grant flows and may require configuration at the Identity Provider (IdP). Client Credentials Grant is supported when the IdP can issue access tokens and is configured to include the required claims. This has been validated with the following IdPs:

  • Active Directory Federation Services (ADFS)
  • PingFederate

Support for other IdPs depends on their ability to issue access tokens and customize claims. IdPs that issue opaque tokens or do not support claim customization may not be compatible.

The following diagram explains the Client Credentials Grant:

  1. The client authenticates with the authorization server using its client_id and client_secret to request an access token.
  2. The authorization server validates the client and issues an access token. The token must be configured to include a sub claim (identifying the client) and groups claims.
  3. The issued access token must contain groups claims that correspond to SSO groups configured in BlueCat Address Manager for authorization.
  4. The client calls BlueCat Address Manager using the access token, and access is granted based on the sub and groups claims in the token.