Authentication Requirements

IBM Application Gateway (IAG) can indicate authentication requirements to identity providers.

Conceptually, authorization policy can be used to emit additional parameters to the identity provider when the authentication takes place. This is achieved by authoring policy with an action of 'obligate' and defining an 'obligation' node containing the parameters.

Authentication Requirements during OIDC Scenarios

During OIDC scenarios, the syntax for obligations looks like the following:

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

When the authentication or 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 an obligation 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:

When the credential does not contain the field 'acr' with the value 'urn:ibm:security:policy:id:2';
will perform an obligation to authenticate or re-authenticate;
with the additional request parameter 'acr_values' set to 'urn:ibm:security:policy:id:2'

policies:
  authorization:
  - name: "enforce_2fa"
    paths: 
      - "*"
    rule: 'acr != "urn:ibm:security:policy:id:2"'
    action: "obligate"
    obligation:
      oidc:
        parameter:
          acr_values: "urn:ibm:security:policy:id:2"

When the above policy is satisfied it results in clients being redirected to the following authentication request URL to authenticate or 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>
  acr_values=urn%3Aibm%3Asecurity%3Apolicy%3Aid%3A2

Understanding OIDC Request Parameters

The OpenID Connect Core specification defines the authentication request and parameters in 3.1.2.1 Authentication Request. Obligations can be used to provide the OPTIONAL request parameters listed in the specification, or any other private parameters which may be implemented by your identity provider.

acr_values

A string of ACR (Authentication Context Class References) to pass to the identity provider.

📘
Note
Note that acceptable acr_values will differ based on the identity provider, refer to your identity provider for further information.

Typically the 'acr_values' are used to control the authentication experience which the identity provider should provide. This can be a space separated string consisting of multiple ACR in order of precedence. The identity provider should indicate which authentication actually took place using the 'acr' field in the returned token.

acr_values for IBM Security Verify

IBM Security Verify uses the 'acr_values' to select which access policy should take effect during the authentication.

Access policies can be referred to by their numerical unique policy ID, which is a low number (one or two digits) for the default policies or a large number (five digits) for custom policies.

The Access Policies page in the IBM Security Verify Knowledge Center provides details about the inbuilt policies.
Custom policies can be authored using the Policy Editor. To retrieve the unique policy ID for a custom access policy, follow the "Edit or delete a rule" process. On the "Edit policy" page, the Unique ID is a five digit identifier shown underneath the policy name.

When referring to a policy in the 'acr_values' or 'acr' field, they must be prefixed with 'urn:ibm:security:policy:id:'. For example, to refer to the inbuilt access policy "Allow access from managed mobile devices; others require 2FA" which has a unique policy ID of '2', use:

urn:ibm:security:policy:id:2

When the authentication is completed, IBM Security Verify will provide an 'acr' value in the token returned to IAG which indicates which access policy/authentication experience took place. This value is stored in the credential and can be used when authoring policy rules. Note that this field is named 'acr', as opposed to the request parameter which is named 'acr_values'.

Below is an example which illustrates how it is possible to write an authorization rule which requires the access policy "Allow access from managed mobile devices; others require 2FA" to take place.

policies:
  authorization:

    #
    # The path '/secure' requires the "Allow access from managed mobile 
    # devices; others require 2FA" access policy. This is a inbuilt policy
    # with the unique policy ID of '2', so we refer to it using the value
    # 'urn:ibm:security:policy:id:2'.
    # 

    #
    # If we do not have acr != 'urn:ibm:security:policy:id:2', obligate the
    # client to authenticate/re-authenticate passing request parameters to
    # IBM Security Verify to indicate we want this specific access policy
    # applied.
    #
    - name: "obligate_2fa"
      paths: 
        - "/secure"
      rule: "acr != 'urn:ibm:security:policy:id:2'"
      action: "obligate"
      obligation:
        oidc:
          acr_values: "urn:ibm:security:policy:id:2"

    #
    # If we have acr = 'urn:ibm:security:policy:id:2', the access policy is
    # satisfied and access will be permitted.
    #
    - name: "permit_2fa"
      paths: 
        - "/secure"
      rule: "acr = 'urn:ibm:security:policy:id:2'"
      action: "permit"

When a client enters the "obligate_2fa" authorization policy:

the client is redirected to IBM Security Verify for authentication
the parameter 'acr_values=urn:ibm:security:policy:id:2' is presented to IBM Security Verify
if the client has not yet logged in, they will be prompted to login
IBM Security Verify will challenge the client to complete 2FA
after completing 2FA, IBM Security Verify will return the client to IAG
IBM Security Verify will return an access token indicating 'acr = urn:ibm:security:policy:id:2'
the client can now reattempt the request, where it will not match "obligate_2fa" but will match "permit_2fa"

Using multiple access policies

After each authentication, the value for 'acr' in the credential is replaced with the last value provided by the identity provider. If you are authoring a policy which involves multiple access policies, ensure this is taken into consideration.

For example, consider a scenario where policy '2' (Allow access from managed mobile devices; others require 2FA) is used for some resources and policy '8' (Require 2FA each session in compliant mobile devices; block otherwise) is used for some other resources. If the rule which obligates policy '2' should be considered satisfied if the client has already satisfied policy '8', include it in the rule logic.

policies:
  authorization:

    #
    # The path '/secure' requires acr = 'urn:ibm:security:policy:id:2' or
    # acr = 'urn:ibm:security:policy:id:8'. This means that if a client has
    # already satisfied policy '8', they will be allowed access to this 
    # resource without having to complete policy '2'.
    #

    - name: "obligate_2fa"
      paths: 
        - "/secure"
      rule: "(acr != 'urn:ibm:security:policy:id:2') and (acr != 'urn:ibm:security:policy:id:8')"
      action: "obligate"
      obligation:
        oidc:
          acr_values: "urn:ibm:security:policy:id:2"

    - name: "permit_2fa"
      paths: 
        - "/secure"
      rule: "(acr = 'urn:ibm:security:policy:id:2') or (acr = 'urn:ibm:security:policy:id:8')"
      action: "permit"

    #
    # The path '/sensitive' requires acr = 'urn:ibm:security:policy:id:8'
    #

    - name: "require_managed_device"
      paths: 
        - "/sensitive"
      rule: "(acr != 'urn:ibm:security:policy:id:8')"
      action: "obligate"
      obligation:
        oidc:
          acr_values: "urn:ibm:security:policy:id:8"

    - name: "permit_managed_device"
      paths: 
        - "/sensitive"
      rule: "acr = 'urn:ibm:security:policy:id:8'"
      action: "permit"

prompt

A string of values which indicate how and if the identity provider should prompt the user during authentication.

📘
Note
Note that acceptable prompt values will differ based on the identity provider, refer to your identity provider for further information.

Typically the 'prompt' values are used to control whether or not the identity provider should prompt the user during authentication if they are not already authenticated.

prompt for IBM Security Verify

IBM Security Verify can use the prompt parameter with the value of 'login' to display the login page and require the client to authenticate again, regardless of whether or not they are already authenticated or could fulfil any required acr_values.

For example, consider the following scenario:

policies:
  authorization:

    #
    # The path '/secure' requires the "Allow access from managed mobile 
    # devices; others require 2FA" access policy. This is a inbuilt policy
    # with the unique policy ID of '2', so we refer to it using the value
    # 'urn:ibm:security:policy:id:2'.
    # 

    #
    # If we do not have acr != 'urn:ibm:security:policy:id:2', obligate the
    # client to authenticate/re-authenticate passing request parameters to
    # IBM Security Verify to indicate we want this specific access policy
    # applied. We are also including 'prompt: login' which means that the
    # client will be asked to login again during the obligation.
    #
    - name: "obligate_2fa"
      paths: 
        - "/secure"
      rule: "acr != 'urn:ibm:security:policy:id:2'"
      action: "obligate"
      obligation:
        oidc:
          acr_values: "urn:ibm:security:policy:id:2"
          prompt: "login"

    #
    # If we have acr = 'urn:ibm:security:policy:id:2', the access policy is
    # satisfied and access will be permitted.
    #
    - name: "permit_2fa"
      paths: 
        - "/secure"
        - "/sensitive"
      rule: "acr = 'urn:ibm:security:policy:id:2'"
      action: "permit"

For a client which has already authenticated to IBM Security Verify and accesses the '/secure' resource:

When 'prompt: login' is present
- the client is prompted to login
- after logging in, the client is challenged to complete 2FA
- the client is returned to IAG
When 'prompt: login' is not present:
- the client is challenged to complete 2FA
- the client is returned to IAG

For a client which has not yet authenticated to IBM Security Verify, the behavior is the same regardless of the presence of 'prompt: login'.

Authentication Requirements