PingAM 7.5.0

Policies in the UI

A policy can only be created as part of a policy set.

You manage policies through the AM admin UI. Go to Realms > Realm Name > Authorization > Policy Sets and select the name of the policy set in which to configure a policy.

To…​ Action

Create a policy

Click Add a Policy.

When creating a policy, specify a name, a resource type, and at least one resource.

Click Create.

Modify a policy

Click the policy name or the pencil icon ().

Delete a policy

Click the delete icon () or click the policy name then x Delete.

Policy type names

Do not use any of the following characters in policy, policy set, or resource type names:

Double quotes (")
Plus sign (+)
Comma (,)
Less than (<)
Equals (=)
Greater than (>)
Backslash (\)
Forward slash (/)
Semicolon (;)
Null (\u0000)

Resources

To define resources that the policy applies to:

  1. Click the Resources pencil icon () or the Resources tab.

  2. Select a resource type from the Resource Type drop-down list.

    The resource type determines which resource patterns are available. The OAuth2 Scope resource type contains the same resource patterns as the URL resource type, as well as the * pattern.

    Use the resource patterns that are most relevant for the scopes in your environment.

    For information on configuring resource types, refer to Resource types.

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

  4. Replace the asterisks with values for matching resources, and click Add.

    For information on configuring resource patterns, refer to Resource type patterns.

  5. Optionally, click Add Resource to add further resource patterns, or click () to delete a resource pattern.

  6. Save your changes.

Policy actions

To define policy actions that allow or deny access to a resource:

  1. Click the Actions pencil icon () or the Actions tab.

  2. Click Add an Action to select an action from the drop-down list.

  3. Select whether to allow or deny the action on the resources.

  4. Optionally, add further actions, or click () to delete actions.

  5. Save your changes.

Conditions

To define subject and environment conditions:

  • Combine logical operators with blocks of configured parameters to create a rule set. The policy uses this rule set to filter requests for resources.

  • Use drag and drop to nest logical operators at multiple levels to create complex rule sets.

Nested subject conditions

  • A gray horizontal bar indicates a valid point to drop a block.

    Drop blocks into drop points, which are shown as a gray horizontal band.

Subjects

To define the subject conditions the policy applies to:

  1. Click Add a Subject Condition, choose the type from the drop-down menu, and provide any required subject values.

  2. When complete, click the check icon () and drag the block into a valid drop point in the rule set.

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

  4. To edit a condition, click the edit icon (), or click () to delete.

  5. Continue combining logical operators and subject conditions and click Save Changes when you’ve finished.

Subject condition types Description

Authenticated Users

Any user that has successfully authenticated with AM.

Users & Groups

Search for and select one or more users or groups that are defined in AM admin UI under the Realms > Realm Name > Identities or the Groups tab.

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 click the check icon ().

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. This disables the policy.

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 Never Match subject condition inside a logical Not block.

Environments

To define the environment conditions the policy applies to:

  1. Click Add an Environment Condition, choose the type from the drop-down menu, and provide any required subject values.

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

  2. When complete, click the check icon () button and drag the block into a valid drop point in the rule set.

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

  4. To edit a condition, click the edit icon (), or click () to delete.

  5. Continue combining logical operators and subject conditions and click Save Changes when you’ve finished.

Environment condition types Description

Active Session Time

Set a condition for the maximum duration the user’s session has been active. To end the session if it has been active for longer than Max Session 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)

The minimum acceptable authentication level required by the policy.

Authentication Level (less than or equal to)

The maximum acceptable authentication level required by the policy.

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

Evaluate 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, use clientType:genericHTML to test whether the value of the clientType property is equal to genericHTML.

Identity Membership

Make the policy apply if the user’s UUID is a member of at least one of the AMIdentity objects specified in AM Identity Name. For example, use this type to filter requests on the identity of a Web Service Client (WSC).

Java agents and web agents do not support the Identity Membership environment condition. Instead, use the Users & Groups subject condition.

IPv4 Address/DNS Name

The IP version 4 address from which the request originated.

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

The IP version 6 address from which the request originated.

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 from the specified domain.

Use an asterisk (*) in the DNS name to match multiple subdomains. For example, *.example.com applies to requests 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.

If you define a filter condition that uses LDAP accounts or groups in a different identity repository, you must configure the LDAP settings under Realms > Realm Name > Services > Policy Configuration.

OAuth2 Scope

Set a condition that an authorization request includes all the specified OAuth 2.0 scopes.

Scope names must follow OAuth 2.0 scope syntax described in RFC 6749, Access Token Scope. 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

Define a complex condition, such as whether the user is making a request from the localhost, and has also authenticated in a particular way.

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 executed at the time of the policy evaluation.

For information on scripting policy conditions, refer to Scripted policy conditions.

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.

Day, date and time conditions in policies must consist of a start and an end value.

Transaction

Make the policy depend on the successful completion of transactional authorization.

Transactional authorization requires the user to authenticate for each access to the resource.

Transactions support the following authentication strategies:

  • Authenticate to Chain: The authentication chain the user must successfully complete to access the protected resource.

  • Authenticate to Realm: The full path of a realm in which the user must successfully authenticate to access the protected resource. For example, /alpha.

  • Authenticate to Tree: The authentication journey the user must successfully traverse to access the protected resource.

  • Authenticate to Module: The authentication module the user must successfully authenticate against to access the protected resource.

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

If you specify a minimum, you must ensure there are methods available to users to reach that level.

If none are found, the policy returns a 400 Bad request error when attempting to complete the transaction.

Response attributes

Add user attributes from the identity repository as response attributes—either as subject attribute or static attributes—to the request header at policy decision time.

Note that response attributes are 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 the application.

To define response attributes in the policy:

  1. Click the Response Attributes edit icon () or the Response Attributes tab.

  2. 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).

  3. 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 click Add (+).

    To edit a static attribute, click the edit icon (), or click () to delete.

  4. Continue adding subject and static attributes, and when finished, click Save Changes.

Example

This example policy requires authenticated users to have a session no longer than 30 minutes to access resources at https://www.example.com:*/*.

Example policy

Before testing your OAuth 2.0 policies, ensure your OAuth 2.0 provider is configured to interact with AM’s authorization service:

  1. In the AM admin UI, go to Realms > Realm Name > Services > OAuth2 Provider.

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

For more information about testing OAuth 2.0 policies, refer to Dynamic OAuth 2.0 authorization.