Policy-based Authentication

Introduction

When building consumer applications, design teams and developers usually want to have full control over the user experience. This can be in conflict with the need to centrally enforce the authentication steps required for application access.

IBM Security Verify allows definition of access policies which control the authentication steps that are required for application access. Access policies can specify different authentication requirements based on properties of the user or connection. They can even be dynamic based on the advanced risk determination capabilities of Adaptive Access.

For applications which perform native authentication directly against the IBM Security Verify APIs, native application access policies can be enforced as part of security token acquisition, leading the developer through the required authentication steps while allowing them complete control over the user experience.

Native application access policies

A native application access policy has two parts. The first part specifies the first contact rules that control initial first factor authentication. The second part specifies the policy rules that control second factor authentication.

First contact rules are evaluated before authentication and so there is limited context available. First contact rules can be based on either geo-location (derived from client IP address) or on OAuth 2.0 client type. The decision from the first contact rules can either be to deny access or to specify a list of allowed first factor authentication methods.

Policy rules are evaluated after initial authentication is complete. As such, they have access to a much richer context which includes user information and, optionally, adaptive access results. The decision from the policy rules can be either to allow access, deny access, or to require second factor authentication via a specified set of second factor authentication methods.

The "policyauth" grant type

To allow enforcement of native application access policies, as part of OAuth 2.0 token acquisition, IBM Security Verify introduces the custom "policyauth" OAuth 2.0 grant type. When a request is made to the IBM Security Verify OAuth 2.0 token endpoint with this grant type, the first contact rules in the policy are evaluated.

If the first contact rules determine that access should be denied, a deny response is returned to the caller.

If the first contact rules determine that access should be allowed, a list of allowed factors is returned to the caller along with an access token which has a special scope of mfa_challenge. This access token can be used to access only the API endpoints required to complete first factor authentication.

{
    "access_token": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "allowedFactors": [
        "password"
    ],
    "scope": "mfa_challenge",
    "grant_id": "11111111-1111-1111-1111-111111111111",
    "token_type": "Bearer",
    "expires_in": 1800
}

Completing first factor authentication

First factor authentication is completed as normal using the Access Token provided by the Policy Auth flow. On completion of first factor authentication, the API client receives a JSON Web Token (JWT) which embodies the identity of the authenticated user and the completed first factor.

{
    "assertion": "eyJhbGciOiJSUzI1NiIsI..."
}

This JWT must then be used in a JWT Bearer OAuth 2.0 grant flow to initiate evaluation of the policy rules in the access policy.

Evaluation of policy rules

When the JSON Web Token (JWT) received from the first factor authentication flow is presented to the IBM Security Verify OAuth 2.0 token endpoint, as part of a JWT Bearer grant flow, this initiates evaluation of the policy rules in the native application access policy.

If the policy rules determine that access should be denied, a deny response is returned to the caller.

If the policy rules determine that access should be allowed (with no further authentication required), the security and/or identity tokens requested in the initial request to the token endpoint are returned to the caller. Authentication is complete.

If the policy rules determine that additional authentication is required, a list of allowed factors is returned to the caller along with a new interim access token. This access token is associated with the user that completed first factor authentication but has a special scope of mfa_challenge which limits its permissions.

{
    "access_token": "yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy",
    "allowedFactors": [
        "emailotp",
        "totp",
        "signatures"
    ],
    "scope": "mfa_challenge",
    "grant_id": "11111111-1111-1111-1111-111111111111",
    "token_type": "Bearer",
    "expires_in": 1800
}

Completing second factor authentication

Second factor authentication is completed as normal using the Access Token returned from the JWT Bearer flow. On completion of second factor authentication, the API client receives another JSON Web Token (JWT) which embodies the identity of the authenticated user and the completed first factor and second factor authentication methods.

This JWT must then be used in another JWT Bearer OAuth 2.0 grant flow to receive the security and/or identity tokens requested in the initial request to the token endpoint. The OAuth 2.0 grant is updated to reflect the completed first and second factor authentication mechanisms. Authentication is complete.

{
    "access_token": "zzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz",
    "grant_id": "11111111-1111-1111-1111-111111111111",
    "token_type": "Bearer",
    "expires_in": 7200
}

💎

Jon Harry, IBM Security