IBM Security Verify

IBM Security Verify (formerly IBM Cloud Identity) helps you secure user productivity with cloud-delivered Single Sign-On (SSO), multifactor authentication, and identity governance. 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 IBM Security Verify 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 IBM Security Verify 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 IBM Security Verify OP as a result of the authentication process.

Authorization Code Flow

Implicit Flow (fragment)

Implicit Flow (form-post)

Configuration

IBM Security Verify

To configure the OIDC flow between IBM Security Verify and IAG you have to first create a IBM Security Verify application, using the 'IBM Application Gateway' template, to represent the IAG application.

Information on how to create an application can be found in the IBM Security Verify documentation: https://www.ibm.com/support/knowledgecenter/en/SSCT62/com.ibm.iamservice.doc/tasks/t_applications.html#t_applications__create_app.

The application configuration screen will have some of the application fields pre-configured for IAG. At a minimum the following sign-on fields will need to be provided:

1. Application URL;
2. Redirect URIs.

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

1. Security Verify endpoint;
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:

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

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 is the identity provider this can be achieved by accessing the token endpoint (https://{tenant}/v1.0/endpoint/default/token). An example curl command which illustrates how to retrieve an Access Token from IBM Security Verify is available in the product documentation: https://www.ibm.com/support/knowledgecenter/SSCT62/com.ibm.iamservice.doc/concepts/get_access_token.html.

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

To support OAuth introspection you first need to create an API client for IBM Security Verify using the 'API Access' tab from the Configuration panel of the management UI:

Information on how to create an API client can be obtained from the product documentation: https://www.ibm.com/support/knowledgecenter/SSCT62/com.ibm.iamservice.doc/tasks/api_clients.html#api_clients.

In order to configure the IAG for OAuth token introspection the following IBM Security Verify 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 API using IBM Security Verify:

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