Authorization

policies/authorization[]

The gateway can apply authorization rules to incoming requests. This entry defines a list of matching requests, rules and actions to perform if matches are found. The rules can be either:

Defined directly here in an entry.
Defined in the authorization section and reference by name here in an entry.

This entry defines authorization rules directly. There are also two pre-defined rules which can be used:

"anyuser" : Which allows access to any user, even if they are not authenticated.
"anyauth" : Which allows access to any authenticated user.

Properties

Name	Type	Constraints	Description
name	string		A name for this policy, which is used to refer to this policy in audit events.
host	string		The host (obtained from the host header in the request) for which this policy will be applied. If no host header is specified all hosts will be matched.
paths	Array of string		The paths which this policy will be applied. Each path may contain the `*?` pattern matching characters. This entry is an array and can be used to specify multiple paths.
methods	Array of string		The method(s) which this policy applies to. If this is not defined, the policy will apply to all methods.
rule	string		If a rule string is not defined here, the gateway will look for a named rule (with the same name as this policy) in the authorization section of the configuration YAML. Refer to the authorization section of this template for an explanation of rule syntax. The predefined rules anyuser or anyauth can also be referenced here.
action	string	Values: `permit`, `deny`, `obligate`, `reauth`	Defines the action to perform if the rule matches. If the action is obligate, the obligation property must also be set for this authorization rule.
obligation	obligation

policies/authorization[]/obligation

If the action for this rule is obligate or reauth, this obligation can be used to indicate that authentication should take place again with specific parameters.

This parameter is required for policies with the 'obligation' action, and is optional for policies with the 'reauth' action.

Note that a policy can only contain one obligated action, that is, this entry must contain oidc or redirect_url.

Redirect URL Macros

The following macros are available:

Macro	Value
%USERNAME%	The current logged in user, or `unauthenticated` for unauthenticated users.
%METHOD%	The HTTP method of the request which matched this policy.
%URL%	The URL the client was attempting to access when this policy was matched.
%HOSTNAME%	The hostname (HTTP Host header) of the client request which matched this policy.
%PROTOCOL%	The protocol (`http` or `https`) which was used
%CREDATTR{<attribute_name>}%	The value of the credential attribute named by `<attribute_name>`.
%HTTPHDR{<header_name>}%	The value of the HTTP header from the client request named by `<header_name>`.

Properties

Name	Type	Constraints	Description
oidc	oidc
redirect_url	string		Allows clients to be redirected to a URL as a result of this policy evaluating successfully. This URL can contain embedded macros to include contextual information about the request and client which was obligated to be redirected to this URL. See the Redirect URL Macros table above for the available macros.

policies/authorization[]/obligation/oidc

Authentication parameters which can be used when using an OIDC identity scenario. These parameters are passed as query string parameters when the authorization endpoint is requested.

Properties

Name	Type	Description
acr_values	string	A string of ACR (Authentication Context Class References) to pass to the identity provider. Refer to "acr_values" in section 3.1.2 of the OpenID Connect Core specification for further information. Valid ACRs are defined by the identity provider. Refer to your identity provider for further information about the ACRs which it supports.
prompt	string	A string of prompt options to pass to the identity provider. Refer to "prompt" in section 3.1.2 of the OpenID Connect Core specification for further information. Prompt options are optional and may not be supported by all identity providers. Refer to your identity provider for further information about support prompt values.
max_age	number	The maximum age of the authentication. Refer to "max_age" in section 3.1.2 of the OpenID Connect Core specification for further information. Setting this to '0' indicates to the provider that the user should re-authenticate immediately. This parameter also forces the provider to include the auth_time parameter in the returned id token, which is used by IAG to determine when the user last performed a re-authentication.

Example

policies:
  authorization:
    - name: policyA
      host: www.test.com
      paths:
        - /test*
      methods:
        - GET
        - POST
      rule: (any groupIds = "administrator")
      action: permit

    - name: policyB
      host: www.example.com
      paths:
        - /example*
      methods:
        - DELETE
      rule: anyuser
      action: obligate
      obligation:
        oidc:
          acr_values: "administrator mfa"
          prompt: login

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

    - name: mfa_required_obligate
      rule: 'acr != "urn:ibm:security:policy:id:2"'
      paths:
        - "/sensitive"
      action: "obligate"
      obligation:
        oidc:
          acr_values: "urn:ibm:security:policy:id:2"
          prompt: "login"

    - name: eula_not_accepted
      rule: 'eula != "true"'
      paths:
        - "/application/*"
      action: "obligate"
      obligation:
        redirect_url: "/eula/landing?origin=%URL%&user=%CREDATTR{preferred_username}%&proxy=%HTTPHDR{x-ibm-proxy}%"

    - name: reauth_required
      rule: anyauth
      paths:
        - "/application/download/*"
      action: "reauth"
      obligation:
        oidc:
          max_age: 0