IBM Security Verify Access

IBM Security Verify Access (formerly IBM Security Access Manager) provides user-friendly access management and multifactor authentication to help organizations maintain security as they adopt new technologies. It can be configured to act as an identity provider for the IBM Application Gateway (IAG) by:

1. acting as an OpenID Connect Provider (OP); or
2. validating OAuth bearer tokens using the OAuth Introspection endpoint.

Generally OIDC is used to protect Web applications and OAuth tokens are used to protect Web APIs.

OpenID Connect

Overview

OpenID Connect is a simple identity protocol and open standard that is built using the OAuth 2.0 protocol. It enables client applications to rely on authentication that is performed by an OpenID Connect Provider (OP) to verify the identity of a user. OpenID Connect uses OAuth 2.0 for authentication and authorization, and then builds identities that uniquely identify users.

The IAG provides a native OpenID Connect relying partner (RP) capability that is able to consume an identity token which has been provided by the Security Verify Access OP in order to establish an authenticated session.

Authentication Flows

The OIDC specification states that authentication can follow one of three paths: the Authorization Code Flow, the Implicit Flow, or the Hybrid Flow. The flow determines how the ID Token and Access Token are returned to the Client. The Authorization Code Flow and the Implicit Flow are described below (please note that the IAG does not support the Hybrid Flow).

The Authorization Code flow is the default and recommended flow for the IAG, but it does require direct connectivity from the IAG container to the Security Verify Access OP. If direct connectivity is not possible the Implicit Flow may be used - although this flow is not recommended and is now considered a security best practices anti-pattern. There are two subtle variations to the Implicit flow, differentiated by the originator of the self-posting form (this form is used to POST the authentication tokens to the RP):

1. The 'fragment' sub-flow uses a self-posting form which is served from the IAG container;
2. The 'form-post' sub-flow uses a self-posting form which is returned from the Security Verify Access OP as a result of the authentication process.

Authorization Code Flow

Implicit Flow (fragment)

Implicit Flow (form-post)

Configuration

IBM Security Verify Access

To configure the OIDC flow between Security Verify Access and IAG you need to have an existing IBM Security Verify Access or IBM Security Access Manager 9.0.7.0+ OIDC OP. If you do not already have one you can follow the IBM Security Verify Access Federation Cookbook, paying particular attention to Chapter 13 (OpenID Connect), to configure an OIDC Identity Provider.

Additional information on how to create an OIDC OP can be found in the IBM Security Verify Access documentation: https://www.ibm.com/support/knowledgecenter/en/SSPREK_9.0.7/com.ibm.isam.doc/config/concept/oauth.html.

In order to configure the IAG to act as an RP the following Security Verify Access information will be required:

1. Discovery Endpoint;
2. Client ID;
3. Client Secret;
4. IBM Security Verify Access CA certificate.

IAG Container

The following initial tasks should be completed in order to protect a Web application using IBM Security Verify Access or IBM Security Access Manager 9.0.7.0+:

An example configuration YAML file which illustrates this scenario is available at: https://www.ibm.com/docs/iag/24.12.0?topic=examples-oidc-verify-access-yaml.

OAuth Introspection

Overview

Bearer Tokens are the predominant type of access token used with OAuth 2.0.

A Bearer Token is an opaque string, not intended to have any meaning to clients using it. Some servers will issue tokens that are a short string of hexadecimal characters, while others may use structured tokens such as JSON Web Tokens.

The IAG can receive an OAuth Bearer Token in a HTTP 'authorization' header, and then call out to an OAuth introspection endpoint to validate the bearer token. The information contained within the introspection response is then used to establish an authenticated session.

Authentication Flows

The first thing which an API client must do in the flow is obtain an OAuth Access token from the OAuth identity provider. If IBM Security Verify Access is the identity provider this can be achieved by accessing the token endpoint (https://{verify-access-hostname}/{junction}/sps/oauth/oauth20/token).

This access token can then be provided as a Bearer Token to the IBM Application Gateway in the 'authorization' HTTP header of the request. For example:

Authorization: Bearer wj0LQ4tPUDTz5LIleVLQkgUc1punUKUfFnBmWy1p

The following diagram highlights the flow:

Configuration

IBM Security Verify Access

To configure the OAuth Introspection flow between Security Verify Access and IAG you need to have an existing IBM Security Verify Access or IBM Security Access Manager 9.0.3.0+ environment with an API Protection definition. If you do not already have one you can follow the IBM Security Verify Access Federation Cookbook, paying particular attention to Chapter 13.1 (OpenID Connect Provider), to configure an API Protection definition.

Additional information on how to create an API Protection definition can be found in the IBM Security Verify Access documentation: https://www.ibm.com/support/knowledgecenter/SSPREK_10.0.0/com.ibm.isva.doc/config/concept/OAuthConfiguring.htm#oauthconfiguring.

In order to configure the IAG for OAuth token introspection the following IBM Security Verify Access information will be required:

1. Introspection URL;
2. Client ID;
3. Client Secret.

IAG Container

The following initial tasks should be completed in order to protect a Web application using IBM Security Verify Access or IBM Security Access Manager 9.0.3.0+:

An example configuration YAML file which illustrates this scenario is available at: ../examples/oauth-isva.