Authorization

One of the key capabilities of the IBM Application Gateway (IAG) is being able to apply authorization policies to requests, controlling who is able to access your protected resources.

Policy Definition

The authorization policy is made up of a collection of rules. There are a couple of main elements which are important to understand when constructing the authorization policy:

Rule Matching

A rule will be evaluated for matching resources only. There are three elements which are used to match a resource:

In other words, a rule will be considered a match for a resource request if the path, host header and HTTP method matches the request.

Rule Definition

A rule is a logical expression which is used to compare the user attributes, as obtained during the authentication processing, against required values.

The following operators can be used when constructing the rule:

logical operators:

multi-valued operators:

relational operators:

Simple Rule

A 'simple' rule usually consists of three elements:

1. A user attribute name;
2. A relational operator;
3. A literal value (literal values are always enclosed in double or single quotes).

For example:

name = "alice"

Complex Rules

A 'complex' rule consists of a number of 'simple' rules, separated by logical operators. Parenthesis should be used to control the evaluation order of the simple rules.

For example:

(not ((name = "scott") or (name = "alice"))) and (any groupIds = "admin")

The above rule will evaluate to true if the user is not scott or alice, and they are a member of the admin group.

Pre-Defined Rules

The following pre-defined rules can also be used:

Rule Action

A rule will evaluate to either true or false. If a rule evaluates to 'true' the configured rule action will then be used to determine the overall authorization decision. The possible actions include:

If no action is specified the default is 'permit'.

Obligation

If the rule action is 'obligate' or 'reauth', the obligation node defines additional parameters about the authentication or re-authentication that should take place. Depending on the configured identity source, the format of the obligation data can look different.

Obligation for OIDC Scenarios

For OIDC scenarios, the obligation data is a map of string values. The parameter and values are appended to the authorization request when authentication or re-authentication takes place. See Authentication Requirements for further information.

obligation:
  oidc:
    <parameter>: <value>

Obligation vs Re-Authentication

The 'obligate' action is suitable for "stepping-up" a client - that is, changing their current level of authentication. For example, an obligation may require the client to perform a second factor authentication, which upon completing is maintained within their credential for the remainder of the session.

A 'reauth' action is similar but is triggered every time the resource is accessed. For example, a re-authentication can take place every single time a client accesses a sensitive resource.

Authorization Logic

The authorization policy comprises of an ordered sequence of authorization rules. When making an authorization decision each rule will be examined in turn. If the rule matches the request it will be evaluated. If the rule evaluates to 'true' the result of the authorization decision is determined from the corresponding rule action. Each rule will be examined in order until a matching rule evaluates to 'true'. The default rule, which will be used if the end of the list of configured rules is reached, is to grant access to any authenticated user.

The following diagram illustrates the logic which is used:

An example authorization policy is defined below:

policies:
  authorization:
  
    # Alice has left the team and is no longer allowed
    # access to any data.
    - name: alice
      paths: 
        - /*
      rule: "(user = 'alice')"
      action: deny
      
    # Allow unauthenticated access to /public.
    - name: unauth
      paths: 
        - /public/*
      methods:
        - GET
      rule: anyuser
      action: permit
      
    # Allow any authenticated user to retrieve their
    # account information.
    - name: account
      paths: 
        - /account/*
      methods:
        - GET
      rule: anyauth
      action: permit

    # Updates to account information can only be completed
    # after the user has completed stronger authentication.
    - name: account_update
      paths: 
        - /account/*
      methods:
        - POST
      rule: "(acr = 'urn:ibm:security:policy:id:2')"
      action: permit
      
    # We can use and obligation to trigger a re-authentication
    # to prompt the client to complete strong authentication.
    - name: account_update_obligation
      paths: 
        - /account/*
      methods:
        - POST
      rule: "(acr != 'urn:ibm:security:policy:id:2')"
      action: obligate
      obligation:
        oidc:
          acr_values: urn:ibm:security:policy:id:2

    # A reauth action can be used to force the client to perform
    # re-authentication.
    - name: download_report_reauth
      paths:
        - /account/reports/download/*
      rule: "anyauth"
      action: "reauth"
      obligation:
        oidc:
          max_age: 0

    # In order to be able to manage accounts you must be
    # an administrator.
    - name: manage
      paths: 
        - /account/*
      rule: (any groupIds = "admin")
      action: permit
      
    # We want to deny access to every other resource.
    - name: deny_all
      paths: 
        - /*
      rule: anyuser
      action: deny

Configuration

The authorization rules are configured as authorization polices on the server. Information on how to define the authorization policy is available in the Defining the Authorization Policy page.

Debugging

It is absolutely critical that the authorization policy is authored correctly for the environment. This can potentially be a complex task, and as such it is relatively easy to make mistakes.

There are two mechanisms which can be used to help validate and debug the authorization policy:

Credential Viewer

The in-built credential viewer application can be used to display the user attributes contained within an active session. This is useful in determining which attributes are available when defining the authorization rules. For information on enabling the in-built credential viewer application refer to the Credential Viewer YAML reference page.

Tracing

Tracing can be enabled within the authorization logic to help debug the actual rules that have been created, and to also debug the logic which was followed to reach a decision. The trace component name for the authorization logic is: iag.azn.

The configured trace level will control the amount of trace information generated. As a general guide:

Further information on managing tracing within IAG is available in the Enabling Tracing page.