Re-Authentication

Suggest Edits

IBM Application Gateway (IAG) can indicate that a client should re-authenticate before accessing a resource.

Re-authentication differs to Authentication Requirements as it allows policy to be authored which requires a client to perform the re-authentication each time a resource protected by the re-authentication policy is accessed.

Re-Authentication during OIDC Scenarios

During OIDC scenarios, the syntax for re-authentication looks like the following:

policies:
  authorization:
    - name: <policyName>
      ...
      action: "reauth"
      obligation:
        oidc:
          <parameter>: <value>

When the re-authentication takes place, the parameters are included in the authentication request URL which IAG will redirect the client to. For example, when using IBM Verify as an identity provider, the a regular redirect URL looks like the following:

HTTP/1.1 302 Found
Location: https://ibm-app-gw.verify.ibm.com/oidc/endpoint/default/authorize?
  response_type=code
  &scope=openid
  &client_id=<clientId>
  &state=<state>
  &redirect_uri=<IAG>/pkmsoidc
  &nonce=<nonce>

During re-authentication with additional authentication requirements, the request parameters are appended to the end of this URL:

HTTP/1.1 302 Found
Location: https://ibm-app-gw.verify.ibm.com/oidc/endpoint/default/authorize?
  response_type=code
  &scope=openid
  &client_id=<clientId>
  &state=<state>
  &redirect_uri=<IAG>/pkmsoidc
  &nonce=<nonce>
  &<parameter>=<value>

For example, consider the following policy which:

  • For any logged in client accessing a resource which matches /reports/downloads/*
  • will be forced to re-authenticate
  • with the identity provider receiving the additional request parameter 'max_age' set to '0'
policies:
  authorization:
  - name: "require_reauth"
    paths: 
      - "/reports/downloads/*"
    rule: "anyauth"
    action: "reauth"
    obligation:
      oidc:
        max_age: "0"

When the above policy is satisfied it results in clients being redirected to the following authentication request URL to re-authenticate:

https://ibm-app-gw.verify.ibm.com/oidc/endpoint/default/authorize?
  response_type=code
  &scope=openid
  &client_id=<clientId>
  &state=<state>
  &redirect_uri=<IAG>/pkmsoidc
  &nonce=<nonce>
  max_age=0

Re-authentication window

IAG should be configured to use a re-authentication window. This is a period of time after the last re-authentication event during which a client will not be forced to re-authenticate again.

To configure the window, the 'server/session/reauth/login_time_window' parameter can be used to specify the length of the window (in seconds):

server:
  session:
    reauth:
      login_time_window: 30

In the above example, this window is configured as 30 seconds.

Tracking Re-authentication Time

To track the last re-authentication time, IAG uses the credential attribute AZN_CRED_AUTH_TIME, which is a unix timestamp containing the last time the client re-authenticated.

Using OIDC

When using OIDC as identity provider, IAG will populate this attribute with the 'auth_time' claim returned in the ID token. Note that identity providers will not always present the 'auth_time' claim. For example, in the case of IBM Verify, the 'auth_time' claim is returned if the 'max_age' parameter is presented during the authorization request. Refer to your identity provider or 3.1.2.1 Authentication Request in the OpenID Connect Core specification for more information.

The 'max_age' can be specified using the 'obligation/oidc' parameter withing the authorization policy:

policies:
  authorization:
  - name: "require_reauth"
    ...
    action: "reauth"
    obligation:
      oidc:
        max_age: "0"

The 'max_age=0' parameter is also used to indicate to the identity provider that a user-interactive authentication should take place.

🚧

The importance of 'auth_time'

Note that without the 'auth_time' claim, IAG cannot guarantee that the client actually performed a re-authentication. For this reason, it is strongly recommended that any time re-authentication is used with OIDC that the re-authentication window is used and appropriate 'obligation' parameters are specified for the identity provider.

Using External Authentication

When using external authentication, the external authentication application should present the AZN_CRED_AUTH_TIME attribute in the returned external authentication headers:

> POST /auth_app/reauth
> ...

< HTTP/1.1 200 OK
< ...
< AM-EAI-USER-ID: [email protected]
< AM-EAI-XATTRS: firstName,lastName,accessGroup,AZN_CRED_AUTH_TIME
< firstName: John
< lastName: Smith
< accessGroup: regularUsers
< AZN_CRED_AUTH_TIME: 1640280693
< AM-EAI-REDIR-URL: /app1/downloads/resource.zip
< ...

Updated almost 2 years ago