We Have Moved

The IBM Application Gateway has a new home - docs.verify.ibm.com/gateway

The documentation on this site will no longer be maintained after v21.02, please update your bookmarks.

External Authentication

The External Authentication Interface (EAI) provides a mechanism for a resource server to handle the authentication process.

Conceptually, the resource server application will handle the authentication user experience and can return HTTP headers containing identity information which IAG will use to establish a credential.

Configuring External Authentication

To configure external authentication, IAG must be provided with a list of trigger URLs. These trigger URLs indicate to IAG which resources can return the external authentication HTTP headers which contain identity information.

For example, consider the following configuration:

version: 21.02

resource_servers:
  - path: /auth_app
    connection_type: ssl
    servers:
      - host: 10.10.10.200
        port: 9443

identity:
  auth_challenge_redirect: 
    url: /auth_app/login
    parameters:
    - name: originalUrl
      source: macro
      value: URL
  eai:
    triggers:
      - /auth_app/login_complete
      - /auth_app/login_complete_v2

policies:
  authorization:
    - name: eai_unauth
      paths: 
        - "/auth_app/*"
      rule: anyauth
      action: permit

1. Our external authentication application is defined as the resource server '/auth_app'.
2. Unauthenticated clients will be redirected to '/auth_app/login'. This is the login page for the external authentication application. The originally requested URL will be included as a query string parameter named 'originalUrl'.
3. The trigger URLs '/auth_app/login_complete' and '/auth_app/login_complete_v2' are registered. IAG will inspect responses for these resources for identity information headers.
4. An authorization policy which will allow all clients (authenticated and unauthenticated) is applied to the external authentication application.

External Authentication Headers

IAG will examine responses to requests sent to any of the configured trigger URLs for external authentication headers. If external authentication headers are found, IAG will create a new credential using the information contained in these headers.

At a minimum, the 'AM-EAI-USER-ID' (username) header must be provided to trigger external authentication.

Consider the following example response to a configured trigger URL:

> POST /auth_app/login_complete
> ...

< HTTP/1.1 200 OK
< ...
< AM-EAI-USER-ID: testuser@ibm.com
< AM-EAI-XATTRS: firstName, lastName, accessGroup
< firstName: John
< lastName: Smith
< accessGroup: regularUsers
< AM-EAI-REDIR-URL: /app1/welcome
< ...

This response:

1. Will trigger external authentication as the request URL matches a trigger URL and contains the 'AM-EAI-USER-ID' HTTP header.
2. A credential will be created with the username "testuser@ibm.com" from the 'AM-EAI-USER-ID' HTTP header.
3. The 'AM-EAI-XATTRS' is present and indicates that the 'firstName', 'lastName' and 'accessGroup' HTTP headers should be interpreted as credential attributes.
4. The 'AM-EAI-REDIR-URL' indicates that the client should be redirected to '/app1/welcome'.

The resulting credential will look like:

The response from the external authentication application will be intercepted by IAG and not returned to the client. The client will instead receive a 302 redirect to the URL '/app1/welcome'.

Using External Authentication and OIDC

External authentication can be used in conjunction with an OIDC identity.

If both OIDC and EAI are configured, by default IAG will redirect unauthenticated clients to start the OIDC login. To change this behavior, use the 'auth_challenge_redirect' to specify a location where unauthenticated clients should be sent to start authentication.

# Example 1
# Unauthenticated clients will be redirected to start OIDC authentication.
identity:
  oidc:
    discovery_endpoint: https://www.test.com/mga/sps/oauth/oauth20/metadata/oidc_def
    ...
  eai:
    triggers:
      - /auth_app/login_complete
      ...

# Example 2
# Unauthenticated clients will be redirected to '/auth_app/login'.
identity:
  auth_challenge_redirect: 
    url: /auth_app/login
  oidc:
    discovery_endpoint: https://www.test.com/mga/sps/oauth/oauth20/metadata/oidc_def
    ...
  eai:
    triggers:
      - /auth_app/login_complete
      ...

When using 'auth_challenge_redirect' to control the initial authentication challenge, clients can later be redirected to start the OIDC authentication process by sending them to the OIDC kick-off URL '/pkmsoidc?iss=default'.

Additionally, 'auth_challenge_redirect' can include parameters describing the original request which was redirected. See the YAML reference for Default Authentication Challenge for further information.

Sign-out with External Authentication

The External Authentication Interface can also be used to sign-out an active session or all active sessions for a given user. The mechanism works in a similar way to the sign-on process, where the external authentication application responds to a requests on any of the matching trigger URLs with headers indicating the action to take place.

Sign-out for a Single User Session

An external authentication application can indicate to IAG that a session should be terminated by providing a terminate session header and indicating the identifier for the session to terminate.

Note that the session ID is the value stored in the credential as tagvalue_user_session_id.

Sign-out for all Sessions Belonging to a User

An external authentication application can indicate to IAG that all sessions belonging to a particular user should be terminated by providing a terminate all_sessions header and indicating the username whose sessions should be terminated.