Authentication is a requirement when performing Federated Single sign on. This is traditionally completed via a traditional forms based authentication. However, there are several situations that require more than traditional forms based authentication. For example, some applications may have access to more sensitive data, or invoke more ‘risky’ APIs. In this instance just performing Username and password authentication is not sufficient and a 2nd factor is required.

2nd factor authentication as a requirement is not well defined today by any common federation protocols. IBM Security Access Manager (ISAM) provides a consistent way for an administrator to author policy to enforce authentication requirements during federated single sign on requests. The capability on ISAM which fulfils these requirements is known as Access Policy.

Access policy is a consistent way for an administrator to author custom authentication policy and then attach this policy to the identity providers they have configured. Currently the supported protocols are SAML 2.0 and OpenID Connect. The policy takes the form of a javascript mapping rule which has access to all of the necessary contextual information.

Access Policy was added to Security Access Manager in version 9.0.4.0, released December 2017.

Access Policy: A State Machine

The capabilities of access policies are quite extensive. The policy runs as a state machine, presenting the current request context, evaluating the rule and based on the decision returning a result. The decisions are:

• Deny
• Permit
• Challenge

When a permit is returned, the SSO will continue and a deny will halt the SSO. The challenge mechanism serves as a way of getting further information to augment the state of the SSO request.

The Challenge Decision

When access policy returns a challenge decision it results in control being returned back to the browser for further interaction. This takes its form in one of three ways:

• A 302 redirect to another AAC interface (e.g. Authentication Service)
• A 302 redirect to another server or junctioned resource
• A page template response (self hosted content) returned

When the challenge is returned, current state about the SSO request is stored in the users session to allow resuming of the SSO.

In order to return to the SSO the authentication endpoint should be called.

The goal of returning control back to the browser is for the user to go and perform additional authentication steps. This would typically include:

• Invoking an AAC Authentication policy
• Presenting a form for further details from the user to then be evaluated by the access policy.
• Invoking an existing EAI.

Combining the browser interaction with the existing components available in mapping rules allows for business specific scenarios such as:

• Brand specific login pages
• 2nd factor authentication
• Prompting the end user for further consent / interaction during the SSO.
• Performing a context based access risk evaluation

The Authentication Endpoint

The authentication endpoint on ISAM serves two purposes:

1. Federation protocols redirect to it in order to prompt the user for authentication.
2. Its used to re-enter an access policy after prompting the user for further input.

The authentication endpoint is found at/sps/auth. and is populated in the template page macro @ACTION@ in access policy.

When Does Access Policy Run

One of the key things to understand about access policy is when it occurs in a SSO request.

On ISAM when a SSO is requested, the current authenticated state of the user is checked. If the user is authenticated then the protocol endpoint does not need to do anything further to authenticate the user. However, if the user is not authenticated, they are redirected to the authentication endpoint. The way this redirect works, is the current request context (such as all of the protocol relevant  parameters) is saved in the users session,  and then the redirect to the authentication endpoint occurs. The authentication endpoint endpoint is an endpoint protected by WebSEAL, requiring authentication. So when the redirect occurs WebSEAL will cache the request, prompt the user for authentication and then replay the request once it occurs. The authentication endpoint will then resume the SSO.

Access policy runs after the authentication check step. Which means it runs in one of two places:

1. The protocol endpoint its self whether that be /authorize for OIDC, or /login for SAML 2.0
2. when the authentication endpoint is requested, after the user has been authenticated or prompted for further authentication

This information is relevant for a few reasons:

1. It means access policy runs before the prompt for consent in an OpenIDConnect flow
2. It means there is an opportunity for further browser interaction in a SAML flow(traditionally after authentication there’s no further chance for interaction)

Unauthenticated Access Policy

Because of when access policy runs, it also allows for an alternative approach to the SSO flow. By removing the ACL from the authentication endpoint, this will allow a user to be unauthenticated when they reach access policy. This is a powerful use case, as it allows for a custom authentication experience for the FSSO. This would include authentication achieved with:

1. Invoking the UserLookupHelper to authenticate the user
2. Consistent invocation of an Authentication policy
3. Simple invocation of a different EAIS based on the SSO request
4. Using the HTTP client to call out to a service to authenticate the user

This can dramatically simplify how alternative authentication can be performed for SSO. In the past authentication scenarios such as these have been achieved by attaching an ACL or POP to the SSO initiation URI. This is an anti pattern – as it causes the user to be prompted for authentication prior to any validation of the actual SSO request. The requirements of this validation occurring before user authentication is well documented in the case of OIDC.

Note: If your access policy doesn’t correctly authenticate the user but also returns permit, an error will occur when the federation step is completed. 

Note: When implementing an unauthenticated access policy, changing the ACL on the authentication endpoint may impact any other services using the same junction. When using this pattern is recommended to isolate the federation or API protection definition to its own junction. This can be achieved using the Federation config and OAuth config utilities.

Access Policy and the Authentication Service

A simple access policy integrated with the authentication service can be achieved with the
following steps.

Note: This access policy logic, would only have a user performing the authentication once per session, so multiple SSO request would not result in multiple authentications being performed.

1. Access policy invoked
2. Challenge redirect to authentication service policy
3. Authentication policy steps performed
4. Authentication policy follows Target parameter to complete flow

The final step of this policy mentions the Target parameter. This is a mechanism to direct the authentication policy that after the policy is successful, the browser should be redirected back to the Target. The following KC article shows how the target parameter is used in other scenarios here.

Access Policy and EAIs

Access policy can be coupled with an EAI in a similar fashion, access policy returns a redirect to the EAI Application, the EAI performs its authentication and then redirects the user back to the access policy.

This redirect back to the access policy can be achieved by one of two ways for the EAI. The EAI can make use of the eai-flags: stream header, and can stream back a response which redirects the user (whether it be a 302, or a self posting form). Alternatively the EAI can direct the user through native reverse proxy capabilities by including the eai-redir-url header in the authenticating response.

The EAI application can perform the checks necessary to know if authentication is required, or a similar approach to the authentication service scenario can be used, and a credential attribute checked.

A Complete Policy

Available at the link below is an access policy which ensures a resource owner has performed a 2nd factor authentication using TOTP prior to permitting a grant.

Click here to find the gist

The flow of this policy is described using the following steps an chart:

1. Check user credential for the credential attribute authentication Types

2. Check for the presence of the TOTP policy identifier

3a. If the credential value is missing, redirect to the authentication service if the TOTP identifier is not found, including a target URI to return to the SSO

3b. If the credential attribute is present, permit the SSO

Note: This policy assumes that both the authentication service and the SSO protocol have been configured using the same junction point. Learn more about: AAC config, Federation config and OAuth config.

The context object referenced in this policy(Used to get the user: var user = context.getUser(); provides request and protocol relevant information, including:

• Request parameters. For example when doing OIDC; redirect_uri, client_id, scope, response_type are all available.
• HTTP Headers
• Current request parameters,
• The user and their authenticated session, including credential attributes

 

---

Access policy simplifies how 2FA and third party authentication mechanisms can be applied to federated single sign on, including scenarios for OpenBanking, MMFA and hybrid cloud authentication.

#ISAM