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.
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
- 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
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.
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.
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 188.8.131.52 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.
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 about 1 year ago