Skip to main content

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

Header Name Purpose Example
AM-EAI-USER-ID The value of this header is interpreted as the username. testuser@ibm.com
AM-EAI-XATTRS This header contains a comma separated list of other header names which should be interpreted as credential attributes. (Optional) firstName, lastName, accessGroup
AM-EAI-REDIR-URL This header can be used to specify a URL that the client should be redirected to. (Optional) /app1/welcome

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:

Attribute Name Attribute Value(s)
AZN_CRED_AUTHNMECH_INFO EAI Authentication
AZN_CRED_AUTHZN_ID testuser@ibm.com
AZN_CRED_AUTH_EPOCH_TIME (time the credential was created)
AZN_CRED_AUTH_METHOD ext-auth-interface
AZN_CRED_BROWSER_INFO (client user-agent)
AZN_CRED_IP_FAMILY (client IP family)
AZN_CRED_MECH_ID ext-auth-interface
AZN_CRED_NETWORK_ADDRESS_STR (client IP address)
AZN_CRED_PRINCIPAL_NAME testuser@ibm.com
AZN_CRED_QOP_INFO (client QOP info)
AZN_CRED_REGISTRY_ID testuser@ibm.com
AZN_CRED_USER_INFO testuser@ibm.com
accessGroup regularUsers
firstName John
lastName Smith
tagvalue_login_user_name testuser@ibm.com
tagvalue_session_index (session index)
tagvalueusersession_id (session identifier)

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.

Header Name Format Purpose Example
AM-EAI-SERVER-TASK terminate session <session_id> The session corresponding to <session_id> will be destroyed. terminate session abc...:default

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.

Header Name Format Purpose Example
AM-EAI-SERVER-TASK terminate all_sessions <username> The session corresponding to <session_id> will be destroyed. terminate all_sessions testuser@ibm.com