Configuring Policies

Resource types define a template for the resources that policies apply to, and the actions that could be performed on those resources.

Authorization policies let AM determine whether to grant a subject access to a resource.

A policy defines the following:

resources

The resource definitions constrain constrain specific resources, such as web pages, or access to the boarding area the policy applies to.

actions

The actions are verbs that describe what the policy lets users do to the resources, such as read a web page, submit a web form, or access the boarding area.

subject conditions

The subject conditions constrain whom the policy applies to. Examples are: all authenticated users, only administrators, or only passengers with valid tickets for planes leaving soon.

Note that a subject condition that applies to all authenticated users includes the anonymous user.

environment conditions

The environment conditions set the circumstances under which the policy applies, such as only during work hours, only when accessing from a specific IP address, or only when the flight is scheduled to leave within the next four hours.

response attributes

The response attributes define information that AM attaches to a response following a policy decision, such as a name, email address, or frequent flyer status.

To help with the creation of policies, AM uses resource types and policy sets:

  • Resource types define a template for the resources that policies apply to, and the actions that could be performed on those resources.

    See Configuring Resource Types.

  • Policy sets are associated with a set of resource types, and contain one or more policies based upon the template it provides.

    See Configuring Policy Sets.

You can manage policies using the AM console or the REST API:

To Configure a Policy (UI)
  1. In the AM console, go to Realms > Realm Name > Authorization > Policy Sets, and then select the name of the policy set in which to configure a policy:

  2. To create a new policy, select Add a Policy.

  3. In the Name field, enter a descriptive name for the policy.

    Note

    Do not use special characters within resource type, policy, or policy set names (for example, "my+resource+type") when using the AM console or REST endpoints. Using the special characters listed below causes AM to return a 400 Bad Request error. The special characters are: double quotes ("), plus sign (+), comma (,), less than (<), equals (=), greater than (>), backslash (\), forward slash (/), semicolon (;), and null (\u0000).

  4. To define resources that the policy applies to, follow the steps below:

    1. Select a resource type from the Resource Type drop-down list. The set of resource patterns within the selected resource type will populate the Resources drop-down list. For information on configuring resource types, see Configuring Resource Types.

    2. Select a resource pattern from the Resources drop-down list.

    3. (Optional) Replace the asterisks with values to define the resources that the policy applies to. For information on specifying patterns for matching resources, see Specifying Resource Patterns with Wildcards.

      Editing Resource Patterns
      Edit the resource pattern if required.

      The OAuth2 Scope resource type has the same resource patterns as the URL resource type, and also the * pattern. Use the resource patterns that are most relevant for the scopes in your environment.

      Editing OAuth2 Scope Resource Type Resource Patterns
      Edit the resource pattern if required.

      Important

      Before testing your OAuth 2.0 policies, ensure your OAuth 2.0 service is configured to interact with AM's Authorization Service. Perform the following steps:

      1. Navigate to Realms > Realm Name > Services > OAuth2 Provider

      2. Ensure that Use Policy Engine for Scope decisions is enabled.

      For more information about testing OAuth 2.0 policies, see Dynamic OAuth 2.0 Authorization.

    4. Select Add to save the resource.

      The AM console displays a page for your new policy. The Tab pages let you modify the policy's properties.

    Tip

    To remove a resource, select Delete.

  5. Repeat these steps to add all the resources to which your policy applies, and then select Create.

  6. To configure the policy's actions, select the Actions tab and perform the following:

    1. Select an action that the policy applies to by selecting them from the Add an Action drop-down list.

    2. Select whether to allow or deny the action on the resources specified earlier.

      Allowing or Denying the Action for the Resource
      Select the actions and whether to allow or deny the action for the resources specified.

    3. Repeat these steps to add all the appropriate actions, and then select Save Changes.

  7. Define conditions in the AM console by combining logical operators with blocks of configured parameters to create a rule set that the policy uses to filter requests for resources. Use drag and drop to nest logical operators at multiple levels to create complex rule sets.

    Valid drop points in which to drop a block are displayed with a grey horizontal bar.

    Valid Drop Point
    Valid drop points to drop a block in are shown as a grey horizontal band.

    1. To define the subjects that the policy applies to, complete the following steps on the Subjects tab:

      1. Select Add a Subject Condition, choose the type from the drop-down menu, specify any required subject values, select the checkmark to the right when done, and then drag the block into a valid drop point in the rule set above.

        Nesting subject conditions
        Combine logical and subject conditions to create complex policies.

        Authenticated Users

        Any user that has successfully authenticated with AM.

        Users & Groups

        A user or group as defined in the realm containing the policy. To manage the identities and groups in a realm, go to Realms > Realm Name > Identities.

        Select one or more users or groups from the Identities or Groups tabs, which display the identities and groups available within the realm.

        To remove an entry, select the value, and then press Delete (Windows/GNU/Linux) or Backspace (Mac OS X).

        OpenID Connect/Jwt Claim

        Validate a claim within a JSON Web Token (JWT).

        Type the name of the claim to validate in the Claim Name field, for example, sub, and the required value in the Claim Value field, and then select the checkmark.

        Repeat the step to enter additional claims.

        The claim(s) will be part of the JWT payload together with the JWT header and signature. The JWT is sent in the authorization header of the bearer token.

        This condition type only supports string equality comparisons, and is case-sensitive.

        Never Match

        Never match any subject. Has the effect of disabling the policy, as it will never match a subject.

        If you do not set a subject condition, "Never Match" is the default. In other words, you must set a subject condition for the policy to apply.

        To match regardless of the subject, configure a subject condition that is "Never Match" inside a logical Not block.

      2. To add a logical operator, select the Add a Logical Operator button, choose between All Of, Not, and Any Of from the drop-down list, and then drag the block into a valid drop point in the rule set above.

      3. Continue combining logical operators and subject conditions. To edit an item, select the Edit button. To remove an item, select the Delete button. When complete, select Save Changes.

    2. To configure environment conditions in the policy, complete the following steps on the Environments tab:

      1. To add an environment condition, select the Environment Condition button, choose the type from the drop-down list, specify any required parameters, and then drag the block into a drop point in a logical block above.

        Note

        Script is the only environmental condition available for OAuth 2.0 policies.

        Active Session Time

        Make the policy test how long the user's session has been active, as specified in Max Session Time. To terminate the session if it has been active for longer than the specified time, set Terminate Sessions to True. The user will need to reauthenticate.

        Authentication by Module Chain

        Make the policy test the service that was used to authenticate the user.

        Authentication by Module Instance

        Make the policy test the authentication module used to authenticate, specified in Authentication Scheme. Specify a timeout for application authentication in Application Idle Timeout Scheme, and the name of the application in Application Name.

        Authentication Level (greater than or equal to)

        Make the policy test the minimum acceptable authentication level specified in Authentication Level.

        Authentication Level (less than or equal to)

        Make the policy test the maximum acceptable authentication level specified in Authentication Level.

        Authentication to a Realm

        Make the policy test the realm to which the user authenticated.

        A session can only belong to one realm, and session upgrade between realms is not allowed.

        Current Session Properties

        Make the policy test property values set in the user's session.

        Set Ignore Value Case to True to make the test case-insensitive.

        Specify one or more pairs of session properties and values using the format property:value. For example, specify clientType:genericHTML to test whether the value of the clientType property is equal togenericHTML.

        Identity Membership

        Make the policy apply if the UUID of the invocator is a member of at least one of the AMIdentity objects specified in AM Identity Name.

        Often used to filter requests on the identity of a Web Service Client (WSC).

        Note

        Java Agents and Web Agents do not support the Identity Membership environment condition. Instead, use the equivalent Users & Groups subject condition.

        IPv4 Address/DNS Name

        Make the policy test the IP version 4 address that the request originated from.

        The IP address is taken from the requestIp value of policy decision requests. If this is not provided, the IP address stored in the SSO token is used instead.

        Specify a range of addresses to test against by entering four sets of up to three digits, separated by periods (.) in both Start IP and End IP.

        If only one of these values is provided, it is used as a single IP address to match.

        Optionally, specify a DNS name in DNS Name to filter requests to that domain.

        IPv6 Address/DNS Name

        Make the policy test the IP version 6 address that the request originated from.

        The IP address is taken from the requestIp value of policy decision requests. If this is not provided, the IP address stored in the SSO token is used instead.

        Specify a range of addresses to test against by entering eight sets of four hexadecimal characters, separated by a colon (:) in both Start IP and End IP.

        If only one of these values is provided, it is used as a single IP address to match.

        Optionally, specify a DNS name in DNS Name to filter requests to those coming from the specified domain.

        Use an asterisk (*) in the DNS name to match multiple subdomains. For example, *.example.com applies to requests coming from www.example.com, secure.example.com, or any other subdomain of example.com.

        LDAP Filter Condition

        Make the policy test whether the user's entry can be found using the LDAP search filter you specify in the directory configured for the policy service, which by default is the identity repository. Navigate to Configure > Global Services, and then select Policy Configuration to see the global LDAP configuration.

        Alternatively, to configure these settings for a realm, navigate to Realms > Realm Name > Services, and then select Policy Configuration.

        OAuth2 Scope

        Make the policy test whether an authorization request includes all of the specified OAuth 2.0 scopes.

        Scope names must follow OAuth 2.0 scope syntax described in RFC 6749, Access Token Scope . As described in that section, separate multiple scope strings with spaces, such as openid profile.

        The scope strings match regardless of order in which they occur, so openid profile is equivalent to profile openid.

        The condition is also met when additional scope strings are provided beyond those required to match the specified list. For example, if the condition specifies openid profile, then openid profile email also matches.

        Resource/Environment/IP Address

        Make the policy apply to a complex condition, such as whether the user is making a request from the localhost, and has also authenticated with the LDAP authentication module.

        Entries must take the form of an IF...ELSE statement. The IF statement can specify either IP to match the user's IP address, or dnsName to match their DNS name.

        If the IF statement is true, the THEN statement must also be true for the condition to be fulfilled. If not, relevant advice is returned in the policy evaluation request.

        The available parameters for the THEN statement are as follows:

        module

        The module used to authenticate the user. For example, DataStore.

        service

        The service that was used to authenticate the user.

        authlevel

        The minimum required authentication level.

        role

        The role of the authenticated user.

        user

        The name of the authenticated user.

        redirectURL

        The URL the user was redirected from.

        realm

        The realm that was used to authenticate the user.

        The IP address can be IPv4, IPv6, or a hybrid of the two.

        Example: IF IP=[127.0.0.1] THEN role=admins.

        Script

        Make the policy depend on the outcome of a JavaScript or Groovy script executed at the time of the policy evaluation.

        For information on scripting policy conditions, see Scripting a Policy Condition.

        Script is the only environmental condition available for OAuth 2.0 policies. Use scripts to capture the ClientId environmental attribute.

        Time (day, date, time, and timezone)

        Make the policy test when the policy is evaluated.

        The values for day, date and time must be set in pairs that comprise a start and an end.

        Create conditions that apply between a start and end date and time.
        Create conditions that apply between a start and end date and time.

        Transaction

        Make the policy depend on the successful completion of a transaction performed by the user.

        Configure a transaction with an authentication strategy that asks the user to reauthenticate before being allowed access to the resource.

        Transactions support the following authentication strategies:

        • Authenticate to Chain: Specify the name of an authentication chain the user must successfully complete to access the protected resource.

        • Authenticate to Realm: Specify the full path of a realm in which the user must successfully authenticate to access the protected resource.

          For example, /sales/internal.

        • Authenticate to Tree: Specify the name of an authentication tree the user must successfully traverse to access the protected resource.

        • Authenticate to Module: Specify the name of an authentication module the user must successfully authenticate against to access the protected resource.

        • Auth Level: Specify the minimum authentication level the user must achieve to access the protected resource.

          Note

          If you specify a minimum, you must ensure there are methods available to users to reach that level. If none are found, the policy will return a 400 Bad request error when attempting to complete the transaction.

        For more information on transactional authorization, see Transactional Authorization.

      2. To add a logical operator, select the Logical button, choose between All Of, Not, and Any Of from the drop-down list, and then drag the block into a valid drop point in the rule set above.

      3. Continue combining logical operators and environment conditions, and when finished, select Save Changes.

  8. (Optional) You can add response attributes, retrieved from the user entry in the identity repository, into the headers of the request at policy decision time (not available for the OAuth2 Scope resource type). The web or Java agent for the protected resources/applications or the protected resources/applications themselves retrieve the policy response attributes to customize or personalize the application. Policy response attributes come in two formats: subject attributes and static attributes.

    To configure response attributes in the policy, complete the following steps on the Response attributes tab:

    1. To add subject attributes, select them from the Subject attributes drop-down list.

      To remove an entry, select the value, and then press Delete (Windows/GNU/Linux) or Backspace (Mac OS X)

    2. To add a static attribute, specify the key-value pair for each static attribute. Enter the Property Name and its corresponding Property Value in the fields, and then select the Add (+) icon.

      Note

      To edit an entry, select the Edit icon in the row containing the attribute, or select the row itself. To remove an entry, select the Delete icon in the row containing the attribute.

    3. Continue adding subject and static attributes, and when finished, select Save Changes.

Read a different version of :