Re-Authentication
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 over 1 year ago