External authentication

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: "26.06.0"

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.

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.