Authorization
This guide covers concepts, implementation procedures, and customization techniques for working with the authorization features of ForgeRock Access Management.
Authorization
Learn how AM determines access according to policies.
Create policies
Define resources, and protect them by creating authorization policies.
What is transactional authorization?
Use transactional authorization to require additional authorization.
Dynamic OAuth 2.0 scopes
Learn how to grant OAuth 2.0 scopes dynamically.
ForgeRock® Identity Platform serves as the basis for our simple and comprehensive Identity and Access Management solution. We help our customers deepen their relationships with their customers, and improve the productivity and connectivity of their employees and partners. For more information about ForgeRock and about the platform, see https://www.forgerock.com.
Authorization and policy decisions
AM provides access management, which consists of:
-
Authentication: determining who is trying to access a resource
-
Authorization: determining whether to grant or deny access to the resource
The decision to grant access depends on a number of factors:
-
the policies governing access
-
who is trying to gain access
-
possible additional conditions, such as whether the access needs to happen over a secure channel or what time of day it is.
AM relies on policies to reach authorization decisions, such as whether to grant or deny access to a resource, or to grant or deny OAuth 2.0 scopes.
Related Information: Dynamic OAuth 2.0 authorization
Protect resources
When you configure policy sets to protect resources, AM acts as the policy decision point (PDP), whereas AM web and Java agents act as policy enforcement points (PEP). In other words, an agent or other PEP takes responsibility only for enforcing a policy decision rendered by AM. When you configured applications and their policies in AM, you used AM as a policy administration point (PAP).
Concretely speaking, when a PEP requests a policy decision from AM, it specifies the target resource(s),
the policy set (default: iPlanetAMWebAgentService), and information about the subject and the environment.
AM as the PDP retrieves policies within the specified policy set that apply to the target resource(s).
AM then evaluates those policies to make a decision
based on the conditions matching those of the subject and environment.
When multiple policies apply for a particular resource,
the default logic for combining decisions is that the first evaluation resulting in a decision to deny access
takes precedence over all other evaluations.
AM only allows access if all applicable policies evaluate to a decision to allow access.
AM communicates the policy decision to the PEP. The concrete decision, applying policy for a subject under the specified conditions, is called an entitlement.
The entitlement indicates the resource(s) it applies to, the actions permitted and denied for each resource, and optionally, response attributes and advice.
When AM denies a request due to a failed condition, AM can send advice to the PEP, and the PEP can then take remedial action. For instance, suppose a user comes to a website after authenticating with an email address and password, which is configured as authentication level 0. Had the user authenticated using a one-time password, the user would have had authentication level 1 in their session. Yet, because they have authentication level 0, they currently cannot access the desired page, as the policy governing access requires authentication level 1. AM sends advice, prompting the PEP to have the user re-authenticate using a one-time password, gaining authentication level 1, and thus having AM grant access to the protected page.
Policy decisions
AM has to match policies to resources to take policy decisions. For a policy to match, the resource has to match one of the resource patterns defined in the policy. The user making the request has to match a subject. Furthermore, at least one condition for each condition type has to be satisfied.
If more than one policy matches, AM has to reconcile differences. When multiple policies match, the order in which AM uses them to make a policy decision is not deterministic. However, a deny decision overrides an allow decision and so, by default, once AM reaches a deny decision, it stops checking further policies.
Example
Consider the case where AM protects a user profile web page. An AM web agent installed in the web server intercepts client requests to enforce policy. The policy says that only authenticated users can access the page to view and to update their profiles.
When a user browses to the profile page, the AM agent intercepts the request. The web agent notices that the request is to access a protected resource, but the request is coming from a user who has not yet logged in and consequently has no authorization to visit the page. The web agent therefore redirects the user’s browser to AM to authenticate.
AM receives the redirected user, serving a login page that collects the user’s email and password. With the email and password credentials, AM authenticates the user, and creates a session for the user. AM then redirects the user to the web agent, which gets the policy decision from AM for the page to access, and grants access to the page.
While the user has a valid session with AM, the user can go away to another page in the browser, come back to the profile page, and gain access without having to enter their email and password again.
Notice how AM and the web agent handle the access in the example. The website developer can offer a profile page, but the website developer never has to manage login, or handle who can access a page. As AM administrator, you can change authentication and authorization independently of updates to the website. You might need to agree with website developers on how AM identifies users, so web developers can identify users by their own names when they log in. By using AM and web or Java agents for authentication and authorization, your organization no longer needs to update web applications when you want to add external access to your Intranet for roaming users, open some of your sites to partners, only let managers access certain pages of your HR website, or allow users already logged in to their desktops to visit protected sites without having to type their credentials again.
Policies
Authorization policies let AM determine whether to grant a subject access to a resource.
A policy defines the following:
- resources
-
The resource to which access is restricted, such as a web page, a mobile app, or a boarding area in an airport.
- actions
-
The verbs that describe what users can do to the resource, such as read a web page, submit a web form, or access a boarding area.
- subject conditions
-
Who the policy applies to, such as all authenticated users, only administrators, or only passengers with valid tickets for planes leaving soon.
- environment conditions
-
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
-
Information that AM attaches to a response following a policy decision, such as a name, email address, or frequent flyer status.
Policies in the UI
-
In 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 create a new policy, select Add a Policy.
-
In the Name field, enter a descriptive name for the policy.
Do not use special characters in resource type, policy, or policy set names (for example,
"my+resource+type"). If you include special characters, AM returns a 400 Bad Request error. This includes the following special characters: double quotes ("), plus sign (+), comma (,), less than (<), equals (=), greater than (>), backslash (\), forward slash (/), semicolon (;), and null (\u0000). -
To define resources that the policy applies to, follow the steps below:
-
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 Resource types.
-
Select a resource pattern from the Resources drop-down list.
-
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.
Figure 2. Editing Resource PatternsThe
OAuth2 Scoperesource type has the same resource patterns as theURLresource type, and also the*pattern. Use the resource patterns that are most relevant for the scopes in your environment.
Figure 3. Editing OAuth2 Scope Resource Type Resource PatternsBefore 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:
-
Go to Realms > Realm Name > Services > OAuth2 Provider.
-
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.
-
-
Select Add to save the resource.
The AM admin UI displays a page for your new policy. The tab pages let you modify the policy’s properties.
To remove a resource, select Delete.
-
-
Repeat these steps to add all the resources to which your policy applies, and then select Create.
-
To configure the policy’s actions, select the Actions tab and perform the following:
-
Select an action that the policy applies to by selecting them from the Add an Action drop-down list.
-
Select whether to allow or deny the action on the resources specified earlier.
Figure 4. Allowing or Denying the Action for the Resource -
Repeat these steps to add all the appropriate actions, and then select Save Changes.
-
-
Define conditions in the AM admin UI 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.
Figure 5. Valid Drop Point-
To define the subjects that the policy applies to, complete the following steps on the Subjects tab:
-
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.
Figure 6. Nesting subject conditionsSubject condition types
- 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 kbd:[Delete] (Windows/GNU/Linux) or kbd:[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
Notblock.
-
To add a logical operator, select the Add a Logical Operator button, choose between
All Of,Not, andAny Offrom the drop-down list, and then drag the block into a valid drop point in the rule set above. -
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.
-
-
To configure environment conditions in the policy, complete the following steps on the Environments tab:
-
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.
Scriptis the only environmental condition available for OAuth 2.0 policies.Environment condition types
- 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, setTerminate SessionstoTrue. 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
Trueto make the test case-insensitive.Specify one or more pairs of session properties and values using the format
property:value. For example, specifyclientType:genericHTMLto test whether the value of theclientTypeproperty 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).
Java agents and web agents do not support the
Identity Membershipenvironment condition. Instead, use the equivalentUsers & Groupssubject 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
requestIpvalue 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 (kbd:[.]) 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
requestIpvalue 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 (kbd:[:]) 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 (kbd:[*]) in the DNS name to match multiple subdomains. For example,
*.example.comapplies to requests coming fromwww.example.com,secure.example.com, or any other subdomain ofexample.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. By default, this is the identity repository defined during setup.
If you define a filter condition that uses LDAP accounts or groups in a different identity repository, you must configure the LDAP settings:
-
Go to Realms > Realm Name > Services.
-
Select Policy Configuration to view and edit the LDAP 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 profileis equivalent toprofile 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, thenopenid profile emailalso 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 in a particular way.
Entries must take the form of an
IF…ELSEstatement. TheIFstatement can specify eitherIPto match the user’s IP address, ordnsNameto match their DNS name.If the
IFstatement is true, theTHENstatement 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
THENstatement are as follows:moduleThe module used to authenticate the user. For example,
DataStore.serviceThe service that was used to authenticate the user.
authlevelThe minimum required authentication level.
roleThe role of the authenticated user.
userThe name of the authenticated user.
redirectURLThe URL the user was redirected from.
realmThe 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 Scripted policy conditions.
Scriptis the only environmental condition available for OAuth 2.0 policies. Use scripts to capture theClientIdenvironmental 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.
Figure 7. Create conditions that apply between a start and end date andtime. - 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.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 requesterror when attempting to complete the transaction.
-
For more information on transactional authorization, see Transactional authorization.
-
To add a logical operator, select the Logical button, choose between
All Of,Not, andAny Offrom the drop-down list, and drag the block into a valid drop point in the rule set above. -
Continue combining logical operators and environment conditions, and when finished, click Save Changes.
-
-
-
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 Scoperesource 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:
-
To add subject attributes, select them from the Subject attributes drop-down list.
To remove an entry, select the value, and click Delete (Windows/GNU/Linux) or kbd:[Backspace] (Mac OS X).
-
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 select the Add (kbd:[+]) icon.
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.
-
Continue adding subject and static attributes, and when finished, click Save Changes.
-
Policies over REST
Policies are realm-specific, so the URI for the policies API can contain a realm component,
such as /json/realm/policies.
Policy resources are built from standard JSON objects and values (strings, numbers, objects, arrays, true, false,
and null).
Example
{
"name": "mypolicy",
"active": true,
"description": "My Policy.",
"applicationName": "iPlanetAMWebAgentService",
"actionValues": {
"POST": true,
"GET": true
},
"resources": [
"http://www.example.com:80/*",
"http://www.example.com:80/*?*"
],
"subject": {
"type": "AuthenticatedUsers"
},
"condition": {
"type": "SimpleTime",
"startTime": "09:00",
"endTime": "17:00",
"startDay": "mon",
"endDay": "fri",
"enforcementTimeZone": "GMT"
},
"resourceTypeUuid": "76656a38-5f8e-401b-83aa-4ccb74ce88d2",
"resourceAttributes": [
{
"type": "User",
"propertyName": "givenName",
"propertyValues": [ ]
}
],
"lastModifiedBy": "id=amadmin,ou=user,dc=openam,dc=forgerock,dc=org",
"lastModifiedDate": "2015-05-11T17:39:09.393Z",
"createdBy": "id=amadmin,ou=user,dc=openam,dc=forgerock,dc=org",
"creationDate": "2015-05-11T17:37:24.556Z"
}The values for the fields shown in the example are explained below:
name-
String matching the name in the URL (when creating the policy using HTTP PUT) or in the body (when creating the policy using HTTP POST).
active-
Boolean indicating whether AM considers the policy active for evaluation purposes, defaults to
false. description-
String describing the policy.
resources-
List of the resource name pattern strings to which the policy applies. Must conform to the pattern templates provided by the associated resource type.
applicationName-
String containing the policy set name, such as
"iPlanetAMWebAgentService", or"mypolicyset". actionValues-
Set of string action names, each set to a boolean indicating whether the action is allowed. Chosen from the available actions provided by the associated resource type.
Action values can also be expressed as numeric values. When using numeric values, use the value
0forfalseand use any non-zero numeric value fortrue. subject-
Specifies the subject conditions to which the policy applies, where subjects can be combined by using the built-in types
"AND","OR", and"NOT", and where subject implementations are pluggable.Subjects are shown as JSON objects with
typeset to the name of the implementation (using a short name for all registered subject implementations), and other fields, depending on the implementation. The subject types registered by default include the following:-
"AuthenticatedUsers", meaning any user that has successfully authenticated to AM.{ "type": "AuthenticatedUsers" }The
AuthenticatedUserssubject condition does not take into account the realm to which a user authenticated. Any user that has authenticated successfully to any realm passes this subject condition.To test whether a user has authenticated successfully to a specific realm, add the
AuthenticateToRealmenvironment condition. -
"Identity"to specify one or more users from an AM identity repository:{ "type": "Identity", "subjectValues": [ "uid=scarter,ou=People,dc=example,dc=com", "uid=ahall,ou=People,dc=example,dc=com" ] }You can also use the
"Identity"subject type to specify one or more groups from an identity repository:{ "type": "Identity", "subjectValues": [ "cn=HR Managers,ou=Groups,dc=example,dc=com" ] } -
"JwtClaim"to specify a claim in a user’s JSON web token (JWT).{ "type": "JwtClaim", "claimName": "sub", "claimValue": "scarter" } -
"NONE", meaning never match any subject. The result is not that access is denied, but rather that the policy itself does not match and therefore cannot be evaluated in order to allow access.
The following example defines the subject either as the user Sam Carter from an AM identity repository, or as a user with a JWT claim with a subject claim with the value
scarter: -
{
"subject": {
"type": "OR",
"subjects": [{
"type": "Identity",
"subjectValues": [
"uid=scarter,ou=People,dc=example,dc=com"
]
},
{
"type": "JwtClaim",
"claimName": "sub",
"claimValue": "scarter"
}
]
}
}To read a single subject type description, or to list all the available subject types, see Manage subject condition types.
condition-
Conditions are shown as JSON objects with
"type"set to the name of the implementation (using a short name for all registered condition implementations), and other fields depending on the implementation. The condition types registered by default include the following.-
"AMIdentityMembership"to specify a list of AM users and groups.{ "type": "AMIdentityMembership", "amIdentityName": [ "id=scarter,ou=People,dc=example,dc=com" ] }Java Agents and Web Agents do not support the
AMIdentityMembershipenvironment condition. Instead, use the equivalentIdentitysubject condition. -
"AuthLevel"to specify the authentication level.{ "type": "AuthLevel", "authLevel": 2 } -
"AuthScheme"to specify the authentication module used to authenticate, the policy set name, and a timeout for authentication.{ "type": "AuthScheme", "authScheme": [ "DataStore" ], "applicationName": "iPlanetAMWebAgentService", "applicationIdleTimeout": 10 } -
"AuthenticateToRealm"to specify the realm to which the user authenticated.{ "type": "AuthenticateToRealm", "authenticateToRealm": "MyRealm" } -
"AuthenticateToService"to specify the authentication tree or chain that was used to authenticate.{ "type": "AuthenticateToService", "authenticateToService": "MyAuthnTree" } -
"IPv4"or"IPv6"to specify an IP address range from which the request originated.{ "type": "IPv4", "startIp": "127.0.0.1", "endIp": "127.0.0.255" }You can also use the
"IPv4"and"IPv6"conditions with the"dnsName"field to specify domain names from which the request originated. Omit"startIp"and"endIp"when using"dnsName".{ "type": "IPv4", "dnsName": [ "*.example.com" ] } -
"LDAPFilter"to specify an LDAP search filter. The user’s entry is tested against the search filter in the directory configured in the Policy Configuration Service.{ "type": "LDAPFilter", "ldapFilter": "(&(c=US)(preferredLanguage=en-us))" } -
"LEAuthLevel"to specify a maximum acceptable authentication level.{ "type": "LEAuthLevel", "authLevel": 2 } -
"OAuth2Scope"to specify a list of attributes that must be present in the user profile.{ "type": "OAuth2Scope", "requiredScopes": [ "name", "address", "email" ] } -
"ResourceEnvIP"to specify a complex condition such as whether the user is making a request from a given host and has authenticated with a given authentication level. For example:{ "type": "ResourceEnvIP", "resourceEnvIPConditionValue": [ "IF IP=[127.168.10.*] THEN authlevel=4" ] }Entries must take the form of one or more IF…ELSE statements. If the IF statement is true, the THEN statement must also be true for the condition to be fulfilled. The IF statement can specify an IP to match the user’s IP address, or a dnsName to match their DNS name. The IP address can be IPv4 or IPv6 format, or a hybrid of the two, and can include wildcard characters.
The available parameters for the THEN statement are as follows:
serviceThe service that was used to authenticate the user.
authlevelThe minimum required authentication level.
roleThe role of the authenticated user.
userThe name of the authenticated user.
redirectURLThe URL the user was redirected from.
realmThe realm that was used to authenticate the user.
-
"Session"to specify how long the user’s session has been active, and to terminate the session if it is too old, forcing the user to reauthenticate.{ "type": "Session", "maxSessionTime": "10", "terminateSession": false } -
"SessionProperty"to specify attributes set in the user’s session.{ "type": "SessionProperty", "ignoreValueCase": true, "properties": { "CharSet": [ "UTF-8" ], "clientType": [ "genericHTML" ] } } -
"SimpleTime"to specify a time range, where"type"is the only required field.{ "type": "SimpleTime", "startTime": "07:00", "endTime": "19:00", "startDay": "mon", "endDay": "fri", "startDate": "2015:01:01", "endDate": "2015:12:31", "enforcementTimeZone": "GMT+0:00" }The following example defines the condition as neither Saturday or Sunday, nor certain client IP addresses.
{ "type": "NOT", "condition": { "type": "OR", "conditions": [ { "type": "SimpleTime", "startDay": "sat", "endDay": "sun", "enforcementTimeZone": "GMT+8:00" }, { "type": "IPv4", "startIp": "192.168.0.1", "endIp": "192.168.0.255" } ] } }To read a single condition type description, or to list all the available condition types, see Manage environment condition types.
-
resourceTypeUuid-
The UUIDs of the resource type associated with the policy.
resourceAttributes-
List of attributes to return, with decisions. These attributes are known as response attributes, and do not apply to
OAuth2 Scoperesource types.The response attribute provider is pluggable. The default implementation provides for statically defined attributes and for attributes retrieved from user profiles.
Attributes are shown as JSON objects:
typeis set to the name of the implementation (by default"Static"for statically defined attributes or"User"for attributes from the user profile)propertyNameis set to the attribute names. For static attributes,"propertyValues"holds the attribute values. For user attributes,"propertyValues"is not used; the property values are determined at evaluation time. createdBy-
A string containing the universal identifier DN of the subject that created the policy.
creationDate-
An integer containing the creation date and time, in number of seconds since the Unix epoch (1970-01-01T00:00:00Z).
lastModifiedBy-
A string containing the universal identifier DN of the subject that most recently updated the policy.
If the policy has not been modified since it was created, this will be the same value as
createdBy. lastModifiedDate-
An integer containing the last modified date and time, in number of seconds since the Unix epoch (1970-01-01T00:00:00Z).
If the policy has not been modified since it was created, this will be the same value as
creationDate.
Before making a REST API call to request manage a policy component, make sure that you have:
-
Authenticated successfully to AM as a user with sufficient privileges to make the REST API call.
-
Obtained the session token returned after successful authentication.
When making a REST API call, specify the realm in the path component of the endpoint.
You must also pass the session token in the HTTP header. For more information about the AM session token and its use in REST API calls, see Using the session token after authentication.
Query policies
Use REST calls to list all the policies in a realm, or to find policies that explicitly apply to a given user or group.
List all policies in a realm
-
To list all the policies in a realm, perform an HTTP GET to the
/json/realms/root/realms/realm/policiesendpoint, with an_queryFilterparameter set totrue.The
<session-cookie-name>header is required and should contain the SSO token of an administrative user, such asamAdmin, who has access to perform the operation.$ curl \ --header "<session-cookie-name>: AQIC5w…" \ --header "Accept-API-Version: resource=1.0, protocol=2.1" \ "https://<tenant-name>.forgeblocks.com/am/json/realms/root/realms/myrealm/policies?_queryFilter=true" { "result":[ { "name":"example", "active":true, "description":"Example Policy", "applicationName":"iPlanetAMWebAgentService", "actionValues":{ "POST":false, "GET":true }, "resources":[ "http://www.example.com:80/", "http://www.example.com:80/?*" ], "subject":{ "type":"Identity", "subjectValues":[ "uid=demo,ou=People,dc=example,dc=com" ] }, "resourceTypeUuid":"12345a67-8f0b-123c-45de-6fab78cd01e4", "lastModifiedBy":"id=amadmin,ou=user,dc=openam,dc=forgerock,dc=org", "lastModifiedDate":"2015-05-11T14:48:08.711Z", "createdBy":"id=amadmin,ou=user,dc=openam,dc=forgerock,dc=org", "creationDate":"2015-05-11T14:48:08.711Z" } ], "resultCount":1, "pagedResultsCookie":null, "remainingPagedResults":0 }Additional query strings can be specified to alter the returned results. For more information, see Query.
Supported _queryFilter Fields and Operators
Field Supported Operators nameEquals (
eq)descriptionEquals (
eq)applicationNameEquals (
eq)createdByEquals (
eq)creationDate(1)Equals (
eq), Greater than or equal to (ge), Greater than (gt), Less than or equal to (le), Less than (lt)lastModifiedByEquals (
eq)lastModifiedDate(1)Equals (
eq), Greater than or equal to (ge), Greater than (gt), Less than or equal to (le), Less than (lt)(1) The implementation of
eqfor this date field does not use regular expression pattern matching.
Query policies in a realm by user or group
You can query policies that explicitly reference a given subject by providing the universal ID (UID) of either a user or group. AM returns any policies that explicitly apply to the user or group as part of a subject condition.
|
You can obtain the universal ID for a user or group by using REST. |
The following caveats apply to querying policies by user or group:
-
Group membership is not considered. For example, querying policies for a specific user will not return policies that only use groups in their subject conditions, even if the user is a member of any of those groups.
-
Wildcards are not supported, only exact matches.
-
Only policies with a subject condition type of
Identityare queried—environment conditions are not queried. TheIdentitysubject condition type is labelled as Users & Groups in the policy editor in the AM admin UI. -
Policies with subject conditions that only contain the user or group in a logical NOT operator are not returned.
To query policies by user or group:
-
Perform an HTTP GET to the
/json/realms/root/realms/realm/policiesendpoint, with an_queryIdparameter set toqueryByIdentityUid, and auidparameter containing the universal ID of the user or group:$ curl \ --get \ --header "<session-cookie-name>: AQIC5w…" \ --header "Accept-API-Version: resource=1.0" \ --data "_queryId=queryByIdentityUid" \ --data "uid=id=demo,ou=user,o=myrealm,ou=services,dc=openam,dc=forgerock,dc=org" \ "https://<tenant-name>.forgeblocks.com/am/json/realms/root/realms/myrealm/policies" { "result":[ { "name":"mySubRealmPolicy", "active":true, "description":"", "resources":[ "://:*/?", "://:*/*" ], "applicationName":"iPlanetAMWebAgentService", "actionValues":{ "POST":true, "PATCH":true, "GET":true, "DELETE":true, "OPTIONS":true, "PUT":true, "HEAD":true }, "subject":{ "type":"Identity", "subjectValues":[ "id=demo,ou=user,o=myrealm,ou=services,dc=openam,dc=forgerock,dc=org" ] }, "resourceTypeUuid":"76656a38-5f8e-401b-83aa-4ccb74ce88d2", "lastModifiedBy":"id=amAdmin,ou=user,dc=openam,dc=forgerock,dc=org", "lastModifiedDate":"2016-05-05T08:45:35.716Z", "createdBy":"id=amadmin,ou=user,dc=openam,dc=forgerock,dc=org", "creationDate":"2016-05-03T13:45:38.137Z" } ], "resultCount":1, "pagedResultsCookie":null, "totalPagedResultsPolicy":"NONE", "totalPagedResults":-1, "remainingPagedResults":0 }The
<session-cookie-name>header is required and should contain the SSO token of an administrative user, such asamAdmin, who has access to perform the operation.
Read a specific policy
To read an individual policy in a realm, perform an HTTP GET to the /json/realms/root/realms/realm/policies endpoint,
and specify the policy name in the URL.
The <session-cookie-name> header is required and should contain the SSO token of an administrative user,
such as amAdmin, who has access to perform the operation.
$ curl \
--header "<session-cookie-name>: AQIC5…" \
"https://<tenant-name>.forgeblocks.com/am/json/realms/root/policies/example"
{
"result": [
{
"name": "example",
"active": true,
"description": "Example Policy",
"applicationName": "iPlanetAMWebAgentService",
"actionValues": {
"POST": false,
"GET": true
},
"resources": [
"http://www.example.com:80/",
"http://www.example.com:80/?*"
],
"subject": {
"type": "Identity",
"subjectValues": [
"uid=demo,ou=People,dc=example,dc=com"
]
},
"resourceTypeUuid": "12345a67-8f0b-123c-45de-6fab78cd01e4",
"lastModifiedBy": "id=amadmin,ou=user,dc=openam,dc=forgerock,dc=org",
"lastModifiedDate": "2015-05-11T14:48:08.711Z",
"createdBy": "id=amadmin,ou=user,dc=openam,dc=forgerock,dc=org",
"creationDate": "2015-05-11T14:48:08.711Z"
}
],
"resultCount": 1,
"pagedResultsCookie": null,
"remainingPagedResults": 0
}You can use the query string parameters _prettyPrint=true to make the output easier to read,
and _fields=field-name[,field-name…] to limit the fields returned in the output.
Create policies
To create a policy in a realm, perform an HTTP POST to the /json/realms/root/realms/realm/policies endpoint,
with an _action parameter set to create. Include a JSON representation of the policy in the POST data.
The <session-cookie-name> header is required and should contain the SSO token of an administrative user,
such as amAdmin, who has access to perform the operation.
|
Configure the 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:
For more information about testing OAuth 2.0 policies, see Dynamic OAuth 2.0 authorization. |
Do not use special characters in resource type, policy, or policy set names (for example, "my+resource+type"). If you
include special characters, AM returns a 400 Bad Request error. This includes the following special characters:
double quotes ("), plus sign (+), comma (,), less than (<), equals (=), greater than (>),
backslash (\), forward slash (/), semicolon (;), and null (\u0000).
$ curl \
--request POST \
--header "Content-Type: application/json" \
--header "<session-cookie-name>: AQIC5…" \
--header "Accept-API-Version: resource=1.0" \
--data '{
"name": "mypolicy",
"active": true,
"description": "My Policy.",
"applicationName": "iPlanetAMWebAgentService",
"actionValues": {
"POST": false,
"GET": true
},
"resources": [
"http://www.example.com:80/",
"http://www.example.com:80/?"
],
"subject": {
"type": "Identity",
"subjectValues": [
"uid=demo,ou=People,dc=example,dc=com"
]
},
"resourceTypeUuid": "12345a67-8f0b-123c-45de-6fab78cd01e4"
}' \
"https://<tenant-name>.forgeblocks.com/am/json/realms/root/policies?_action=create"
{
"name":"mypolicy",
"active":true,
"description":"My Policy.",
"applicationName":"iPlanetAMWebAgentService",
"actionValues":{
"POST":false,
"GET":true
},
"resources":[
"http://www.example.com:80/",
"http://www.example.com:80/?"
],
"subject":{
"type":"Identity",
"subjectValues":[
"uid=demo,ou=People,dc=example,dc=com"
]
},
"resourceTypeUuid":"12345a67-8f0b-123c-45de-6fab78cd01e4",
"lastModifiedBy":"id=amadmin,ou=user,dc=openam,dc=forgerock,dc=org",
"lastModifiedDate":"2015-05-11T14:48:08.711Z",
"createdBy":"id=amadmin,ou=user,dc=openam,dc=forgerock,dc=org",
"creationDate":"2015-05-11T14:48:08.711Z"
}You can use the query string parameters _prettyPrint=true to make the output easier to read,
and _fields=field-name[,field-name…] to limit the fields returned in the output.
Update policies
To update an individual policy in a realm, perform an HTTP PUT to the /json/realms/root/realms/realm/policies endpoint,
and specify the policy name in the URL.
Include a JSON representation of the updated policy in the PUT data.
The <session-cookie-name> header is required and should contain the SSO token of an administrative user,
such as amAdmin, who has access to perform the operation.
Do not use special characters in resource type, policy, or policy set names (for example, "my+resource+type"). If you
include special characters, AM returns a 400 Bad Request error. This includes the following special characters:
double quotes ("), plus sign (+), comma (,), less than (<), equals (=), greater than (>),
backslash (\), forward slash (/), semicolon (;), and null (\u0000).
$ curl \
--request PUT \
--header "<session-cookie-name>: AQIC5w…" \
--header "Content-Type: application/json" \
--header "Accept-API-Version: resource=1.0" \
--data '{
"name": "myupdatedpolicy",
"active": true,
"description": "My Updated Policy.",
"resources": [
"http://www.example.com:80/",
"http://www.example.com:80/?*"
],
"actionValues": {
"POST": true,
"GET": true
},
"subject": {
"type": "Identity",
"subjectValues": [
"uid=scarter,ou=People,dc=example,dc=com",
"uid=bjenson,ou=People,dc=example,dc=com"
]
},
"resourceTypeUuid": "12345a67-8f0b-123c-45de-6fab78cd01e4"
}' \
"https://<tenant-name>.forgeblocks.com/am/json/realms/root/policies/mypolicy"You can use the query string parameters _prettyPrint=true to make the output easier to read,
and _fields=field-name[,field-name…] to limit the fields returned in the output.
Delete policies
To delete an individual policy in a realm, perform an HTTP DELETE to the /json/realms/root/realms/realm/policies endpoint,
and specify the policy name in the URL.
The <session-cookie-name> header is required and should contain the SSO token of an administrative user,
such as amAdmin, who has access to perform the operation.
$ curl \
--header "<session-cookie-name>: AQIC5w…" \
--header "Accept-API-Version: resource=2.1" \
--request DELETE \
"https://<tenant-name>.forgeblocks.com/am/json/realms/root/policies/myupdatedpolicy"Copy and move policies
You can copy or move an individual policy by performing an HTTP POST
to the /json/realms/root/realms/realm/policies/policyName endpoint as follows:
-
Specify the
_action=copyor_action=moveURL parameter. -
Specify the realm in which the input policy resides in the URL.
-
Specify the policy to be copied or moved in the URL.
-
Specify the SSO token of an administrative user who has access to perform the operation in the
iPlanetDirectoryProheader.
JSON input data for copying or moving individual policies
| Object | Property | Description |
|---|---|---|
|
|
The name of the output policy. Required unless you are copying or moving a policy to a different realm and you want the output policy to have the same name as the input policy. |
|
|
The policy set in which to place the output policy. Required when copying or moving a policy to a different policy set. |
|
|
The realm in which to place the output policy. If not specified, AM copies or moves the policy within the realm identified in the URL. Required when copying or moving a policy to a different realm. |
|
|
The UUID of the output policy’s resource type. Required when copying or moving a policy to a different realm. |
The follow example copies the policy myPolicy to myNewPolicy.
The output policy is placed in the myRealm realm, in the same policy set as the input policy:
$ curl \
--header "<session-cookie-name>: AQIC5w…" \
--header "Accept-API-Version: resource=2.1" \
--request DELETE \
"https://<tenant-name>.forgeblocks.com/am/json/realms/root/policies/myupdatedpolicy"
{}The following example moves a policy named myPolicy in the myRealm realm
to myMovedPolicy in the myOtherRealm realm.
The output policy is placed in the iPlanetAMWebAgentService policy set,
which is the policy set in which the input policy is located.
The realm myOtherRealm must be configured as follows for the example to run successfully:
-
It must have a resource type that has the same resources as the resource type configured for the
myPolicypolicy. -
It must have a policy set named
iPlanetAMWebAgentService.
$ curl \
--request POST \
--header "Content-Type: application/json" \
--header "<session-cookie-name>: AQIC5w…" \
--header "Accept-API-Version: resource=2.1" \
--data '{
"to": {
"name": "myMovedPolicy",
"realm": "/myOtherRealm",
"resourceType: "616b3d02-7a8d-4422-b6a7-174f62afd065"
}
}' \
"https://<tenant-name>.forgeblocks.com/am/json/realms/root/realms/myRealm/policies/myPolicy?_action=move"
{
"name":"myMovedPolicy",
"active":true,
"description":"",
"actionValues":{},
"applicationName":"iPlanetAMWebAgentService",
"resources":["://:*/*"],
"subject":{"type":"NONE"},
"resourceTypeUuid":"616b3d02-7a8d-4422-b6a7-174f62afd065",
"lastModifiedBy":"id=amadmin,ou=user,dc=example,dc=com",
"lastModifiedDate":"2015-12-21T19:32:59.502Z",
"createdBy":"id=amadmin,ou=user,dc=example,dc=com",
"creationDate":"2015-12-21T19:32:59.502Z"
}You can also copy and move multiple policies—all the policies in a policy set—in a single operation
by performing an HTTP POST to the /json/realms/root/realms/realm/policies endpoint as follows:
-
Specify the
_action=copyor_action=moveURL parameter. -
Specify the realm in which the input policies reside as part of the URL. If no realm is specified in the URL, AM copies or moves policies within the top level realm.
-
Specify the SSO token of an administrative user who has access to perform the operation in the
iPlanetDirectoryProheader.
JSON input data for copying or moving multiple policies
| Object | Property | Description |
|---|---|---|
|
|
The policy set in which the input policies are located. Required. |
|
|
The policy set in which to store output policies. Required when copying or moving policies to a different policy set. |
|
|
The realm in which to store output policies. Required when copying or moving policies to a different realm. |
|
|
A value appended to output policy names in order to prevent name clashes. Required. |
|
Varies |
One or more resource types mappings, where the left side of the mapping specifies the UUID of a resource type used by the input policies, and the right side of the mapping specifies the UUID of a resource type used by the output policies. The two resource types should have the same resource patterns. Required when copying or moving policies to a different realm. |
The following example copies all the policies in the iPlanetAMWebAgentService policy set
in the myRealm realm to the iPlanetAMWebAgentService policy set in the myOtherRealm realm,
appending the string -copy to the output policy names.
The realm myOtherRealm must be configured as follows for the example to run successfully:
-
It must have a resource type that maps to the
ccb50c1a-206d-4946-9106-4164e8f2b35bresource type. The two resource types should have the same resource patterns. -
It must have a policy set named
iPlanetAMWebAgentService.
The JSON output shows that a single policy is copied.
The policy myNewPolicy is copied to realm myOtherRealm.
The copied policy receives the name myOtherRealm-copy:
$ url \
--request POST \
--header "Content-Type: application/json" \
--header "<session-cookie-name>: AQIC5w…" \
--header "Accept-API-Version: resource=2.1" \
--data '{
"from":{
"application":"iPlanetAMWebAgentService"
},
"to":{
"realm":"/myOtherRealm",
"namePostfix":"-copy"
},
"resourceTypeMapping":{
"ccb50c1a-206d-4946-9106-4164e8f2b35b":"616b3d02-7a8d-4422-b6a7-174f62afd065"
}
}' \
"https://<tenant-name>.forgeblocks.com/am/json/realms/root/realms/myRealm/policies?_action=copy"
{
"name":"myNewPolicy-copy",
"active":true,
"description":"",
"actionValues":{},
"applicationName":"iPlanetAMWebAgentService",
"resources":["://:*/*"],"subject":{"type":"NONE"},
"resourceTypeUuid":"616b3d02-7a8d-4422-b6a7-174f62afd065",
"lastModifiedBy":"id=amadmin,ou=user,dc=example,dc=com",
"lastModifiedDate":"2015-12-21T20:01:42.410Z",
"createdBy":"id=amadmin,ou=user,dc=example,dc=com",
"creationDate":"2015-12-21T20:01:42.410Z"
}Manage environment condition types
Environment condition types describe the JSON representation of environment conditions that you can use in policy definitions.
AM provides the conditiontypes REST endpoint for the following:
Environment condition types are server-wide, and do not differ by realm.
Hence the URI for the condition types API does not contain a realm component, but is /json/conditiontypes.
Script is the only environmental condition available for OAuth 2.0 policies.
Use scripts to capture the ClientId environmental attribute.
Environment condition types are represented in JSON and take the following form.
Environment condition types are built from standard JSON objects and values
(strings, numbers, objects, arrays, true, false, and null).
{
"title": "IPv4",
"logical": false,
"config": {
"type": "object",
"properties": {
"startIp": {
"type": "string"
},
"endIp": {
"type": "string"
},
"dnsName": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
}Notice that the environment condition type has a title, a "logical" field that indicates whether the type is a logical operator or takes a predicate, and a configuration specification. The configuration specification in this case indicates that an IPv4 environment condition has two properties, "startIp" and "endIp", that each take a single string value, and a third property, "dnsName," that takes an array of string values. In other words, a concrete IP environment condition specification without a DNS name constraint could be represented in a policy definition as in the following example:
{
"type": "IPv4",
"startIp": "127.0.0.1",
"endIp": "127.0.0.255"
}The configuration is what differs the most across environment condition types. The NOT condition, for example, takes a single condition object as the body of its configuration.
{
"title" : "NOT",
"logical" : true,
"config" : {
"type" : "object",
"properties" : {
"condition" : {
"type" : "object",
"properties" : {
}
}
}
}
}The concrete NOT condition therefore takes the following form.
{
"type": "NOT",
"condition": {
...
}
}The OR condition takes an array of conditions.
{
"title" : "OR",
"logical" : true,
"config" : {
"type" : "object",
"properties" : {
"conditions" : {
"type" : "array",
"items" : {
"type" : "any"
}
}
}
}
}A corresponding concrete OR condition thus takes the following form.
{
"type": "OR",
"conditions": [
{
...
},
{
...
},
...
]
}Query environment condition types
To list all environment condition types, perform an HTTP GET to the /json/conditiontypes endpoint,
with a _queryFilter parameter set to true.
The <session-cookie-name> header is required and should contain the SSO token of an administrative user,
such as amAdmin, who has access to perform the operation.
$ curl \
--header "<session-cookie-name>: AQIC5…" \
--header "Accept-API-Version: resource=1.0, protocol=2.1" \
'https://<tenant-name>.forgeblocks.com/am/json/realms/root/conditiontypes?_queryFilter=true'
{
"result" : [
{
"title": "IPv4",
}
"logical": false,
"config": {
"type": "object",
"properties": {
"startIp": {
"type": "string"
},
"endIp": {
"type": "string"
},
"dnsName": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
},
{
"title": "NOT",
"logical": true,
"config": {
"type": "object",
"properties": {
"condition": {
"type": "object",
"properties": { }
}
}
}
},
{…},
{…},
{…}
],
"resultCount" : 18,
"pagedResultsCookie" : null,
"remainingPagedResults" : 0
}Additional query strings can be specified to alter the returned results. For more information, see Query.
Read a specific environment condition type
To read an individual environment condition type, perform an HTTP GET to the /json/conditiontypes endpoint,
and specify the environment condition type name in the URL.
The <session-cookie-name> header is required and should contain the SSO token of an administrative user,
such as amAdmin, who has access to perform the operation.
$ curl \
--header "<session-cookie-name>: AQIC5…" \
--header "Accept-API-Version: resource=1.0" \
'https://<tenant-name>.forgeblocks.com/am/json/realms/root/conditiontypes/IPv4'
{
"title":"IPv4",
"logical":false,
"config":{
"type":"object",
"properties":{
"startIp":{
"type":"string"
},
"endIp":{
"type":"string"
},
"dnsName":{
"type":"array",
"items":{
"type":"string"
}
}
}
}
}Manage subject condition types
Subject condition types describe the JSON representation of subject conditions that you can use in policy definitions.
AM provides the subjecttypes REST endpoint for the following:
Environment condition types are server-wide, and do not differ by realm.
Hence the URI for the condition types API does not contain a realm component, but is /json/subjecttypes.
Subject condition types are represented in JSON and take the following form.
Subject condition types are built from standard JSON objects and values
(strings, numbers, objects, arrays, true, false, and null).
{
"title" : "Identity",
"logical" : false,
"config" : {
"type" : "object",
"properties" : {
"subjectValues" : {
"type" : "array",
"items" : {
"type" : "string"
}
}
}
}
}Notice that the subject type has a title, a "logical" field that indicates whether the type is a logical operator or takes a predicate, and a configuration specification. The configuration specification in this case indicates that an Identity subject condition has one property, "subjectValues", which takes an array of string values. In other words, a concrete Identity subject condition specification is represented in a policy definition as in the following example:
{
"type": "Identity",
"subjectValues": [
"uid=scarter,ou=People,dc=example,dc=com"
]
}The configuration is what differs the most across subject condition types. The AND condition, for example, takes an array of subject condition objects as the body of its configuration.
{
"title" : "AND",
"logical" : true,
"config" : {
"type" : "object",
"properties" : {
"subjects" : {
"type" : "array",
"items" : {
"type" : "any"
}
}
}
}
}The concrete AND subject condition therefore takes the following form.
{
"type": "AND",
"subject": [
{...},
{...},
{...},
{...}
]
}Query subject condition types
To list all environment condition types, perform an HTTP GET to the /json/subjecttypes endpoint,
with a _queryFilter parameter set to true.
The <session-cookie-name> header is required and should contain the SSO token of an administrative user,
such as amAdmin, who has access to perform the operation.
$ curl \
--header "<session-cookie-name>: AQIC5…" \
--header "Accept-API-Version: resource=1.0" \
'https://<tenant-name>.forgeblocks.com/am/json/realms/root/subjecttypes?_queryFilter=true'
{
"result" : [
{
"title": "JwtClaim"
}
"logical": false,
"config": {
"type": "object",
"properties": {
"claimName": {
"type": "string"
},
"claimValue": {
"type": "string"
}
}
}
},
{
"title": "NOT",
"logical": true,
"config": {
"type": "object",
"properties": {
"subject": {
"type": "object",
"properties": { }
}
}
}
},
{…},
{…},
{…}
],
"resultCount" : 5,
"pagedResultsCookie" : null,
"remainingPagedResults" : 0
}Additional query strings can be specified to alter the returned results. For more information, see Query.
Read a specific subject condition type
To read an individual subject condition type, perform an HTTP GET to the /json/subjecttypes endpoint,
and specify the subject condition type name in the URL.
The <session-cookie-name> header is required and should contain the SSO token of an administrative user,
such as amAdmin, who has access to perform the operation.
$ curl \
--header "<session-cookie-name>: AQIC5…" \
--header "Accept-API-Version: resource=1.0" \
'https://<tenant-name>.forgeblocks.com/am/json/realms/root/subjecttypes/Identity'
{
"title" : "Identity",
"logical" : false,
"config" : {
"type" : "object",
"properties" : {
"subjectValues" : {
"type" : "array",
"items" : {
"type" : "string"
}
}
}
}Manage subject attributes
When you define a policy subject condition, the condition can depend on values of subject attributes stored in a user’s profile. The list of possible subject attributes that you can use depends on the LDAP User Attributes configured for the identity store where AM looks up the user’s profile.
AM provides the subjectattributes REST endpoint for Query subject attributes.
Subject attributes derive from the list of LDAP user attributes configured for the identity store.
Query subject attributes
To list all subject attributes, perform an HTTP GET to the /json/subjectattributes endpoint,
with a _queryFilter parameter set to true.
The <session-cookie-name> header is required and should contain the SSO token of an administrative user,
such as amAdmin, who has access to perform the operation.
$ curl \
--header "<session-cookie-name>: AQIC5…" \
--header "Accept-API-Version: resource=1.0" \
'https://<tenant-name>.forgeblocks.com/am/json/realms/root/subjectattributes/?_queryFilter=true'
{
"result" : [
"sunIdentityServerPPInformalName",
"sunIdentityServerPPFacadeGreetSound",
"uid",
"manager",
"sunIdentityServerPPCommonNameMN",
"sunIdentityServerPPLegalIdentityGender",
"preferredLocale",
"…",
"…",
"…"
],
"resultCount": 87,
"pagedResultsCookie": null,
"remainingPagedResults": 0
}Note that no pagination cookie is set and the subject attribute names are all returned as part of the "result" array.
Manage decision combiners
Decision combiners describe how to resolve policy decisions when multiple policies apply.
AM provides the decisioncombiners REST endpoint for the following:
Decision combiners are server-wide, and do not differ by realm.
Hence, the URI for the condition types API does not contain a realm component, but is /json/decisioncombiners.
Query decision combiners
To list all decision combiners, perform an HTTP GET to the /json/decisioncombiners endpoint,
with a _queryFilter parameter set to true.
The <session-cookie-name> header is required and should contain the SSO token of an administrative user,
such as amAdmin, who has access to perform the operation.
$ curl \
--header "<session-cookie-name>: AQIC5…" \
--header "Accept-API-Version: resource=1.0, protocol=2.1" \
'https://<tenant-name>.forgeblocks.com/am/json/realms/root/realms/alpha/decisioncombiners?_queryFilter=true'
{
"result":[
{
"title":"DenyOverride"
}
],
"resultCount":1,
"pagedResultsCookie":null,
"remainingPagedResults":0
}Additional query strings can be specified to alter the returned results. For more information, see Query.
Read a specific decision combiner
To view an individual decision combiner, perform an HTTP GET on its resource.
To read an individual decision combiner, perform an HTTP GET to the /json/decisioncombiners endpoint,
and specify the decision combiner name in the URL.
The <session-cookie-name> header is required and should contain the SSO token of an administrative user,
such as amAdmin, who has access to perform the operation.
$ curl \
--header "<session-cookie-name>: AQIC5…" \
--header "Accept-API-Version: resource=1.0" \
'https://<tenant-name>.forgeblocks.com/am/json/realms/root/realms/alpha/decisioncombiners/DenyOverride'
{
"title" : "DenyOverride"
}Resource types
Resource types define a template for the resources that policies apply to, and the actions that can be performed on those resources.
AM needs a policy to decide whether a user can access a resource. When you configure a policy, you also configure a resource (or a pattern to match several resources) that the policy applies to, and the actions that the policy allows or denies.
Resource types are templates that you can define once and reuse in several policies. For example, you could create a template that always allows PUT and POST operations from your internal network.
Default resource types
AM includes two resource types by default: URL and OAuth2 Scope. These default resource types are sufficient
for most environments.
URLresource type-
The
URLresource type acts as a template for protecting web pages or applications. It contains resource patterns, such as*://*:*/*?*, that can be more specific when used in the policy.This resource type supports the following actions:
GET
POST
PUT
HEAD
PATCH
DELETE
OPTIONSFor example, an application for Example.com’s HR service might contain resource types that constrain all policies to apply to URL resource types under
http*://example.com/hr*andhttp*://example.com/hr*?*, and only allow HTTPGETandPOSTactions.AM also includes a resource type to protect REST endpoints, with patterns including
https://*:*/*?*and theCRUDPAQactions:CREATE
READ
UPDATE
DELETE
PATCH
ACTION
QUERY OAuth2 Scoperesource type-
The
OAuth2 Scoperesource type acts as a template for granting or denying OAuth 2.0 scopes. It contains a string-based scope pattern,*, and two URL-based scope patterns, such as*://*:*/*?*. The resource supports theGRANTaction, which can be allowed or denied.
Resource types in the UI
-
In the AM admin UI, go to Realms > Realm Name > Authorization > Resource Types.
-
To create a new resource type, click New Resource Type.
-
To modify an existing resource type, select the resource type name.
-
To delete an existing resource type, click Delete in the row containing the resource type.
You can only delete resource types that are not being used by policy sets or policies. Trying to delete a resource type that is in use returns an HTTP 409 Conflict status code.
Remove the resource type from any associated policy sets or policies to be able to delete it.
-
-
Provide a name for the resource type, and optionally, a description.
Do not use special characters in resource type, policy, or policy set names (for example,
"my+resource+type"). If you include special characters, AM returns a 400 Bad Request error. This includes the following special characters: double quotes ("), plus sign (+), comma (,), less than (<), equals (=), greater than (>), backslash (\), forward slash (/), semicolon (;), and null (\u0000). -
To define resource patterns that policies using this resource type can expand upon, follow the steps below:
-
In the Add a new pattern… box, enter a pattern with optional wildcards that the policies will use as a template.
Specify resource patterns with wildcards
Resource patterns can specify an individual URL or resource name to protect. Alternatively, a resource pattern can match URLs or resource names by using wildcards.
-
The wildcards you can use are
*and-*-.These wildcards can be used throughout resource patterns to match URLs or resource names. For a resource pattern used to match URLs, wildcards can be employed to match the scheme, host, port, path, and query string of a resource.
-
When used within the path segment of a resource, the wildcard
*matches multiple path segments.For example,
http://www.example.com/*matcheshttp://www.example.com/,http://www.example.com/index.html, and alsohttp://www.example.com/company/images/logo.png. -
When used within the path segment of a resource, the wildcard
-*-will only match a single path segment.For example,
http://www.example.com/-*-matcheshttp://www.example.com/index.html, but does not matchhttp://www.example.com/company/resource.htmlorhttp://www.example.com/company/images/logo.png.
-
-
Wildcards do not match
?. You must explicitly add patterns to match URLs with query strings.-
When matching URLs sent from a web or Java agent, an asterisk (
*) used at the end of a pattern after a?character matches one or more characters, not zero or more characters.For example,
http://www.example.com/*?*matcheshttp://www.example.com/users?_action=create, but nothttp://www.example.com/users?.To match everything under
http://www.example.com/specify three patterns, one forhttp://www.example.com/*, one forhttp://www.example.com/*?, and one forhttp://www.example.com/*?*. -
When matching resources by using the
policies?_action=evaluateREST endpoint, an asterisk (kbd:[*]) used at the end of a pattern after a?character matches zero or more characters.For example,
http://www.example.com/*?*matcheshttp://www.example.com/users?_action=create, as well ashttp://www.example.com/users?.To match everything under
http://www.example.com/specify two patterns, one forhttp://www.example.com/*, one forhttp://www.example.com/*?*.
-
-
When defining patterns to match URLs with query strings, AM sorts the query string field-value pairs alphabetically by field name when normalizing URLs before checking whether a policy matches. Therefore, the query string
?subject=SPBnfm+t5PlP+ISyQhVlplE22A8=&action=getis equivalent to the query string?action=get&subject=SPBnfm+t5PlP+ISyQhVlplE22A8=. -
Duplicate slashes (
/) are not considered part of the resource name to match. A trailing slash is considered by AM as part of the resource name.For example,
http://www.example.com//path/, andhttp://www.example.com/path//are treated in the same way.http://www.example.com/path, andhttp://www.example.com/path/are considered two distinct resources. -
Wildcards can be used to match protocols, host names, and port numbers.
For example,
*://*:*/*matcheshttp://www.example.com:80/index.html,https://www.example.com:443/index.html, andhttp://www.example.net:8080/index.html.When a port number is not explicitly specified, then the default port number is implied. Therefore
http://www.example.com/*is the same ashttp://www.example.com:80/*, andhttps://www.example.com/*is the same ashttps://www.example.com:443/*. -
Wildcards cannot be escaped.
-
Do not mix
*and-*-in the same pattern. -
To match a resource that uses non-ASCII characters, percent-encode the resource when creating the rule.
For example, to match resources under an Internationalized Resource Identifier (IRI), such as
http://www.example.com/forstå, specify the following percent-encoded pattern:http://www.example.com:80/forst%C3%A5/*
-
By default, comparisons are not case-sensitive. The delimiter, wildcards and case-sensitivity are configurable.
-
-
Click +Add Pattern to confirm the pattern.
To remove a pattern, select the Delete icon.
-
-
To define the actions that policies using this resource type can allow or deny, follow the steps below:
-
In the Add a new action… box, enter an action related to the types of resources being described, and click +Add Action.
-
Select either Allow or Deny as the default state for the action.
To remove an action, select the Delete icon.
-
-
Continue adding the patterns and actions that your resource type requires.
Figure 8. Configuring Resource Types in the UI -
Select Create to save a new resource type or Save Changes to save modifications to an existing resource type.
Resource types over REST
You can manage resource types over REST at the resourcetypes endpoint.
Resource types are realm-specific. The URI for the resource types API can therefore contain a realm component,
for example, json/realms/root/realms/myRealm/resourcetypes.
Resource types take the form of standard JSON objects and values (strings, numbers, objects, sets, arrays, true, false,
and null). Each resource type has a unique, system-generated UUID, which must be used when modifying existing resource
types. Renaming a resource type does not affect the UUID.
Example
{
"uuid": "12345a67-8f0b-123c-45de-6fab78cd01e2",
"name": "URL",
"description": "The built-in URL Resource Type available to OpenAM Policies.",
"patterns": [
"*://*:*/*?*",
"*://*:*/*"
],
"actions": {
"POST": true,
"PATCH": true,
"GET": true,
"DELETE": true,
"OPTIONS": true,
"HEAD": true,
"PUT": true
},
"createdBy": "id=dsameuser,ou=user,dc=openam,dc=forgerock,dc=org",
"creationDate": 1422892465848,
"lastModifiedBy": "id=dsameuser,ou=user,dc=openam,dc=forgerock,dc=org",
"lastModifiedDate": 1422892465848
}A resource type object can include the following fields:
uuid-
String matching the unique identifier AM generated for the resource type when created.
name-
The name provided for the resource type.
description-
An optional text string to help identify the resource type.
patterns-
An array of resource patterns specifying individual URLs or resource names to protect.
For more information on patterns in resource types and policies, see Specifying Resource Patterns with Wildcards.
actions-
Set of string action names, each set to a boolean indicating whether the action is allowed.
createdBy-
A string containing the universal identifier DN of the subject that created the resource type.
creationDate-
An integer containing the creation date and time, in ISO 8601 format.
lastModifiedBy-
A string containing the universal identifier DN of the subject that most recently updated the resource type.
If the resource type has not been modified since it was created, this will be the same value as
createdBy. lastModifiedDate-
An string containing the last modified date and time, in ISO 8601 format.
If the resource type has not been modified since it was created, this will be the same value as
creationDate.
Before making a REST API call to manage a resource type, make sure that you have:
-
Authenticated successfully to AM as a user with sufficient privileges to make the REST API call.
-
Obtained the session token returned after successful authentication.
When making a REST API call, specify the realm in the path component of the endpoint.
You must also pass the session token in the HTTP header. For more information about the AM session token and its use in REST API calls, see Using the session token after authentication.
Query resource types
To list all the resource types in a realm, send an HTTP GET request to the /json/realms/root/realms/realm/resourcetypes endpoint,
with _queryFilter=true.
The <session-cookie-name> header is required and should contain the SSO token of an administrative user,
such as amAdmin, who has access to perform the operation.
$ curl \
--header "<session-cookie-name>: AQIC5…" \
--header "Accept-API-Version: resource=1.0" \
'https://<tenant-name>.forgeblocks.com/am/json/realms/root/realms/myrealm/resourcetypes?_queryFilter=true'
{
"result":[
{
"uuid":"12345a67-8f0b-123c-45de-6fab78cd01e3",
"name":"LIGHTS",
"description":"",
"patterns":[
"light:///"
],
"actions":{
"switch_off":true,
"switch_on":true
},
"createdBy":"id=amadmin,ou=user,dc=openam,dc=forgerock,dc=org",
"creationDate":1431013059131,
"lastModifiedBy":"id=amadmin,ou=user,dc=openam,dc=forgerock,dc=org",
"lastModifiedDate":1431013069803
}
],
"resultCount":1,
"pagedResultsCookie":null,
"remainingPagedResults":0
}Additional query strings can be specified to alter the returned results. For more information, see Query.
Supported _queryFilter Fields and Operators
| Field | Supported Operators |
|---|---|
|
Equals ( |
|
Equals ( |
|
Equals ( |
|
Equals ( |
|
Equals ( |
Read a resource type
To read a specific resource types in a realm, send an HTTP GET request to the /json/realms/root/realms/realm/resourcetypes endpoint, specifying the UUID in the URL.
The <session-cookie-name> header is required and should contain the SSO token of an administrative user,
such as amAdmin, who has access to perform the operation.
$ curl \
--header "<session-cookie-name>: AQIC5…" \
--header "Accept-API-Version: resource=1.0" \
'https://<tenant-name>.forgeblocks.com/am/json/realms/root/realms/myrealm/resourcetypes/12345a67-8f0b-123c-45de-6fab78cd01e3'
{
"uuid":"12345a67-8f0b-123c-45de-6fab78cd01e3",
"name":"LIGHTS",
"description":"",
"patterns":[
"light:///"
],
"actions":{
"switch_off":true,
"switch_on":true
},
"createdBy":"id=amadmin,ou=user,dc=openam,dc=forgerock,dc=org",
"creationDate":1431013059131,
"lastModifiedBy":"id=amadmin,ou=user,dc=openam,dc=forgerock,dc=org",
"lastModifiedDate":1431013069803
}Create a resource type
To create a resource type in a realm, send an HTTP POST request to the /json/realms/root/realms/realm/resourcetypes endpoint, with
_action=create. Include a JSON representation of the resource type in the POST data.
The <session-cookie-name> header is required and should contain the SSO token of an administrative user,
such as amAdmin, who has access to perform the operation.
Do not use special characters in resource type, policy, or policy set names (for example, "my+resource+type"). If you
include special characters, AM returns a 400 Bad Request error. This includes the following special characters:
double quotes ("), plus sign (+), comma (,), less than (<), equals (=), greater than (>),
backslash (\), forward slash (/), semicolon (;), and null (\u0000).
$ curl \
--request POST \
--header "Content-Type: application/json" \
--header "<session-cookie-name>: AQIC5…" \
--header "Accept-API-Version: resource=1.0" \
--data '{
"name":"My Resource Type",
"actions":{
"LEFT":true,
"RIGHT":true,
"UP":true,
"DOWN":true
},
"patterns":[
"http://device/location/"
]
}' \
'https://<tenant-name>.forgeblocks.com/am/json/realms/root/realms/myrealm/resourcetypes/?_action=create'
{
"uuid":"12345a67-8f0b-123c-45de-6fab78cd01e4",
"name":"My Resource Type",
"description":null,
"patterns":[
"http://device/location/"
],
"actions":{
"RIGHT":true,
"DOWN":true,
"UP":true,
"LEFT":true
},
"createdBy":"id=amadmin,ou=user,dc=openam,dc=forgerock,dc=org",
"creationDate":1431099940616,
"lastModifiedBy":"id=amadmin,ou=user,dc=openam,dc=forgerock,dc=org",
"lastModifiedDate":1431099940616
}
Update a resource type
To update a specific resource type in a realm, send an HTTP PUT request to the /json/realms/root/realms/realm/resourcetypes endpoint, specifying the UUID in both the URL and the PUT body. Include a JSON representation of the updated resource type in the PUT data, alongside the UUID.
The <session-cookie-name> header is required and should contain the SSO token of an administrative user,
such as amAdmin, who has access to perform the operation.
Do not use special characters in resource type, policy, or policy set names (for example, "my+resource+type"). If you
include special characters, AM returns a 400 Bad Request error. This includes the following special characters:
double quotes ("), plus sign (+), comma (,), less than (<), equals (=), greater than (>),
backslash (\), forward slash (/), semicolon (;), and null (\u0000).
$ curl \
--request PUT \
--header "Content-Type: application/json" \
--header "iPlanetDirectoryPro: AQIC5…" \
--header "Accept-API-Version: resource=1.0" \
--data '{
"name":"My Resource Type",
"uuid":"12345a67-8f0b-123c-45de-6fab78cd01e4"
"actions":{
"LEFT":true,
"RIGHT":true,
"UP":false,
"DOWN":false
},
"patterns":[
"http://device/location/"
]
}' \
'https://<tenant-name>.forgeblocks.com/am/json/realms/root/realms/myrealm/resourcetypes/12345a67-8f0b-123c-45de-6fab78cd01e4'
{
"uuid":"12345a67-8f0b-123c-45de-6fab78cd01e4",
"name":"My Resource Type",
"description":null,
"patterns":[
"http://device/location/"
],
"actions":{
"RIGHT":true,
"DOWN":true,
"UP":false,
"LEFT":false
},
"createdBy":"id=amadmin,ou=user,dc=openam,dc=forgerock,dc=org",
"creationDate":1431099940616,
"lastModifiedBy":"id=amadmin,ou=user,dc=openam,dc=forgerock,dc=org",
"lastModifiedDate":1637667798885
}Delete a resource type
To delete a specific resource types in a realm, send an HTTP DELETE request to the /json/realms/root/realms/realm/resourcetypes endpoint, specifying the UUID in the URL.
The <session-cookie-name> header is required and should contain the SSO token of an administrative user,
such as amAdmin, who has access to perform the operation.
$ curl \
--request DELETE \
--header "<session-cookie-name>: AQIC5…" \
--header "Accept-API-Version: resource=1.0" \
'https://<tenant-name>.forgeblocks.com/am/json/realms/root/realms/myrealm/resourcetypes/12345a67-8f0b-123c-45de-6fab78cd01e4'
{}You can only delete resource types that are not being used by a policy set or policy. If you attempt to delete a resource type that is in use, AM returns an HTTP 409 Conflict status code, with a message such as:
{
"code": 409,
"reason": "Conflict",
"message": "Unable to remove resource type 12345a67-8f0b-123c-45de-6fab78cd01e4 because it is
referenced in the policy model."
}
Remove the resource type from any associated policy sets or policies before you delete it.
Policy sets
Policy sets are associated with a set of resource types, and contain one or more policies based upon the template it provides. They are used as templates for policies protecting websites, web applications, or other resources.
For AM to decide if a user can access a resource, it requires a policy.
Policy sets are a way to group policies that protect applications or sites that have similar characteristics. For example, they all use the same resource type. This means that you do not need to configure the same set of parameters in each policy.
AM includes two policy sets that are used for web and Java agents, and for dynamic OAuth 2.0 policies.
Policy sets have templates, called application types. There are two application types defined by default, which correspond to the default policy sets. You can only configure these using REST, but for most use cases, you can use the default application types.
Default policy sets
AM includes the following default policy sets:
-
The Default Policy Set,
iPlanetAMWebAgentServiceis the policy set configured by default for web and Java agents. You can create new policy sets for agents and configure them in the agent profile. -
The Default OAuth2 Scopes Policy Set,
oauth2Scopes, is the policy set configured for the OAuth 2.0 service on the realm.The OAuth 2.0 service cannot be configured to use a different policy set. Configure all policies required for your OAuth 2.0 service in the Default OAuth2 Scopes Policy Set.
When creating or editing policy sets, consider the following points:
-
When the realm and policy set differ for your web or Java agent, you can specify the realm and policy set in the agent profile. AM then directs requests from the agent to the specified realm and policy set, so this is backwards compatible with existing web and Java agents.
You can configure the realm and policy set the agent uses in the agent profile. See the ForgeRock web agents documentation, or the ForgeRock Java agents documentation for more information.
-
AM only honors
OAuth2 Scoperesource type policies configured in the Default OAuth2 Scopes Policy Set. Configure all policies required for your OAuth 2.0 service in the Default OAuth2 Scopes Policy Set. -
AM creates a policy set containing a policy representing the resources and identities specified by a resource owner using UMA 2.0 to share their registered resources.
These policies appear in the AM admin UI as read-only, and cannot be edited by administrative users such as
amAdmin. They can, however, be viewed and deleted.
Manage policy sets using the AM admin UI or the REST API:
Policy sets in the UI
-
In the AM admin UI, go to Realms > Realm Name > Authorization > Policy Sets.
-
To create a new policy set, select New Policy Set.
-
To modify an existing policy set, select it from the table.
-
-
If creating a new policy, enter an ID for the policy set. This is a required parameter.
Once a policy set is created, you cannot change its
ID. -
If creating a new policy, enter a name for the policy set. The name is optional and is for display purposes only.
Do not use special characters in resource type, policy, or policy set names (for example,
"my+resource+type"). If you include special characters, AM returns a 400 Bad Request error. This includes the following special characters: double quotes ("), plus sign (+), comma (,), less than (<), equals (=), greater than (>), backslash (\), forward slash (/), semicolon (;), and null (\u0000). -
From the Resource Types drop-down list, select one or more resource types that policies in this policy set will use.
To remove a resource type from the policy set, select the label, and then press kbd:[Delete] or kbd:[Backspace].
Configure the
OAuth2 Scoperesource type only in the Default OAuth2 Scopes Policy Set. Any policy configured for theOAuth2 Scoperesource type outside the default policy set will not be evaluated. -
Select Create to save the new policy set, or Save Changes to save modifications to an existing policy set.
Policy sets over REST
You can manage policy sets over REST at the applications endpoint.
Policy sets are realm-specific. The URI for the policy set API can therefore contain a realm component, for example,
/json/realms/root/realms/realm/applications.
Policy sets take the form of standard JSON objects and values (strings, numbers, objects, sets, arrays, true, false,
and null).
Example
{
"creationDate": 1431351677264,
"lastModifiedDate": 1431351677264,
"conditions": [
"AuthenticateToService",
"Script",
"AuthScheme",
"IPv6",
"SimpleTime",
"OAuth2Scope",
"IPv4",
"AuthenticateToRealm",
"OR",
"AMIdentityMembership",
"LDAPFilter",
"AuthLevel",
"SessionProperty",
"LEAuthLevel",
"Session",
"NOT",
"AND",
"ResourceEnvIP"
],
"applicationType": "iPlanetAMWebAgentService",
"subjects": [
"JwtClaim",
"AuthenticatedUsers",
"Identity",
"NOT",
"AND",
"NONE",
"OR"
],
"entitlementCombiner": "DenyOverride",
"saveIndex": null,
"searchIndex": null,
"resourceComparator": null,
"resourceTypeUuids": [
"12345a67-8f0b-123c-45de-6fab78cd01e4"
],
"attributeNames": [ ],
"editable": true,
"createdBy": "id=dsameuser,ou=user,dc=openam,dc=forgerock,dc=org",
"lastModifiedBy": "id=dsameuser,ou=user,dc=openam,dc=forgerock,dc=org",
"description": "The built-in Application used by {am_abbr} Policy Agents.",
"realm": "/",
"name": "iPlanetAMWebAgentService"
}A policy set object can include the following fields:
conditions-
Condition types allowed in the context of this policy set.
For information on condition types, see Policies over REST and Managing Environment Condition Types.
applicationType-
Name of the application type used as a template for this policy set.
subjects-
Subject types allowed in the context of this policy set.
For information on subject types, see Policies over REST and Managing Subject Condition Types.
entitlementCombiner-
Name of the decision combiner, such as
"DenyOverride".For more on decision combiners, see Managing Decision Combiners.
saveIndex-
Class name of the implementation for creating indexes for resource names, such as
"com.sun.identity.entitlement.util.ResourceNameIndexGenerator", for URL resource names. searchIndex-
Class name of the implementation for searching indexes for resource names, such as
"com.sun.identity.entitlement.util.ResourceNameSplitter", for URL resource names. resourceComparator-
Class name of the resource comparator implementation used in the context of this policy set.
The following implementations are available:
"com.sun.identity.entitlement.ExactMatchResourceName"
"com.sun.identity.entitlement.PrefixResourceName"
"com.sun.identity.entitlement.RegExResourceName"
"com.sun.identity.entitlement.URLResourceName" resourceTypeUuids-
A list of the UUIDs of the resource types associated with the policy set.
attributeNames-
A list of attribute names such as
cn. The list is used to aid policy indexing and lookup. description-
String describing the policy set.
realm-
Name of the realm in which this policy set is defined. You must specify the realm in the policy set JSON, even though it can be derived from the URL that is used when creating the policy set.
name-
String matching the name in the URL used when creating the policy set by HTTP PUT, or in the body when creating the policy set by HTTP POST.
createdBy-
A string containing the universal identifier DN of the subject that created the policy set.
creationDate-
An integer containing the creation date and time, in number of seconds since the Unix epoch (1970-01-01T00:00:00Z).
lastModifiedBy-
A string containing the universal identifier DN of the subject that most recently updated the policy set.
If the policy set has not been modified since it was created, this will be the same value as
createdBy. lastModifiedDate-
An integer containing the last modified date and time, in number of seconds since the Unix epoch (1970-01-01T00:00:00Z).
If the policy set has not been modified since it was created, this will be the same value as
creationDate.
Before making a REST API call to request manage a policy component, make sure that you have:
-
Authenticated successfully to AM as a user with sufficient privileges to make the REST API call.
-
Obtained the session token returned after successful authentication.
When making a REST API call, specify the realm in the path component of the endpoint.
You must also pass the session token in the HTTP header. For more information about the AM session token and its use in REST API calls, see Using the session token after authentication.
Query policy sets
To list all the policy sets in a realm, send an HTTP GET request to the /json/realms/root/realms/realm/applications
endpoint, with _queryFilter=true.
The <session-cookie-name> header is required and should contain the SSO token of an administrative user,
such as amAdmin, who has access to perform the operation.
$ curl \
--header "iPlanetDirectoryPro: AQIC5…" \
--header "Accept-API-Version: resource=1.0" \
'https://<tenant-name>.forgeblocks.com/am/json/realms/root/applications?_queryFilter=true'
{
"result": [
{
"resourceComparator": null,
"saveIndex": null,
"searchIndex": null,
"applicationType": "iPlanetAMWebAgentService",
"entitlementCombiner": "DenyOverride",
"subjects": [
"AuthenticatedUsers",
"NOT",
"Identity",
"OR",
"AND",
"NONE",
"JwtClaim"
],
"attributeNames": [],
"editable": true,
"createdBy": "id=dsameuser,ou=user,dc=openam,dc=forgerock,dc=org",
"name": "iPlanetAMWebAgentService",
"description": "The built-in Application used by OpenAM Policy Agents.",
"conditions": [
"Script",
"AMIdentityMembership",
"IPv6",
"IPv4",
"SimpleTime",
"LEAuthLevel",
"LDAPFilter",
"AuthScheme",
"Session",
"AND",
"AuthenticateToRealm",
"ResourceEnvIP",
"OAuth2Scope",
"SessionProperty",
"OR",
"Transaction",
"NOT",
"AuthLevel",
"AuthenticateToService"
],
"creationDate": 1637661939155,
"lastModifiedBy": "id=dsameuser,ou=user,dc=openam,dc=forgerock,dc=org",
"lastModifiedDate": 1637661939155,
"actions": {
"HEAD": true,
"DELETE": true,
"POST": true,
"GET": true,
"OPTIONS": true,
"PUT": true,
"PATCH": true
},
"resources": [
"://:*/",
"://:/?"
],
"realm": "/"
},
{
"resourceComparator": null,
"saveIndex": null,
"searchIndex": null,
"applicationType": "sunAMDelegationService",
"entitlementCombiner": "DenyOverride",
"subjects": [
"OR",
"AND",
"AuthenticatedUsers",
"NOT",
"Identity"
],
"attributeNames": [],
"editable": true,
"createdBy": "id=dsameuser,ou=user,dc=openam,dc=forgerock,dc=org",
"name": "sunAMDelegationService",
"description": null,
"conditions": [],
"creationDate": 1637661944233,
"lastModifiedBy": "id=dsameuser,ou=user,dc=openam,dc=forgerock,dc=org",
"lastModifiedDate": 1637661944233,
"actions": {
"READ": true,
"MODIFY": true,
"DELEGATE": true
},
"resources": [
"sms://:/",
"sms://:*/?"
],
"realm": "/"
},
{
"resourceComparator": null,
"saveIndex": null,
"searchIndex": null,
"applicationType": "iPlanetAMWebAgentService",
"entitlementCombiner": "DenyOverride",
"subjects": [
"AuthenticatedUsers",
"NOT",
"Identity",
"OR",
"AND",
"NONE",
"JwtClaim"
],
"attributeNames": [],
"editable": true,
"createdBy": "id=dsameuser,ou=user,dc=openam,dc=forgerock,dc=org",
"name": "oauth2Scopes",
"description": "The built-in Application used by the OAuth2 scope authorization process.",
"conditions": [
"Script",
"AMIdentityMembership",
"IPv6",
"IPv4",
"SimpleTime",
"LEAuthLevel",
"LDAPFilter",
"AuthScheme",
"Session",
"AND",
"AuthenticateToRealm",
"ResourceEnvIP",
"OAuth2Scope",
"SessionProperty",
"OR",
"Transaction",
"NOT",
"AuthLevel",
"AuthenticateToService"
],
"creationDate": 1637661944239,
"lastModifiedBy": "id=dsameuser,ou=user,dc=openam,dc=forgerock,dc=org",
"lastModifiedDate": 1637661944239,
"actions": {
"GRANT": true
},
"resources": [
"://:*/",
"://:/?",
"*"
],
"realm": "/"
}
],
"resultCount": 3,
"pagedResultsCookie": null,
"totalPagedResultsPolicy": "NONE",
"totalPagedResults": -1,
"remainingPagedResults": 0
}Additional query strings can be specified to alter the returned results. For more information, see Query.
Supported _queryFilter Fields and Operators
| Field | Supported Operators |
|---|---|
|
Equals ( |
|
Equals ( |
|
Equals ( |
|
Equals ( |
|
Equals ( |
|
Equals ( |
(1) The implementation of eq for this date field does not use regular expression pattern matching.
Read a policy set
To read a specific policy set in a realm, send an HTTP GET request to the
/json/realms/root/realms/realm/applications endpoint, specifying the policy set name in the URL.
The <session-cookie-name> header is required and should contain the SSO token of an administrative user,
such as amAdmin, who has access to perform the operation.
$ curl \
--header "<session-cookie-name>: AQIC5…" \
--header "Accept-API-Version: resource=1.0" \
'https://<tenant-name>.forgeblocks.com/am/json/realms/root/applications/mypolicyset'
{
"creationDate":1431360678810,
"lastModifiedDate":1431360678810,
"conditions":[
"AuthenticateToService",
"AuthScheme",
"IPv6",
"SimpleTime",
"OAuth2Scope",
"IPv4",
"AuthenticateToRealm",
"OR",
"AMIdentityMembership",
"LDAPFilter",
"SessionProperty",
"AuthLevel",
"LEAuthLevel",
"Session",
"NOT",
"AND",
"ResourceEnvIP"
],
"applicationType":"iPlanetAMWebAgentService",
"subjects":[
"JwtClaim",
"AuthenticatedUsers",
"Identity",
"NOT",
"AND",
"OR"
],
"entitlementCombiner":"DenyOverride",
"saveIndex":null,
"searchIndex":null,
"resourceComparator":"com.sun.identity.entitlement.URLResourceName",
"resourceTypeUuids":[
"12345a67-8f0b-123c-45de-6fab78cd01e2"
],
"attributeNames":[
],
"editable":true,
"createdBy":"id=amadmin,ou=user,dc=openam,dc=forgerock,dc=org",
"lastModifiedBy":"id=amadmin,ou=user,dc=openam,dc=forgerock,dc=org",
"description":"My example policy set.",
"realm":"/",
"name":"mypolicyset"
}You can use the query string parameters _prettyPrint=true to make the output easier to read,
and _fields=field-name[,field-name…] to limit the fields returned in the output.
Create a policy set
To create a policy set in a realm, send an HTTP POST request to the /json/realms/root/realms/realm/applications endpoint, with _action=create. Include a JSON representation of the policy set in the POST data.
The <session-cookie-name> header is required and should contain the SSO token of an administrative user,
such as amAdmin, who has access to perform the operation.
Do not use special characters in resource type, policy, or policy set names (for example, "my+resource+type"). If you
include special characters, AM returns a 400 Bad Request error. This includes the following special characters:
double quotes ("), plus sign (+), comma (,), less than (<), equals (=), greater than (>),
backslash (\), forward slash (/), semicolon (;), and null (\u0000).
$ curl \
--request POST \
--header "Content-Type: application/json" \
--header "<session-cookie-name>: AQIC5…" \
--header "Accept-API-Version: resource=2.1" \
--data '{
"name":"mypolicyset",
"resourceTypeUuids":[
"12345a67-8f0b-123c-45de-6fab78cd01e2"
],
"realm":"/",
"conditions":[
"AND",
"OR",
"NOT",
"AMIdentityMembership",
"AuthLevel",
"AuthScheme",
"AuthenticateToRealm",
"AuthenticateToService",
"IPv4",
"IPv6",
"LDAPFilter",
"LEAuthLevel",
"OAuth2Scope",
"ResourceEnvIP",
"Session",
"SessionProperty",
"SimpleTime"
],
"applicationType":"iPlanetAMWebAgentService",
"description":"My example policy set.",
"resourceComparator":"com.sun.identity.entitlement.URLResourceName",
"subjects":[
"AND",
"OR",
"NOT",
"AuthenticatedUsers",
"Identity",
"JwtClaim"
],
"entitlementCombiner":"DenyOverride",
"saveIndex":null,
"searchIndex":null,
"attributeNames":[
]
}' \
'https://<tenant-name>.forgeblocks.com/am/json/realms/root/applications/?_action=create'
{
"creationDate":1431360678810,
"lastModifiedDate":1431360678810,
"conditions":[
"AuthenticateToService",
"AuthScheme",
"IPv6",
"SimpleTime",
"OAuth2Scope",
"IPv4",
"AuthenticateToRealm",
"OR",
"AMIdentityMembership",
"LDAPFilter",
"SessionProperty",
"AuthLevel",
"LEAuthLevel",
"Session",
"NOT",
"AND",
"ResourceEnvIP"
],
"applicationType":"iPlanetAMWebAgentService",
"subjects":[
"JwtClaim",
"AuthenticatedUsers",
"Identity",
"NOT",
"AND",
"OR"
],
"entitlementCombiner":"DenyOverride",
"saveIndex":null,
"searchIndex":null,
"resourceComparator":"com.sun.identity.entitlement.URLResourceName",
"resourceTypeUuids":[
"12345a67-8f0b-123c-45de-6fab78cd01e2"
],
"attributeNames":[],
"editable":true,
"createdBy":"id=amadmin,ou=user,dc=openam,dc=forgerock,dc=org",
"lastModifiedBy":"id=amadmin,ou=user,dc=openam,dc=forgerock,dc=org",
"description":"My example policy set.",
"realm":"/",
"name":"mypolicyset"
}You can use the query string parameters _prettyPrint=true to make the output easier to read,
and _fields=field-name[,field-name…] to limit the fields returned in the output.
Update a policy set
To update a specific policy set in a realm, send an HTTP PUT request to the /json/realms/root/realms/realm/applications endpoint, specifying the policy set name in the URL.
Include a JSON representation of the updated policy set in the PUT data.
The <session-cookie-name> header is required and should contain the SSO token of an administrative user,
such as amAdmin, who has access to perform the operation.
Do not use special characters in resource type, policy, or policy set names (for example, "my+resource+type"). If you
include special characters, AM returns a 400 Bad Request error. This includes the following special characters:
double quotes ("), plus sign (+), comma (,), less than (<), equals (=), greater than (>),
backslash (\), forward slash (/), semicolon (;), and null (\u0000).
$ curl \
--request PUT \
--header "<session-cookie-name>: AQIC5…" \
--header "Content-Type: application/json" \
--header "Accept-API-Version: resource=2.1" \
--data '{
"name":"myupdatedpolicyset",
"description":"My updated policy set - new name and fewer allowable conditions/subjects.",
"conditions":[
"NOT",
"SimpleTime"
],
"subjects":[
"AND",
"OR",
"NOT",
"AuthenticatedUsers",
"Identity"
],
"applicationType":"iPlanetAMWebAgentService",
"entitlementCombiner":"DenyOverride",
"resourceTypeUuids":[
"76656a38-5f8e-401b-83aa-4ccb74ce88d2"
]
}' \
'https://<tenant-name>.forgeblocks.com/am/json/realms/root/applications/mypolicyset'
{
"creationDate":1431362370739,
"lastModifiedDate":1431362390817,
"conditions":[
"NOT",
"SimpleTime"
],
"resourceComparator":"com.sun.identity.entitlement.URLResourceName",
"resourceTypeUuids":[
"76656a38-5f8e-401b-83aa-4ccb74ce88d2"
],
"createdBy":"id=amadmin,ou=user,dc=openam,dc=forgerock,dc=org",
"lastModifiedBy":"id=amadmin,ou=user,dc=openam,dc=forgerock,dc=org",
"applicationType":"iPlanetAMWebAgentService",
"subjects":[
"AuthenticatedUsers",
"Identity",
"NOT",
"AND",
"OR"
],
"entitlementCombiner":"DenyOverride",
"saveIndex":null,
"searchIndex":null,
"attributeNames":[
],
"editable":true,
"description":"My updated policy set - new name and fewer allowable conditions/subjects.",
"realm":"/",
"name":"myupdatedpolicyset"
}You can use the query string parameters _prettyPrint=true to make the output easier to read,
and _fields=field-name[,field-name…] to limit the fields returned in the output.
Delete a policy set
To delete a specific policy set in a realm, send an HTTP DELETE request to the /json/realms/root/realms/realm/applications
endpoint, specifying the policy set name in the URL.
The <session-cookie-name> header is required and should contain the SSO token of an administrative user,
such as amAdmin, who has access to perform the operation.
$ curl \
--request DELETE \
--header "<session-cookie-name>: AQIC5…" \
--header "Accept-API-Version: resource=2.1" \
'https://<tenant-name>.forgeblocks.com/am/json/realms/root/applications/myupdatedpolicyset'Policy set application types over REST
Application types act as templates for policy sets, and define how to compare resources and index policies.
AM provides a default application type that represents web resources called iPlanetAMWebAgentService.
AM web and Java agents use a default policy set that is based on this type,
which is also called iPlanetAMWebAgentService.
AM provides the applicationtypes REST endpoint for the following:
Applications types are server-wide, and do not differ by realm.
Hence the URI for the application types API does not contain a realm component, but is /json/applicationtypes.
Application type resources are represented in JSON and take the following form.
Application type resources are built from standard JSON objects and values
(strings, numbers, objects, arrays, true, false, and null).
Example
{
"name": "iPlanetAMWebAgentService",
"actions": {
"POST": true,
"PATCH": true,
"GET": true,
"DELETE": true,
"OPTIONS": true,
"PUT": true,
"HEAD": true
},
"resourceComparator": "com.sun.identity.entitlement.URLResourceName",
"saveIndex": "org.forgerock.openam.entitlement.indextree.TreeSaveIndex",
"searchIndex": "org.forgerock.openam.entitlement.indextree.TreeSearchIndex",
"applicationClassName": "com.sun.identity.entitlement.Application"
}The values for the fields shown in the description are explained below:
"name"-
The name provided for the application type.
"actions"-
Set of string action names, each set to a boolean indicating whether the action is allowed.
"resourceComparator"-
Class name of the resource comparator implementation used in the context of this application type.
The following implementations are available:
"com.sun.identity.entitlement.ExactMatchResourceName"
"com.sun.identity.entitlement.PrefixResourceName"
"com.sun.identity.entitlement.RegExResourceName"
"com.sun.identity.entitlement.URLResourceName" "saveIndex"-
Class name of the implementation for creating indexes for resource names, such as
"com.sun.identity.entitlement.util.ResourceNameIndexGenerator", for URL resource names. "searchIndex"-
Class name of the implementation for searching indexes for resource names, such as
"com.sun.identity.entitlement.util.ResourceNameSplitter", for URL resource names. "applicationClassName"-
Class name of the application type implementation, such as
"com.sun.identity.entitlement.Application".
Query application types
To list all application types, perform an HTTP GET to the /json/applicationtypes endpoint,
with a _queryFilter parameter set to true.
The <session-cookie-name> header is required and should contain the SSO token of an administrative user,
such as amAdmin, who has access to perform the operation.
$ curl \
--header "<session-cookie-name>: AQIC5…" \
--header "Accept-API-Version: resource=1.0" \
'https://<tenant-name>.forgeblocks.com/am/json/realms/root/applicationtypes?_queryFilter=true'
{
"result" : [ … application types … ],
"resultCount" : 8,
"pagedResultsCookie" : null,
"remainingPagedResults" : -1
}Additional query strings can be specified to alter the returned results. For more information, see Query.
Read a specific application type
To read an individual application type, perform an HTTP GET to the /json/applicationtypes endpoint,
and specify the application type name in the URL.
The <session-cookie-name> header is required and should contain the SSO token of an administrative user,
such as amAdmin, who has access to perform the operation.
$ curl \
--header "<session-cookie-name>: AQIC5…" \
--header "Accept-API-Version: resource=1.0" \
'https://<tenant-name>.forgeblocks.com/am/json/realms/root/applicationtypes/iPlanetAMWebAgentService'
{
"name": "iPlanetAMWebAgentService",
"actions": {
"POST": true,
"PATCH": true,
"GET": true,
"DELETE": true,
"OPTIONS": true,
"PUT": true,
"HEAD": true
},
"resourceComparator": "com.sun.identity.entitlement.URLResourceName",
"saveIndex": "org.forgerock.openam.entitlement.indextree.TreeSaveIndex",
"searchIndex": "org.forgerock.openam.entitlement.indextree.TreeSearchIndex",
"applicationClassName": "com.sun.identity.entitlement.Application"
}Request authorization from AM
Once you have configured AM to determine whether to grant or deny access based on the policies you created, you must configure your policy enforcement points (PEP) to use AM.
The ForgeRock Identity Platform provides the following PEPs:
-
Web agents and Java agents, which are add-on components installed on the web server or container serving your applications. They are tightly integrated with AM, and serve exclusively as policy enforcement points.
For more information, see the ForgeRock web agents documentation, or the ForgeRock Java agents documentation.
-
ForgeRock Identity Gateway, which is a high-performance reverse proxy server that can also function as a policy enforcement point.
For more information, see the ForgeRock Identity Gateway Getting started guide.
The ForgeRock Identity Platform PEP’s intercept inbound client requests to access a resource in your web site or application. Then, based on internal rules, they may defer the request to AM for policy evaluation. Since they are tightly integrated with AM, you do not need to add additional code to request policy evaluation or manage advices.
We recommend that you use the ForgeRock Identity Platform PEP’s. However, you can code your own and make REST calls to AM to request policy evaluation.
Related information: Request policy decisions over REST
Request policy decisions over REST
You can request policy decisions from AM by using the REST API described in this page. AM evaluates requests based on the context and the policies configured, and returns decisions that indicate what actions are allowed or denied, as well as any attributes or advice for the resources specified.
|
This section does not apply to OAuth 2.0 policies. |
AM provides the /json/realms/root/policies endpoint to request policy evaluation.
When making a REST API call, specify the realm in the path component of the endpoint.
Before making a REST API call to request manage a policy component, make sure that you have:
-
Authenticated successfully to AM as a user with sufficient privileges to make the REST API call.
-
Obtained the session token returned after successful authentication.
When making the REST API call, pass the session token in the HTTP header. For more information about the AM session token and its use in REST API calls, see Using the session token after authentication.
To request decisions for specific resources, see Request policy decisions for specific resources.
To request decisions for a resource and all resources beneath it, see Request policy decisions for a tree of resources.
Request policy decisions for specific resources
This section shows how you can request a policy decision over REST for specific resources.
When making a REST API call, specify the realm in the path component of the endpoint.
To request policy decisions for specific resources,
perform an HTTP POST using the evaluation action to the appropriate path under the URI where AM is deployed,
/json{/realm/root}/policies?_action=evaluate.
The payload for the HTTP POST is a JSON object that specifies at least the resources, and takes the following form.
{
"resources": [
"resource1",
"resource2",
...,
"resourceN"
],
"application": "defaults to iPlanetAMWebAgentService if not specified",
"subject": {
"ssoToken": "SSO token ID string",
"jwt": "JSON Web Token string",
"claims": {
"key": "value",
...
}
},
"environment": {
"optional key1": [
"value",
"another value",
...
],
"optional key2": [
"value",
"another value",
...
],
...
}
}The values for the fields shown above are explained below:
"resources"-
This required field specifies the list of resources for which to return decisions.
For example, when using the default policy set,
"iPlanetAMWebAgentService", you can request decisions for resource URLs.{ "resources": [ "http://www.example.com/index.html", "http://www.example.com/do?action=run" ] } "application"-
This field holds the name of the policy set, and defaults to
"iPlanetAMWebAgentService"if not specified.For more on policy sets, see Policy sets over REST.
"subject"-
This optional field holds an object that represents the subject. You can specify one or more of the following keys. If you specify multiple keys, the subject can have multiple associated principals, and you can use subject conditions corresponding to any type in the request.
"ssoToken"-
The value is the SSO token ID string for the subject, returned for example on successful authentication as described in Authenticate using REST.
You can use an OpenID Connect ID token if the client that the token has been issued for is authorized to use ID tokens as session tokens. For more information, see Using ID Tokens as Session Tokens.
"jwt"-
The value is a JWT string.
"claims"-
The value is an object (map) of JWT claims to their values. If you do not specify the subject, AM uses the SSO token ID of the subject making the request.
"environment"-
This optional field holds a map of keys to lists of values.
If you do not specify the environment, the default is an empty map.
The example below requests policy decisions for two URL resources.
The <session-cookie-name> header sets the SSO token for a user who has access to perform the operation.
$ curl \
--request POST \
--header "Content-Type: application/json" \
--header "Accept-API-Version: resource=2.1" \
--header "<session-cookie-name>: AQIC5…" \
--data '{
"resources":[
"http://www.example.com/index.html",
"http://www.example.com/do?action=run"
],
"application":"iPlanetAMWebAgentService"
}' \
"https://<tenant-name>.forgeblocks.com/am/json/realms/root/policies?_action=evaluate"
[
{
"resource":"http://www.example.com/do?action=run",
"actions":{
},
"attributes":{
},
"advices":{
"AuthLevelConditionAdvice":[
"3"
]
}
},
{
"resource":"http://www.example.com/index.html",
"actions":{
"POST":false,
"GET":true
},
"attributes":{
"cn":[
"demo"
]
},
"advices":{
}
}
]In the JSON list of decisions returned for each resource, AM includes these fields.
"resource"-
A resource specified in the request.
The decisions returned are not guaranteed to be in the same order as the resources were requested.
"actions"-
A map of action name keys to Boolean values that indicate whether the action is allowed (
true) or denied (false) for the specified resource.In the example, for resource
http://www.example.com:80/index.htmlHTTP GET is allowed, whereas HTTP POST is denied. "attributes"-
A map of attribute names to their values, if any response attributes are returned according to applicable policies.
In the example, the policy that applies to
http://www.example.com:80/index.htmlcauses that the value of the subject’s "cn" profile attribute to be returned. "advices"-
A map of advice names to their values, if any advice is returned according to applicable policies.
The
"advices"field can provide hints regarding what AM needs to take the authorization decision.In the example, the policy that applies to
http://www.example.com:80/do?action=runrequests that the subject be authenticated at an authentication level of at least 3.{ "advices": { "AuthLevelConditionAdvice": [ "3" ] } }See Policy decision advice for details.
You can use the query string parameters _prettyPrint=true to make the output easier to read,
and _fields=field-name[,field-name…] to limit the fields returned in the output.
Policy decision advice
When AM returns a policy decision, the JSON for the decision can include an "advices" field. This field contains hints for the policy enforcement point.
{
"advices": {
"type": [
"advice"
]
}
}The "advices" returned depend on policy conditions. For more information about AM policy conditions, see Policies over REST.
This section shows examples of the different types of policy decision advice and the conditions that cause AM to return the advice.
"AuthLevel" and "LEAuthLevel" condition failures can result in advice
showing the expected or maximum possible authentication level.
For example, failure against the following condition:
{
"type": "AuthLevel",
"authLevel": 2
}Leads to this advice:
{
"AuthLevelConditionAdvice": [
"2"
]
}An "AuthenticateToRealm" condition failure can result in advice
showing the name of the realm to which authentication is required.
For example, failure against the following condition:
{
"type": "AuthenticateToRealm",
"authenticateToRealm": "MyRealm"
}Leads to this advice:
{
"AuthenticateToRealmConditionAdvice": [
"/myRealm"
]
}An "AuthenticateToService" condition failure can result in advice
showing the name of the required authentication chain.
For example, failure against the following condition:
{
"type": "AuthenticateToService",
"authenticateToService": "MyAuthnChain"
}Leads to this advice:
{
"AuthenticateToServiceConditionAdvice": [
"MyAuthnChain"
]
}A "ResourceEnvIP" condition failure can result in advice that indicates corrective action to be taken.
The advice varies, depending on what the condition tests.
For example, failure against the following condition:
{
"type": "ResourceEnvIP",
"resourceEnvIPConditionValue": [
"IF IP=[127.0.0.12] THEN authlevel=4"
]
}Leads to this advice:
{
"AuthLevelConditionAdvice": [
"4"
]
}Failure against a different type of "ResourceEnvIP" condition such as the following:
{
"type": "ResourceEnvIP",
"resourceEnvIPConditionValue": [
"IF IP=[127.0.0.11] THEN service=MyAuthnChain"
]
}Leads to this advice:
{
"AuthenticateToServiceConditionAdvice": [
"MyAuthnChain"
]
}A "Session" condition failure can result in advice showing that access has been denied
because the user’s session has been active longer than allowed by the condition.
The advice will also show if the user’s session was terminated and reauthentication is required.
For example, failure against the following condition:
{
"type": "Session",
"maxSessionTime": "10",
"terminateSession": false
}Leads to this advice:
{
"SessionConditionAdvice": [
"deny"
]
}When policy evaluation denials occur against the following conditions, AM does not return any advice:
-
IPv4 -
IPv6 -
LDAPFilter -
OAuth2Scope -
SessionProperty -
SimpleTime
When policy evaluation is requested for a nonexistent or inactive subject, AM returns an HTTP 200 code and a response that contains no actions or advice. Access to the resource is denied.
Request policy decisions for a tree of resources
This section shows how you can request policy decisions over REST for a resource and all other resources in the subtree beneath it.
When making a REST API call, specify the realm in the path component of the endpoint.
To request policy decisions for a tree of resources,
perform an HTTP POST using the evaluation action to the appropriate path under the URI where AM is deployed,
for example /json/realms/root/realms/myRealm/policies?_action=evaluateTree.
The payload for the HTTP POST is a JSON object that specifies at least the root resource, and takes the following form.
{
"resource": "resource string",
"application": "defaults to iPlanetAMWebAgentService if not specified",
"subject": {
"ssoToken": "SSO token ID string",
"jwt": "JSON Web Token string",
"claims": {
"key": "value",
...
}
},
"environment": {
"optional key1": [
"value",
"another value",
...
],
"optional key2": [
"value",
"another value",
...
],
...
}
}The values for the fields shown above are explained below:
"resource"-
This required field specifies the root resource for the decisions to return.
For example, when using the default policy set,
"iPlanetAMWebAgentService", you can request decisions for resource URLs.{ "resource": "http://www.example.com/" } "application"-
This field holds the name of the policy set, and defaults to
"iPlanetAMWebAgentService"if not specified.For more on policy sets, see Policy sets over REST.
"subject"-
This optional field holds an object that represents the subject. You can specify one or more of the following keys. If you specify multiple keys, the subject can have multiple associated principals, and you can use subject conditions corresponding to any type in the request.
"ssoToken"-
The value is the SSO token ID string for the subject, returned for example on successful authentication as described in Authenticate using REST.
"jwt"-
The value is a JWT string.
"claims"-
The value is an object (map) of JWT claims to their values. If you do not specify the subject, AM uses the SSO token ID of the subject making the request.
"environment"-
This optional field holds a map of keys to lists of values.
If you do not specify the environment, the default is an empty map.
The example below requests policy decisions for http://www.example.com/.
The <session-cookie-name> header sets the SSO token for a user who has access to perform the operation,
and the subject takes the SSO token of the user who wants to access a resource.
$ curl \
--request POST \
--header "Content-Type: application/json" \
--header "<session-cookie-name>: AQIC5…NDU1*" \
--header "Accept-API-Version: resource=1.0" \
--data '{
"resource": "http://www.example.com/",
"subject": { "ssoToken": "AQIC5…zE4*" }
}' \
"https://<tenant-name>.forgeblocks.com/am/json/realms/root/policies?_action=evaluateTree"
[
{
"resource":"http://www.example.com/",
"actions":{
"GET":true,
"OPTIONS":true,
"HEAD":true
},
"attributes":{
},
"advices":{
}
},
{
"resource":"http://www.example.com/",
"actions":{
"POST":false,
"PATCH":false,
"GET":true,
"DELETE":true,
"OPTIONS":true,
"HEAD":true,
"PUT":true
},
"attributes":{
"myStaticAttr":[
"myStaticValue"
]
},
"advices":{
}
},
{
"resource":"http://www.example.com/?*",
"actions":{
"POST":false,
"PATCH":false,
"GET":false,
"DELETE":false,
"OPTIONS":true,
"HEAD":false,
"PUT":false
},
"attributes":{
},
"advices":{
"AuthLevelConditionAdvice":[
"3"
]
}
}
]Notice that AM returns decisions not only for the specified resource, but also for matching resource names in the tree whose root is the specified resource.
In the JSON list of decisions returned for each resource, AM includes these fields.
"resource"-
A resource name whose root is the resource specified in the request.
The decisions returned are not guaranteed to be in the same order as the resources were requested.
"actions"-
A map of action name keys to Boolean values that indicate whether the action is allowed (
true) or denied (false) for the specified resource.In the example, for matching resources with a query string only HTTP OPTIONS is allowed according to the policies configured.
"attributes"-
A map of attribute names to their values, if any response attributes are returned according to applicable policies.
In the example, the policy that applies to
http://www.example.com:80/*causes a static attribute to be returned. "advices"-
A map of advice names to their values, if any advice is returned according to applicable policies.
The
"advices"field can provide hints regarding what AM needs to take the authorization decision.In the example, the policy that applies to resources with a query string requests that the subject be authenticated at an authentication level of at least 3.
Notice that with the
"advices"field present, no"advices"appear in the JSON response.{ "advices": { "AuthLevelConditionAdvice": [ "3" ] } }
You can use the query string parameters _prettyPrint=true to make the output easier to read,
and _fields=field-name[,field-name…] to limit the fields returned in the output.
Transactional authorization
Transactional authorization improves security by requiring a user to perform additional actions when trying to access a resource protected by an AM policy. For example, they must re-authenticate, or respond to a push notification on their mobile device.
Performing the additional action successfully grants access to the protected resource, but only once. Additional attempts to access the resource will require the user to perform the configured actions again.
Transactional authorization is implemented as a environment condition type that can be added to authorization policies.
Example
The transactional authorization environment condition can be combined in policies with the other conditions. For example, only requiring a push notification response when access is attempted to the employees subrealm, but outside usual working hours, as shown below:
Related information: Authorization and policy decisions
How does transactional authorization work?
The following diagram describes the sequence of events that occur when accessing a resource that is protected by a REST application, and an AM policy containing a transactional environment condition:
The sequence of events for a transaction authorization is as follows:
-
An authenticated user attempts to access a resource that is protected by an AM server.
-
The resource server contacts AM to evaluate the policies that apply.
The resource server can be protected with ForgeRock’s Web or Java Agents, which support transactional authorization natively, or a custom application that uses ForgeRock’s REST API as per the diagram to manage the transactional authorization.
-
As the policy contains a transaction environment condition, AM creates a transaction token in the Core Token Service (CTS) store. The initial transaction token state is set to
CREATED.The transaction token contains information about the policy evaluation, including the:
-
Realm
-
Resource
-
Subject
-
Audit tracking ID
-
Authentication method
To protect against tampering, AM verifies that these details do not change and match those in the incoming requests for the duration of the transaction.
The transaction token has a time-to-live (default 180 seconds) defined in the Transaction Authentication Service. If the transaction is not completed in this time, the token is deleted, and the flow will need to be restarted. Alter the default if the transaction includes authentication actions that take more time to complete. For example, using HOTP authentication for a one-time password over email.
The time-to-live can be configured per realm. See Transaction Authentication service.
-
-
In the JSON response to the policy evaluation request, AM returns the transaction ID—the unique ID of the newly created transaction token—in the
TransactionConditionAdvicearray in theadvicesobject:{ "resource": "http://www.example.com:8000/index.html", "actions": {}, "attributes": {}, "advices": { "TransactionConditionAdvice": [ "7b8bfd4c-60fe-4271-928d-d09b94496f84" ] }, "ttl": 0 } -
As the JSON response to the evaluation does not grant any actions but does contain advices, the REST application on the resource server extracts the transaction ID and returns it to the authentication service to commence the authentication.
The transaction ID is included in the
TransactionConditionAdviceattribute value pair in the composite advice query parameters sent as part of the request for actions.ForgeRock web and Java agents manage this interaction natively. For information on using the REST API to handle
adviceselements in policy evaluations, see Request policy decisions over REST. -
AM extracts the transaction ID from the composite advice, verifies the corresponding transaction token, and changes the state to
IN_PROGRESS.If the transaction ID is not in the expected state or does not exist, a
401 Unauthorizederror is returned. For example:{ "code": 401, "reason": "Unauthorized", "message": "Unable to read transaction.", "detail": { "errorCode": "128" } } -
AM responds with the callbacks necessary to satisfy any environment conditions.
The advices returned by transaction environment conditions have the lowest precedence when compared to the other condition advices. End users will have to complete the non-transactional condition advices before they can complete the transactional condition advices.
-
The REST application renders the callbacks and presents them to the user.
-
The user completes the required actions.
For example, authenticates to the specified tree, or responds to the push notification on their registered mobile device.
If the user is unable to complete the actions, AM returns an HTTP 200 message and the user is redirected to the protected resource. Policy evaluation will fail since the transactional authorization process has failed.
-
The REST app completes the callbacks and returns the result to AM.
-
AM verifies the transaction token, and changes the state to
COMPLETED. -
With the transaction now complete, AM returns the original token.
Note that the authentication performed as part of an authorization flow does not behave exactly the same as a standard authentication. The differences are:
-
The user’s original session is not upgraded or altered in any way.
-
Failing the authentication during the authorization flow does not increment account lockout counters.
-
-
The web or Java agent or custom application on the resource server can reevaluate the policies applying to the protected resources again, but includes the ID of the completed transaction as a value in the
TxIdarray in theenvironmentobject:{ "resources" : ["http://www.example.com:8000/index.html"], "application" : "iPlanetAMWebAgentService", "subject" : { "ssoToken" : "AQIC5w....*AJTMQAA*" }, "environment": { "TxId": ["7b8bfd4c-60fe-4271-928d-d09b94496f84"] } } -
AM verifies the transaction was authorized and that the transaction token is in the
COMPLETEDstate. -
If the transaction was completed successfully, authorization continues.
The transaction token is marked for deletion, so that it cannot be used to grant more than a single access.
-
As the authentication required to complete the transaction was successful, AM returns the result of the policy reevaluation.
For example, the following response grants the
POSTandGETactions to the resourcehttp://www.example.com:8000/index.html:{ "resource": "http://www.example.com:8000/index.html", "actions": { "POST": true, "GET": true }, "attributes": {}, "advices": {}, "ttl": 0 }Successful transactional authorization responses set the time-to-live (
ttl) value to zero to ensure that the policy decision is not cached and cannot be used more than once.ForgeRock agents prior to version 5 do not support a time-to-live value of zero and cannot be used for transactional authorization.
-
The user is able to access the protected resource once.
Additional attempts to access a resource protected with a policy containing a transactional environment condition require a new transaction to be completed.
To configure transactional authorization, first configure the trees you need for session upgrade, then configure your policies.
Dynamic OAuth 2.0 authorization
You can configure AM to grant scopes statically or dynamically:
-
Statically (Default). You configure several OAuth 2.0 clients with different subsets of scopes and resource owners are redirected to a specific client depending on the scopes required. As long as the resource owner can authenticate and the client can deliver the same or a subset of the requested scopes, AM issues the token with the scopes requested. Therefore, two different users requesting scopes A and B to the same client will always receive scopes A and B.
-
Dynamically. You configure an OAuth 2.0 client with a comprehensive list of scopes and resource owners authenticate against it. When AM receives a request for scopes, AM’s Authorization Service grants or denies access scopes dynamically by evaluating authorization policies at runtime. Therefore, two different users requesting scopes A and B to the same client can receive different scopes based on policy conditions.
Example use case
Consider the case of a company deployment that supports custom OAuth 2.0 clients and internal applications.
The use of the internal application is bound by the terms and conditions specified by the company;
therefore, the user does not need to consent to provide with their user profile information
(for example, the profile scope).
To provide the internal application with the user profile automatically,
the administrator creates a policy that grants the profile scope to all requests made
by authenticated users using a particular OAuth 2.0 client.
How does dynamic OAuth 2.0 authorization work?
When issuing access tokens, AM deduces consent status based on a policy result:
an allow policy result means consent is granted, while a deny result means it is denied.
If AM cannot deduce consent using a policy, for example, because none is defined, it is down to the resource owner to decide whether to grant consent. Note that this is only possible in flows where the resource owner interacts with the consent screen. If the resource owner cannot interact with the consent screen, for example, during the ROPC Grant flow, AM denies the scope.
Just like when granting scopes statically, AM only evaluates default scopes configured in the OAuth 2.0 client profile when no scope is requested. AM follows the same rules to deduce consent for both default and requested scopes.
When issuing refresh tokens, AM issues any scope that was previously consented to either by policy or by the resource owner on the consent screen, unless it is explicitly denied by a policy.
To understand which flows are interactive and which ones are not, see the examples in OAuth 2.0 grant flows and OpenID Connect grant flows.
OAuth 2.0 authorization is implemented by using the OAuth2 Scope resource type,
which must always be configured in the Default OAuth2 Scopes policy set.
Related information: Policies.
Writing policies for OAuth 2.0 may not be straightforward if your environment requires complex conditions. The easiest way to test if your OAuth 2.0 policies are granting or denying the scopes you expect before setting them in production is to configure AM as an OAuth 2.0 client and authorization provider and request some tokens.
Configure Access Management for the examples
-
Configure an instance of the OAuth 2.0 provider.
Ensure that:
-
Use Policy Engine for Scope Decisions is enabled.
-
Response Type Plugins is configured for
tokenandid_token. -
Grant Types is configured for
Resource Owner Password CredentialsandImplicit.
-
-
Go to Realms > Realm Name > Applications > OAuth 2.0 and add a client.
Configure the client properties as follows:
-
Client ID:
myClient -
Client secret:
forgerock -
Redirection URIs:
https://www.example.com:443/callback -
Scope(s):
profileemailopenid -
Grant Types:
Resource Owner Password Credentials
-
-
Go to Realms > Realm Name > Authorization > Policy Sets, and select Default OAuth2 Scopes Policy Set.
-
Create a new policy as follows:
-
Name:
myOAuth2Policy -
Resource Type:
OAuth2 Scope -
Resources: Select the
*resource pattern and replace it withemail.Once the policy is created, you will see the Summary tab.
-
-
On the Actions tab, add the
GRANTaction, and set the default state toAllow. Save your changes. -
On the Subjects tab, specify the subject condition
All of…Authenticated Users. Save your changes. -
If the
demouser is not present in your environment, create it by performing the following step:-
Go to Realms > Realm Name > Identities, and add a new user called
demowith passwordCh4ng31t.
-
Test OAuth 2.0 policies in a non-interactive flow
This procedure shows how to test OAuth 2.0 policies with the ROPC Grant flow. In this flow, the resource owner does not interact with the consent screen and cannot therefore grant scopes.
-
Request an access token from AM by specifying:
-
The client name,
myClient, and its password,forgerock. -
The resource owner password credentials grant type,
password. -
The user and password to authenticate with,
demoandCh4ng31t. -
The requested scopes,
emailandprofile.
$ curl --request POST \ --data "grant_type=password" \ --data "username=demo" \ --data "password=Ch4ng31t" \ --data "scope=profile email" \ --data "client_id=myClient" \ --data "client_secret=forgerock" \ "https://<tenant-name>.forgeblocks.com/am/oauth2/realms/root/realms/alpha/access_token" -
-
Review the JSON response.
It should be similar to the following:
{ "access_token":"B78LPVHaycIrObh12Qps0n9ynYM", "scope":"email", "token_type":"Bearer", "expires_in":3599 }Note how the requested scopes were
emailandprofile, but the scope granted wasemail, which matches theGRANT=Allowaction defined in the policy.
Test OAuth 2.0 policies in an interactive OpenID Connect flow
This procedure shows how to test OAuth 2.0 policies with the OpenID Connect Implicit Grant flow. In this flow, the end user can interact with the consent screen, and can therefore grant scopes.
-
In a web browser, make a call to the
oauth2/authorizeendpoint with the following parameters:-
nonce=123 -
state=456 -
scope=openid+email+profile -
response_type=id_token -
client_id=myClient -
redirect_uri=https://www.example.com:443/callback
For example:
https://<tenant-name>.forgeblocks.com/am/oauth2/authorize?nonce=123&state=456&scope=openid+email+profile&response_type=id_token&client_id=myClient&redirect_uri=https://www.example.com:443/callback. You will be prompted to log in to AM. -
-
Log in as the
demouser.You will be prompted to provide consent for the
profilescope:
Figure 12. Requesting Consent for the Profile ScopeNotice that you are not prompted to provide consent for the
emailscope. -
Allow the flow to continue.
-
Review the URL of the browser.
It should show something similar to:
http://example.com/#scope=openid%20profile%20email&id_token=eyJ0eXJKV1Q…8WK1eg&state=456.Notice that the
emailscope has been granted automatically.If the authorization policy had been configured as
GRANT=Deny, you still would have not seen theemailscope in the consent page, but the scope would not appear in the URL of the browser.
Scripted policy conditions
You can use scripts to tailor the actions that AM takes as part of policy evaluation.
AM includes a sample policy condition script that demonstrates how to access a user’s profile information, use that information in HTTP calls, and make a policy decision based on the outcome.
To examine the contents of the sample policy condition script in the AM admin UI, go to Realms > realm name > Scripts, and select Scripted Policy Condition.
Test scripted policy conditions with the sample script
The sample policy condition script requires the subject of the policy to have an address in their profile. The script compares this address to the country in the resource URL and to the country from which the request originated (determined by an external GeoIP web service). The script also requires the user to have access to evaluate policies.
Add an address to a user profile
Add an address value to a user’s profile. The sample policy condition script uses the address when
performing policy evaluation. This example assumes that the user you are updating exists and has the ID demo.
-
In the AM admin UI, go to Realms > realm name > Identities.
-
On the Identities tab, select (
demo). -
In the Home Address field, enter a valid address.
For example:
201 Mission St, Suite 2900, San Francisco, CA 94105
-
Click Save Changes.
Add a user who can evaluate policies
Add a user to a group and assign the privilege required to perform policy evaluations.
-
In the AM admin UI, go to Realms > realm name > Identities.
-
Click Add Identity, enter an ID for the identity, such as
restPolicyUser, complete the required fields, and click Create. -
Return to Realms > realm name > Identities.
On the Groups tab, click Add Group, enter an ID for the group, such as
policyEval, and click Create. -
Return to Realms > realm name > Identities.
-
Select the user you created in step 2, for example,
restPolicyUser. -
On the Groups tab, in the Name field, select the group you created in step 3, for example
policyEval. -
Click Save Changes.
-
-
Go to Realms > realm name > Identities > Groups.
-
Select the group you created in step 3, for example
policyEval. -
On the Privileges tab, select
Policy Admin, then click Save Changes.
Create a policy that uses the sample policy condition script
Create a policy that uses the sample policy condition script. Policy evaluations can then be performed to test the script functionality.
-
In the AM admin UI, go to Realms > realm name > Authorization > Policy Sets.
-
On the Policy Sets page, select
Default OAuth2 Scopes Policy Set. -
Click Add a Policy.
-
Define the policy as follows:
-
Enter a name for the policy.
-
Define resources to which the policy applies:
-
Select
URLfrom the Resource Type list. -
Select the resource pattern
*://*:*/*from the Resources list, then click Add.The
*://*:*/*resource appears in the Resources field. -
Select Add Resource to add a second resource to the policy.
-
Select the resource pattern
*://*:*/*?*from the Resources list, then click Add.The
*://*:*/*?*resource appears along with the*://*:*/*resource in the Resources field. -
Click Create to create the policy.
The Resources tab appears as follows:
-
-
Specify actions to which the policy applies:
-
On the Actions tab, select GET from the Add an Action list.
-
The GET action appears in the list of actions. The default state for the GET action is Allow.
The Actions tab appears as follows:
-
Click Save Changes.
-
-
Configure identities to which the policy applies:
-
On the Subjects tab, select the edit icon ().
-
Select Authenticated Users from the Type list.
-
Select the OK icon—the check mark.
The Subjects tab appears as follows:
-
Click Save Changes.
-
-
Configure environments in which the policy applies:
-
On the Environments tab, select Add an Environment Condition.
-
Select Script from the Type list.
-
Select Scripted Policy Condition from the Script Name list.
-
Select the OK icon—the check mark.
The Environments tab appears as follows:
-
Click Save Changes.
-
-
No additional configuration is required in the Response Attributes or Details tabs.
-
Test the sample policy condition script
To evaluate against a policy, you must first obtain an SSO token for the subject performing the evaluation,
in this case demo. You can then make a call to the policies?_action=evaluate endpoint, including some environment
information, which the policy uses to make an authorization decision.
Evaluate a policy
-
Obtain an SSO token for the
demouser:$ curl \ --request POST \ --header "Content-Type: application/json" \ --header "X-OpenAM-Username: demo" \ --header "X-OpenAM-Password: Ch4ng31t" \ --header "Accept-API-Version: resource=2.0, protocol=1.0" \ 'https://<tenant-name>.forgeblocks.com/am/json/realms/root/realms/alpha/authenticate' { "tokenId":"AQIC5wM…TU3OQ*", "successUrl":"/openam/console", "realm":"/alpha" } -
Obtain an SSO token for the user who has the privilege required to evaluate policies.
For example,
restPolicyUser.$ curl \ --request POST \ --header "Content-Type: application/json" \ --header "X-OpenAM-Username: restPolicyUser" \ --header "X-OpenAM-Password: myStrongPassword" \ --header "Accept-API-Version: resource=2.0, protocol=1.0" \ 'https://<tenant-name>.forgeblocks.com/am/json/realms/root/realms/alpha/authenticate' { "tokenId":"AQIC8aF…TA1OQ*", "successUrl":"/openam/console", "realm":"/alpha" } -
Send an evaluation request to the
policiesendpoint, providing the SSO token of therestPolicyUseruser as the value of the<session-cookie-name>header.In the JSON data, set the
subjectobject to the SSO token of thedemouser. In theresourcesobject, include a URL that resides on a server in the same country as the address set for thedemouser. In theenvironmentobject, include an IP address that is also based in the same country as the user and the resource.The example below uses the URL of a web site and an IP address located in the United States:
$ curl \ --request POST \ --header "Content-Type: application/json" \ --header "<session-cookie-name>: AQIC8aF…TA1OQ*" \ --data '{ "resources":[ "https://www.us-site.com:8443/index.html" ], "application":"iPlanetAMWebAgentService", "subject":{ "ssoToken":"AQIC5wM…TU3OQ*" }, "environment":{ "IP":[ "38.99.39.210" ] } }' \ "https://<tenant-name>.forgeblocks.com/am/json/realms/root/policies?_action=evaluate" { "advices":{}, "ttl":9223372036854775807, "resource":"https://www.us-site.com:8443/index.html", "actions":{ "POST":true, "GET":true }, "attributes":{ "countryOfOrigin":[ "United States" ] } }If the country in the subject’s profile matches the country determined from the source IP in the environment and the country determined from the resource URL, then AM returns a list of actions available. The script will also add an attribute to the response called
countryOfOriginwith the country as the value.If the countries do not match, no actions are returned. In the following example, the resource URL is based in France, while the IP and user’s address in the profile are based in the United States:
$ curl \ --request POST \ --header "Content-Type: application/json" \ --header "<session-cookie-name>: AQIC8aF…TA1OQ*" \ --data '{ "resources":[ "https://www.france-site.com:8443/index.html" ], "application":"iPlanetAMWebAgentService", "subject":{ "ssoToken":"AQIC5wM…TU3OQ*" }, "environment":{ "IP":[ "38.99.39.210" ] } }' \ "https://<tenant-name>.forgeblocks.com/am/json/realms/root/policies?_action=evaluate" { "advices": {}, "ttl": 9223372036854775807, "resource": "https://www.france-site.com:8443/index.html", "actions": {}, "attributes": {} }