Preface

This guide covers concepts, implementation procedures, and customization
techniques for working with the authorization features of ForgeRock Access Management.

This guide is written for anyone using Access Management to manage authorization.

About ForgeRock Identity Platform™ Software

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.

Chapter 1. Introducing Authorization

This chapter provides an overview of authorization.

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

Whether access is granted depends on what the policies about access
are, who is trying to gain access, and perhaps some other conditions, such as
whether the access itself needs to happen over a secure channel or what time
of day it is.

1.1. Resource Types, Policy Sets, and Policies

Define authorization policies to allow AM to
determine whether to grant a subject access to a resource.

A policy defines the following:

resources

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

actions

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

subject conditions

The subject conditions constrain 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 environment conditions set
the circumstances under which the policy applies,
such as only during work hours,
only when accessing from a specific IP address,
or only when the flight is scheduled to leave within the next four hours.

response attributes

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

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

Resource types

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

AM includes two resource types by default: URL
and OAuth2 Scope.

URL resource type

The URL resource type acts as a template for protecting web
pages or applications. It contains resource patterns, such as
*://*:*/*?*, which can be made more specific
when used in the policy. The resource supports the following actions:

GET

POST

PUT

HEAD

PATCH

DELETE

OPTIONS

For 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* and
http*://example.com/hr*?*, and only the HTTP
GET and POST actions.

AM also includes a resource type to protect REST endpoints, with
patterns including https://*:*/*?*
and the CRUDPAQ actions:

CREATE

READ

UPDATE

DELETE

PATCH

ACTION

QUERY

OAuth2 Scope resource type

The OAuth2 Scope resource 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 patters, such as
*://*:*/*?*. The resource supports the
GRANT action, which can be allowed or denied.

Policy Sets

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

AM includes the following default policy sets:

The Default Policy Set, iPlanetAMWebAgentService is 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.

Important

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.

1.2. Policy Decisions

AM relies on policies to reach authorization decisions,
such as whether to grant or to deny access to a resource or grant or deny
OAuth 2.0 scopes.

Protecting Resources Through Policy Decisions

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.

Protecting Pages or Applications

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 web site
having authenticated 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 reauthenticate using a one-time password module,
gaining authentication level 1,
and thus having AM grant access to the protected page.

Granting or Denying OAuth 2.0 Scopes Through Policy Decisions

You can
configure AM to grant scopes statically or dynamically:

Statically. 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.

Granting or Denying OAuth2 2.0 Scopes Dynamically

When OAuth 2.0 policies are configured, default scopes are granted in the
following situations as long as they are configured in a policy which passes
policy evaluation:

When no scope is requested

When default scopes are requested

Important

When issuing a refresh token, any scope that was previously consented
either by policy or by the resource owner on the consent screen will
be issued unless it is explicitly denied by a policy.

1.3. Authorization Examples

Protecting Resources

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 web site developer can offer a profile page,
but the web site 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 web site.
You might need to agree with web site 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 web site,
or allow users already logged in to their desktops to visit protected sites
without having to type their credentials again.

Granting or Denying OAuth 2.0 Scopes Dynamically

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 his 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.

1.4. Reaching 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. If you want AM to continue checking
despite the deny, navigate to Configure > Global Services, select Policy
Configuration, and then enable Continue Evaluation on Deny Decision.

Chapter 2. Implementing Authorization

This chapter covers how to implement authorization using the AM console
and the REST API.

2.1.1.1. Configuring Resource Types

This section describes the process of using the AM
console for creating resource types, which
define a template for the resources that policies apply to,
and the actions that could be performed on those resources.

Select Create Resource Type to save a new resource type or Save
Changes to save modifications to an existing resource type.

2.1.1.2. Configuring Policy Sets

This section describes how to use the AM
console to create policy sets, which are
used as templates for policies protecting Web sites, Web applications,
or other resources.

When creating policy sets, consider the following points:

To make use of a policy set configured with policies containing the
URL resource type or any other custom resource type,
you must configure a web or Java agent to use the policy set for policy decisions.
For details
see "To Specify the Realm and Application for Policy Decisions" in the Setup and Maintenance Guide.

Enter a name for the policy set. The name is optional and is
for display purposes only.

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

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 Delete or
Backspace.

Important

Configure the OAuth2 Scope resource type only in the
Default OAuth2 Scopes Policy Set. Any policy configured for the
OAuth2 Scope resource 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.

2.1.1.3. Configuring Policies

This section describes the process of using the AM console to
configure policies, which are used to protect a web site, web application, or
other resource.

To Configure a Policy Using the AM Console

In the AM console, select Realms >
Realm Name
> Authorization > Policy Sets, and then 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.

Note

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

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 "Configuring Resource Types".

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

Tip

To remove a resource, select Delete.

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.

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 console by combining logical operators
with blocks of configured parameters to create a rule set that the policy
uses to filter requests for resources. Use drag and drop to nest
logical operators at multiple levels to create complex rule sets.

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

Valid Drop Point

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.

Nesting subject conditions

The available subject condition types are:

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, navigate to Realms >
Realm Name > Identities.

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

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

OpenID Connect/Jwt Claim

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

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

Repeat the step to enter additional claims.

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

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

Never Match

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

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

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

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

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.

Note

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

The available environment condition types are:

Active Session Time

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

Authentication by Module Chain

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

Authentication by Module Instance

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

Authentication Level (greater than or equal to)

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

Authentication Level (less than or equal to)

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

Authentication to a Realm

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

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

Current Session Properties

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

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

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

Identity Membership

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

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

Note

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

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

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

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

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

IPv6 Address/DNS Name

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

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

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

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

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

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

LDAP Filter Condition

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

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

OAuth2 Scope

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

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

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

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

Resource/Environment/IP Address

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

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

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

The available parameters for the
THEN
statement are as follows:

module

The module that was used to authenticate the user, for
example DataStore.

service

The service that was used to authenticate the user.

authlevel

The minimum required authentication level.

role

The role of the authenticated user.

user

The name of the authenticated user.

redirectURL

The URL the user was redirected from.

realm

The realm that was used to authenticate the user.

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

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

Script

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

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

Time (day, date, time, and timezone)

Make the policy test when the policy is evaluated.

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

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

Transaction

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

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

Transactions support the following authentication strategies:

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

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

For example, /sales/internal.

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

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

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

Note

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

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

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

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

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

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

Note

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

2.1.1.4. Specifying 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/* matches
http://www.example.com/,
http://www.example.com/index.html, and also
http://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/-*- matches
http://www.example.com/index.html but does not match
http://www.example.com/company/resource.html or
http://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/*?* matches
http://www.example.com/users?_action=create, but not
http://www.example.com/users?.

To match everything under
http://www.example.com/ specify three patterns,
one for http://www.example.com/*,
one for http://www.example.com/*?, and
one for http://www.example.com/*?*.

When matching resources by using the policies?_action=evaluate
REST endpoint, an asterisk (*) used at the end of a pattern
after a ? character matches zero or more characters.

For example, http://www.example.com/*?* matches
http://www.example.com/users?_action=create, as well as
http://www.example.com/users?.

To match everything under
http://www.example.com/ specify two patterns,
one for http://www.example.com/*,
one for http://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=get
is 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/,
and http://www.example.com/path//
are treated in the same way.

http://www.example.com/path,
and http://www.example.com/path/
are considered two distinct resources.

Wildcards can be used to match protocols, host names, and port numbers.

When a port number is not explicitly specified,
then the default port number is implied.
Therefore http://www.example.com/*
is the same as http://www.example.com:80/*,
and https://www.example.com/*
is the same as https://www.example.com:443/*.

Wildcards cannot be escaped.

Do not mix * and -*- in the same
pattern.

By default, comparisons are not case sensitive.
The delimiter, wildcards and case sensitivity are configurable.
To see examples of other configurations, in the AM console, navigate to
Configure > Global Services, select Policy Configuration, and scroll to Resource
Comparator.

2.1.2. Importing and Exporting Policies

You can import and export policies to and from files.

You can use these files to backup policies, transfer policies between
AM instances, or store policy configuration in a version
control system such as Git or Subversion.

2.2. Implementing Authorization Using the REST API

2.2.1. About the REST Policy Endpoints

AM provides REST APIs both for requesting policy decisions,
and also for administering policy definitions.

When making a REST API call, specify the realm in the path component of the
endpoint. You must specify the entire hierarchy of the realm, starting at the top-level realm.
Prefix each realm in the hierarchy with the realms/ keyword. For example
/realms/root/realms/customers/realms/europe.

Under
/json/realms/root/resourcetypes,
you find a JSON-based API for managing resource types.

Under
/json/realms/root/applications
and /json/applicationtypes
you find JSON-based APIs
for administering policy sets and reading application types.

Under /json/realms/root/policies,
you find a JSON-based API for policy management and evaluation.

Under /json/conditiontypes you find a JSON-based API
for viewing what types of conditions you can use when defining policies.

Under /json/subjecttypes you find a JSON-based API
for viewing what types of subjects you can use when defining policies.

Under /json/subjectattributes you find a JSON-based API
for viewing subjects' attributes you can use when defining response
attributes in policies.

Under /json/decisioncombiners you find a JSON-based API
for viewing implementations you can use when defining policies
to specify how to combine results when multiple policies apply.

Before making a REST API call to request a policy decision or 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

2.2.2. Requesting Policy Decisions

You can request policy decisions from AM
by using the REST APIs described in this section.
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.

2.2.2.1. Requesting 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. You must specify the entire hierarchy of the realm, starting at the top-level realm.
Prefix each realm in the hierarchy with the realms/ keyword. For example
/realms/root/realms/customers/realms/europe.

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{/realms/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.

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
"Authentication and Logout".

"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 iPlanetDirectoryPro header sets the SSO token
for a user who has access to perform the operation.

A
"ResourceEnvIP"
condition failure can result in advice
showing that indicates corrective action to be taken
to resolve the problem. The advice varies, depending on what the condition
tests. For example, failure against the following condition:

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:

When policy evaluation denials occur against the following conditions,
AM does not return any advice:

IPv4

IPv6

LDAPFilter

OAuth2Scope

SessionProperty

SimpleTime

2.2.2.3. Requesting 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. You must specify the entire hierarchy of the realm, starting at the top-level realm.
Prefix each realm in the hierarchy with the realms/ keyword. For example
/realms/root/realms/customers/realms/europe.

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.

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,
"Authentication and Logout".

"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 iPlanetDirectoryPro 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.

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.

2.2.3. Managing Resource Types

This section describes the process of using the AM REST API for managing
resource types, which define a template for the resources that policies apply
to, and the actions associated with those resources.

Resource types are realm specific, hence the URI for the resource
types API can contain a realm component, such as
/json{/realm}/resourcetypes.
If the realm is not specified in the URI, the top level realm is
used.

Resource types are represented in JSON and take the following form.
Resource types are built from 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 will not affect the UUID.

2.2.3.3. Creating a Resource Type

To create a resource type in a realm, perform an HTTP POST to the
/json{/realm}/resourcetypes
endpoint, with an _action parameter
set to create. Include a JSON representation of the
resource type in the POST data.

Note

If the realm is not specified in the URL, AM creates the
resource type in the top level realm.

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

2.2.3.4. Updating a Resource Type

To update an individual resource type in a realm, perform an HTTP
PUT to the /json{/realm}/resourcetypes
endpoint, and specify 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.

Note

If the realm is not specified in the URL, AM uses the top
level realm.

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

You can only delete resource types that are not being used by
a policy set or policy. Trying to delete a resource type that is in
use will return an HTTP 409 Conflict status code, with a message such as:

Remove the resource type from any associated policy sets or
policies to be able to delete it.

2.2.4. Managing Application Types

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.

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

Policy sets are realm specific, hence the URI for the policy set API can
contain a realm component, such as
/json{/realm}/applications.
If the realm is not specified in the URI, the top level realm is
used.

Policy sets are represented in JSON and take the following form.
Policy sets are built from standard JSON objects and values
(strings, numbers, objects, arrays, true,
false, and null).

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.

2.2.5.3. Creating Policy Sets

To create a policy set in a realm, perform an HTTP POST to the
/json{/realm}/applications
endpoint, with an _action parameter
set to create. Include a JSON representation of the
policy set in the POST data.

Note

If the realm is not specified in the URL, AM creates the
policy set in the top level realm.

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

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.

2.2.5.4. Updating Policy Sets

To update an individual policy set in a realm, perform an HTTP
PUT to the /json{/realm}/applications
endpoint, and specify the policy set name in the URL. Include a
JSON representation of the updated policy set in the PUT data.

Note

If the realm is not specified in the URL, AM uses the top
level realm.

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

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.

Tip

Action values can also be expressed as numeric values. When using
numeric values, use the value 0 for
false and use any non-zero numeric
value for true.

"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 "type" set to the name of the implementation
(using a short name for all registered subject implementations),
and also 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"
}

Warning

The AuthenticatedUsers subject 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, also add the AuthenticateToRealm
environment condition.

"Identity"
to specify one or more users from an AM identity repository:

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 also other fields depending on the implementation.
The condition types registered by default include the following.

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 either IP to match the user's IP address,
or 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:

module

The module that was used to authenticate the user,
for example DataStore.

service

The authentication chain that was used to authenticate the user.

authlevel

The minimum required authentication level.

role

The role of the authenticated user.

user

The name of the authenticated user.

redirectURL

The URL from which the user was redirected.

realm

The realm to which the user authenticated.

"Session"
to specify how long the user's session has been
active, and to terminate the session if deemed too old,
such that the user must authenticate again. Note that AM terminates
client-based sessions only if session blacklisting is in effect.
For more information about session blacklisting, see "Session Termination" in the Authentication and Single Sign-On Guide.

List of attributes to return with decisions. These attributes
are known as response attributes, and do not
apply to OAuth2 Scope resource 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
with "type" set to the name of the implementation
(by default either
"Static" for statically defined attributes
or "User" for attributes from the user profile),
"propertyName" 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.

2.2.5.6.1. Querying 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, by using the procedures below:

Additional query strings can be specified to alter the returned results.
For more information,
see "Query".

Supported _queryFilter Fields and
Operators

Field

Supported Operators

name

Equals (eq)

description

Equals (eq)

applicationName

Equals (eq)

createdBy

Equals (eq)

creationDate

Equals (eq),
Greater than or equal to (ge),
Greater than (gt),
Less than or equal to (le),
Less than (lt)

Note

The implementation of eq for this date
field does not use regular expression pattern matching.

lastModifiedBy

Equals (eq)

lastModifiedDate

Equals (eq),
Greater than or equal to (ge),
Greater than (gt),
Less than or equal to (le),
Less than (lt)

Note

The implementation of eq for this date
field does not use regular expression pattern matching.

To 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.

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 Identity are
queried—environment conditions are not queried. The Identity
subject condition type is labelled as Users & Groups in the
policy editor in the AM console.

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{/realm}/policies
endpoint, with an _queryId parameter set to
queryByIdentityUid, and a uid parameter
containing the universal ID of the user or group:

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.

2.2.5.6.4. Updating Policies

To update an individual policy in a realm, perform an HTTP
PUT to the /json{/realm}/policies
endpoint, and specify the policy name in the URL. Include a
JSON representation of the updated policy in the PUT data.

Note

If the realm is not specified in the URL, AM uses the top
level realm.

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

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 myPolicy policy.

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{/realm}/policies
endpoint as follows:

Specify the _action=copy or
_action=move URL 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 iPlanetDirectoryPro header.

Specify JSON input data as follows:

JSON Input Data for Copying or Moving Multiple Policies

Object

Property

Description

from

application

The policy set in which the input policies are located.

Required.

to

application

The policy set in which to store output policies.

Required when copying or moving policies to a different policy set.

to

realm

The realm in which to store output policies.

Required when copying or moving policies to a different realm.

to

namePostfix

A value appended to output policy names in order to prevent name
clashes.

Required.

resourceTypeMapping

Varies; see Description

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-4164e8f2b35b
resource 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:

2.2.5.7. Importing and Exporting XACML 3.0

AM supports the ability to export policies to
eXtensible Access Control Markup Language (XACML) 3.0-based
formatted policy sets
through its /xacml/policies REST endpoint.
You can also import XACML 3.0 policy sets back into AM by using the
same endpoint.
The endpoint's functionally is identical to that of the
ssoadm create-xacml and
ssoadm list-xacml commands.
For more information, see "Importing and Exporting Policies".

Note

AM can only import XACML 3.0 policy sets that were either created by an
AM instance, or that have had minor manual modifications,
due to the reuse of some XACML 3.0 parameters for non-standard information.

When exporting AM policies to XACML 3.0 policy sets, AM maps its
policies to XACML 3.0 policy elements. The
mappings are as follows:

Policies to XACML Mappings

AM Policy

XACML Policy

Policy Name

Policy ID

Description

Description

Current Time (yyyy.MM.dd.HH.mm.ss.SSS)

Version

xacml rule target

entitlement excluded resource names

Rule Deny Overrides

Rule Combining Algorithm ID

Any of:

Entitlement Subject

Resource Names

Policy Set Names

Action Values

Target

Any of:

Policy Set Name

Entitlement Name

Privilege Created By

Privilege Modified By

Privilege Creation Date

Privilege Last Modification Date

Variable Definitions

Single Level Permit/Deny Actions converted
to Policy Rules

Rules

Note

XACML obligation is not supported. Also, only one XACML match is defined for
each privilege action, and only one XACML rule for each privilege action value.

2.2.5.7.1. Exporting to XACML

AM supports exporting policies into XACML 3.0 format.
AM only exports a policy set that contains policy definitions. No other
types can be included in the policy set, such as sub-policy sets or rules.
The policy set mapping is as follows:

Policy Set Mappings

AM

XACML

Realm:<timestamp>(yyyy.MM.dd.HH.mm.ss.SSS)

PolicySet ID

Current Time (yyyy.MM.dd.HH.mm.ss.SSS)

Version

Deny Overrides

Policy Combining Algorithm ID

No targets defined

Target

The export service is accessible at the /xacml/policies
endpoint using a HTTP GET request
at the following endpoint for the root realm or a specific realm:

http://openam.example.com:8080/openam/xacml/policies
http://openam.example.com:8080/openam/xacml/{realm}/policies
where {realm} is the name of a specific realm

You can filter your XACML exports using query search filters. Note the
following points about the search filters:

LDAP-based Searches.
The search filters follow the standard
guidelines for LDAP searches as they are applied to the
entitlements index in the LDAP configuration backend, located at:
ou=default,ou=OrganizationalConfig,ou=1.0,ou=sunEntitlementIndexes,
ou=services,dc=openam,dc=forgerock,dc=org.

Search Filter Format. You can specify
a single search filter or multiple filters in the HTTP URL parameters.
The format for the search filter is as follows:

[attribute name][operator][attribute value]

If you specify multiple search filters, they are logically ANDed: the
search results meet the criteria specified in all the
search filters.

XACML Export Search Filter Format

Element

Description

Attribute Name

The name of the attribute to be searched for. The only permissible
values are: application (keyword for policy set), createdby,
lastmodifiedby, creationdate,
lastmodifieddate, name,
description.

Operator

The type of comparison operation to perform.

= Equals (text)

< Less Than or Equal To (numerical)

> Greater Than or Equal To (numerical)

Attribute Value

The matching value. Asterisk wildcards are supported.

To Export Policies

Use the /xacml/policies endpoint to export the AM entitlement
policies into XACML 3.0 format. The following curl command exports the policies
and returns the XACML response (truncated for display purposes).

2.2.5.7.2. Importing from XACML

AM supports the import of XACML 3.0-based policy sets into
AM policies using the REST /xacml/policies
endpoint.
To test an import, AM provides a dry-run feature that runs an import
without saving the changes to the database. The dry-run feature provides a
summary of the import so that you can troubleshoot any potential mismatches
prior to the actual import.

You can import a XACML policy using an HTTP POST request for the root realm
or a specific realm at the following endpoints:

http://openam.example.com:8080/openam/xacml/policies
http://openam.example.com:8080/openam/xacml/{realm}/policies
where {realm} is the name of a specific realm

To Import a XACML 3.0 Policy

You can do a dry run using the dryrun=true query to
test the import. The dry-run option outputs in JSON format and displays the status
of each import policy, where "U" indicates "Updated"; "A" for "Added". The
dry-run does not actually update to the database. When you are ready for an
actual import, you need to re-run the command
without the dryrun=true query.

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

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.

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

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:

2.2.5.10. Managing 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 data store where AM looks up the user's profile.

2.3. Implementing OAuth 2.0 Policies

Writing policies 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.

If the authorization policy had been configured as GRANT=Deny,
you still would have not seen the email scope in the
consent page, but the scope would not appear in the URL of the browser.

Chapter 3. Implementing Transactional Authorization

This chapter covers transactional authorization. Transactional authorization makes use
of the session upgrade functionality, applying it while authorization is in
progress. For information on session upgrade, see
"About Authentication Levels" in the Authentication and Single Sign-On Guide.

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 reauthenticate to an authentication module 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.

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:

Combining With Other Environment Conditions

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:

Accessing Resources with Transactional Authorization

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
version 5 or newer, 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 the HOTP authentication module for one-time password over email.

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 TransactionConditionAdvice
attribute 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 advices elements in policy
evaluations, see "Requesting Policy Decisions".

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 Unauthorized error is returned. For example:

AM responds with the callbacks necessary to satisfy any environment conditions.

Note

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
chain, or responds to the push notification on their registered mobile device.

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 re-evaluate the
policies applying to the protected resources again, but includes the ID of the
completed transaction as a value in the TxId array in the
environment object:

AM verifies the transaction was authorized and that the
transaction token is in the COMPLETED state.

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 POST
and GET actions to the resource
http://www.example.com:8000/index.html:

Important

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.

3.2. Using Transactional Authorization

This section demonstrates how to set up transactional authorization to send push
notifications to a user's mobile device to authorize access to a protected resource.

3.2.1. Transactional Authorization Prerequisite Tasks

Before attempting this demonstration you must perform the following
prerequisite tasks:

Create an authentication chain containing the
ForgeRock Authenticator (PUSH) Registration authentication
module. Log in to that chain as the demo user and register a mobile
device using the ForgeRock Authenticator application.

To use the AM console for the demonstration, set up a web agent to
protect web resources. See "First Steps" in the Quick Start Guide.

To use the AM REST API for the demonstration, create a user account
that has read access to the policy endpoints. By default, users do not have
permissions to access the policy evaluation endpoints directly.
To allow access to the policy REST endpoints, follow the steps
in "To Allow a User to Evaluate Policies".

Perform the following steps to set up an authorization policy with a transaction
environment condition, which requires users to respond to a push notification message on
their registered mobile device to authorize access to a protected resource.

On the Add Chain page, name the chain pushAuthChain, and then
select Create.

On the Edit Chain tab, select Add a Module.

On the New Module dialog, from the Select Module drop-down list, select the push
module you create in the earlier step, for example,
pushAuth, from the Select Criteria drop-down list, select
Required, and then select OK.

On the Edit Chain tab, select Save Changes.

Create an authorization policy as described in "To Configure a Policy" in the Quick Start Guide, and then make the following changes to the policy:

Note

The request requires authentication as a user with the privileges to
access the policy endpoints, for example by specifying the SSO token ID in the
iPlanetDirectoryPro cookie. See "Authentication and Logout".

AM returns an empty actions element, and a transaction
ID in the TransactionConditionAdvice property, because a
transactional authorization is required to access the resource.

Initiate authentication, and include the transaction ID in the composite advice.
Note that the steps used for performing a transactional authorization are identical
to performing a session upgrade. See
"Session Upgrade" in the Authentication and Single Sign-On Guide.

The transaction ID returned in the previous step must be returned as
composite advice query parameters, wrapped in URL-encoded XML. The XML format is as
follows:

At this point, the mobile device that was registered to the demo
user will receive a push notification message, that they should authorize in the
ForgeRock Authenticator app.

Ensure that the time specified in the waitTime property in
the callbacks has passed, in this case at least 10 seconds, and then complete and
return the requested callbacks.

The value of the authId property must also be
returned, as well as the URL-encoded transaction ID.

Use the SSO token of the demo user for this request.

Note

In this example, the required XML parameters have been
URL-encoded and added to the URL. The curl command is not able
to use the --data-urlencode option for query-string parameters
and also send a JSON payload.

If the callbacks were correctly completed, and the push notification was
responded to in the ForgeRock Authenticator app, AM returns the original
tokenId value.

If the push notification has not yet been responded to in the ForgeRock
Authenticator app, AM will return the required callbacks again, as in
the previous step. Wait until the amount of time specified in the
waitTime element has passed and retry the
request until the tokenId returns.

Re-evaluate the policy, including the transaction ID as the value of a
TxId property in the environment element:

As the authentication required by the transaction was successful, the second
policy evaluation returns the POST and GET
actions as defined in the policy.

Notice that the time-to-live (ttl) value of the policy
evaluation result is set to 0, meaning that the policy must not
be cached. The policy only allows a single access to the resource, which must be
managed by the policy enforcement point.

Note that performing the policy evaluation again with the same subject and resource at
this point starts a new transactional authorization flow, requiring each of the
steps above to be repeated in order to access the protected resource each time.

Chapter 4. Customizing Authorization

This chapter describes how to customize policy evaluation by writing
a policy plug-in and by scripting a customized policy condition.

4.1. Customizing Policy Evaluation With a Plug-In

AM policies let you restrict access to resources based both on
identity and group membership, and also on a range of conditions including
session age, authentication chain or module used, authentication level, realm,
session properties, IP address and DNS name, user profile content, resource
environment, date, day, time of day, and time zone. Yet, some deployments
require further distinctions for policy evaluation. This section explains how
to customize policy evaluation for deployments with particular requirements
not met by built-in AM functionality.

This section shows how to build and use a custom policy plugin
that implements a custom subject condition, a custom environment condition,
and a custom resource attribute.

Get a local clone so that you can try the sample on your system. In the sources, you find
the following files under the
/path/to/openam-samples-external/policy-evaluation-plugin
directory:

pom.xml

Apache Maven project file for the module

This file specifies how to build the sample policy evaluation plugin,
and also specifies its dependencies on AM components.

src/main/java/org/forgerock/openam/examples/SampleAttributeType.java

Extends the com.sun.identity.entitlement.ResourceAttribute interface,
and shows an implementation of a resource attribute provider
to send an attribute with the response.

src/main/java/org/forgerock/openam/examples/SampleConditionType.java

Extends the com.sun.identity.entitlement.EntitlementCondition interface,
and shows an implementation of a condition that is the length of the user name.

A condition influences whether the policy applies for a given access request.
If the condition is fulfilled,
then AM includes the policy in the set of policies to evaluate
in order to respond to a policy decision request.

src/main/java/org/forgerock/openam/examples/SampleSubjectType.java

Extends the com.sun.identity.entitlement.EntitlementSubject interface,
and shows an implementation that defines a user to whom the policy applies.

A subject, like a condition, influences whether the policy applies.
If the subject matches in the context of a given access request,
then the policy applies.

The Java class, SampleEntitlementModule, implements the
org.forgerock.openam.entitlement.EntitlementModule interface.
In the sample,
this class registers SampleAttribute,
SampleCondition, and SampleSubject.

The services file,
org.forgerock.openam.entitlement.EntitlementModule,
holds the fully qualified class name of the EntitlementModule
that registers the custom implementations.
In this case, org.forgerock.openam.entitlement.EntitlementModule.

For an explanation of service loading, see the
ServiceLoader API specification.

If you require additional translations under
/path/to/tomcat/webapps/openam/XUI/locales,
modify other translation.json files as needed.

Clear your browser's cache and restart your browser.

Clearing the cache and refreshing the browser is required when you modify
the translation.json file.

Restart AM or the container in which it runs.

4.1.3. Adding Custom Policy Implementations to Existing Policy Sets

In order to use your custom policy in existing policy sets, you must update
the policy sets. Note that you cannot update a policy set that already has
policies configured. When there are already policies configured for a
policy set, you must instead first delete the policies, and then update the
policy set.

Update the iPlanetAMWebAgentService policy set
in the top level realm of a fresh installation. First, authenticate
to AM as the amadmin user:

4.1.4. Trying the Sample Subject and Environment Conditions

Using the AM console, add a policy to the
iPlanetAMWebAgentService policy set in the top level realm
that allows HTTP GET access for URLs based on the template
http://www.example.com:80/* and uses the custom subject
and environment conditions.

Create the policy with the following properties:

Sample Policy Properties

Property

Value

Name

Sample Policy

Resource Type

URL

Resources

Use the *://*:*/*resource template to specify the
resource http://www.example.com:80/*.

Actions

Allow GET

Subject Conditions

Add a subject condition of type
Sample Subject and a name of
demo so that the demo user is the
only user who can access the resource.

Environment Conditions

Add an environment condition of type
Sample Condition and a minimum username length of
4 so that only users with a username length of 4
characters or greater can access the resource.

With the policy in place, authenticate
both as a user who can request policy decisions
and also as a user trying to access a resource.
Both of these calls return tokenId values
for use in the policy decision request.

Notice that the actions returned from the policy evaluation call are set in
accordance with the policy.

4.1.5. Trying the Sample Resource Attributes

The sample custom policy plugin can
have AM return an attribute with the policy decision.
In order to make this work, list the
resource type for the URL
resource type to obtain its UUID, and then update your policy to return a
test attribute:

4.1.6. Extending the ssoadm Classpath

After customizing your AM deployment to use policy evaluation plugins,
inform ssoadm users to add the jar file containing the
plugins to the classpath before running policy management subcommands.

To add a jar file to the ssoadm classpath, set the
CLASSPATH environment variable before running the
ssoadm command.

$ export CLASSPATH=/path/to/jarfile:$CLASSPATH
$ ssoadm ...

4.2. Scripting a Policy Condition

This section demonstrates how to use the sample policy condition script
as part of an authorization policy. To examine the
contents of the sample policy condition script in the AM console browse
to Realms > Top Level Realm > Scripts, and then select
Scripted Policy Condition.

The default policy condition script demonstrates how to access a user's
profile information, use that information in HTTP calls, and make a policy
decision based on the outcome.

4.2.1. Preparing

AM requires a small amount of configuration before trying the default
policy condition script. The default policy condition script requires that the
subject of the policy has an address in their profile. The script compares the
address to the country in the resource URL and to the country from which the
request originated, as determined by an external GeoIP web service. The
demo user also requires access to evaluate policies.

From the Level drop-down list, choose the debug level required. In this example,
select Message.

Select Submit, and on the summary page that appears, select Confirm.

Message-level debug logging is now enabled for policy evaluation.

4.2.2. Trying the Default Policy Condition Script

This section demonstrates using a policy that contains
the default policy condition script.

To evaluate against a policy, you must first obtain an SSO token for
the subject performing the evaluation, in this case the demo
user. 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.

Send an evaluation request to the policies
endpoint, using the SSO token of the demo user in the
iPlanetDirectoryPro header.

In the JSON data, set the subject property
to also be the SSO token of the demo user.
In the resources property, include a URL
that resides on a server in the same country as the address set for the
demo user. In the environment
property, include an IP address that is also based in the same
country as the user and the resource. The example below uses the
ForgeRock Community web site URL and an IP address from a ForgeRock
office, both located in the 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
countryOfOrigin with 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:

The minimum lifetime to keep unanswered message records in the message dispatcher cache, in seconds. To keep unanswered message records indefinitely, set this property to 0.Should be tuned so that it is applicable to the use case of this service. For example, the ForgeRock Authenticator (Push) authentication module has a default timeout of 120 seconds.

Default value:
120

amster attribute:
mdDuration

Response Cache Concurrency

Level of concurrency to use when accessing the message dispatcher cache. Defaults to 16, and must be greater than 0. Choose a value to accommodate as many threads as will ever concurrently access the message dispatcher cache.

Default value:
16

amster attribute:
mdConcurrency

Response Cache Size

Maximum size of the message dispatcher cache, in number of records. If set to 0 the cache can grow indefinitely. If the number of records that need to be stored exceeds this maximum, then older items in the cache will be removed to make space.

Bind password to connect to the directory server for policy information.

amster attribute:
bindPassword

LDAP Organization Search Filter

Search filter to match organization entries.

Default value:
(objectclass=sunismanagedorganization)

amster attribute:
realmSearchFilter

LDAP Users Search Filter

Search filter to match user entries.

Default value:
(objectclass=inetorgperson)

amster attribute:
usersSearchFilter

LDAP Users Search Scope

Search scope to find user entries.

The possible values for this property are:

SCOPE_BASE

SCOPE_ONE

SCOPE_SUB

Default value:
SCOPE_SUB

amster attribute:
usersSearchScope

LDAP Users Search Attribute

Naming attribute for user entries.

Default value:
uid

amster attribute:
usersSearchAttribute

Maximum Results Returned from Search

Search limit for LDAP searches.

Default value:
100

amster attribute:
maximumSearchResults

Search Timeout

Time after which OpenAM returns an error for an incomplete search, in seconds.

Default value:
5

amster attribute:
searchTimeout

LDAP SSL/TLS

If enabled, OpenAM connects securely to the directory server. This requires that you install the directory server certificate.

Default value:
false

amster attribute:
sslEnabled

LDAP Connection Pool Minimum Size

Minimum number of connections in the pool.

Default value:
1

amster attribute:
connectionPoolMinimumSize

LDAP Connection Pool Maximum Size

Maximum number of connections in the pool.

Default value:
10

amster attribute:
connectionPoolMaximumSize

Heartbeat Interval

Specifies how often should OpenAM send a heartbeat request to the directory.

Use this option in case a firewall/loadbalancer can close idle connections, since the heartbeat requests will ensure that the connections won't become idle.

Default value:
10

amster attribute:
policyHeartbeatInterval

Heartbeat Unit

Defines the time unit corresponding to the Heartbeat Interval setting.

Use this option in case a firewall/loadbalancer can close idle connections, since the heartbeat requests will ensure that the connections won't become idle.

The possible values for this property are:

SECONDS. second

MINUTES. minute

HOURS. hour

Default value:
SECONDS

amster attribute:
policyHeartbeatTimeUnit

Subjects Result Time to Live

Maximum time that OpenAM caches a subject result for evaluating policy requests, in minutes. A value of 0 prevents OpenAM from caching subject evaluations for policy decisions.

Default value:
10

amster attribute:
subjectsResultTTL

User Alias

If enabled, OpenAM can evaluate policy for remote users aliased to local users.

Default value:
false

amster attribute:
userAliasEnabled

5.1.3. Transaction Authentication Service

amster service name: transaction

5.1.3.1. Realm Defaults

The following settings appear on the Realm Defaults tab:

Time to Live

The number of seconds within which the transaction must be completed.

Default value:
180

amster attribute:
timeToLive

5.2. Authorization API Functionality

This section covers functionality available when scripting
authorization using the policy condition script context type.

5.2.1. Accessing Authorization State

Server-side scripts can access the current authorization state
through the following objects:

Authorization State Objects

Object

Type

Description

authorized

Boolean

Return true if the authorization is currently successful,
or false if authorization has failed.
Server-side scripts must set a value for authorized
before completing.

environment

Map<String, Set<String>>

Describe the environment passed from the client making the
authorization request.

For example, the following shows a simple
environment map with a single entry:

"environment": {
"IP": [
"127.0.0.1"
]
}

resourceURI

String

Specify the URI of the resource to which authorization is being requested.

username

String

Specify the user ID of the subject that is requesting authorization.

5.2.2. Accessing Profile Data

Server-side authorization scripts can access profile data of the
subject of the authorization request through
the methods of the identity object.

Note

To access the profile data of the subject, they must be
logged in and their SSO token must be available.

Authorization Script Profile Data Methods

Method

Parameters

Return Type

Description

identity.getAttribute

Attribute Name (type: String)

Set

Return the values of the named attribute for the subject of the
authorization request.

identity.setAttribute

Attribute Name (type: String)

Attribute Values (type: Array)

Void

Set the named attribute to the values specified by the attribute value
for the subject of the authorization request.

identity.addAttribute

Attribute Name (type: String)

Attribute Value (type: String)

Void

Add an attribute value to the list of attribute values associated with the
attribute name for the subject of the authorization request.

identity.store

None

Void

Commit any changes to the identity repository.

Caution

You must call store() otherwise changes
will be lost when the script completes.

5.2.3. Accessing Session Data

Server-side authorization scripts can access session data of the
subject of the authorization request through
the methods of the session object.

Note

To access the session data of the subject, they must be
logged in and their SSO token must be available.

Authorization Script Session Methods

Method

Parameters

Return Type

Description

session.getProperty

Property Name (type: String)

String

Retrieve properties from the session associated with the subject of
the authorization request. For example, AuthLevel.

5.2.4. Setting Authorization Responses

Server-side authorization scripts can return information in the response
to an authorization request.

Authorization Script Response Methods

Method

Parameters

Return Type

Description

responseAttributes.put

Attribute Name (type: String)

Attribute Values (type: Array)

Void

Add an attribute to the response to the authorization request.

advice.put

Advice Key (type: String)

Advice Values (type: Array)

Void

Add advice key-value pairs to the response to a failing authorization
request.

ttl

TTL Value (type: Integer)

Void

Add a time-to-live value, which is a timestamp in milliseconds to the response
to a successful authorization. After the time-to-live value the decision
is no longer valid.

If no value is set, TTL Value defaults to
Long.MAX_VALUE (9223372036854775807), which means
the decision has no timeout, and can live for as long as the calling
client holds on to it. In the case of policy enforcement points, they
hold onto the decision for their configured cache timeout.

Appendix A. About the REST API

This appendix shows how to use the RESTful interfaces for direct
integration between web client applications and ForgeRock Access Management.

A.1. Introducing REST

Representational State Transfer (REST) is an architectural style
that sets certain constraints for designing and building
large-scale distributed hypermedia systems.

As an architectural style, REST has very broad applications.
The designs of both HTTP 1.1 and URIs follow RESTful principles.
The World Wide Web is no doubt the largest and best known REST application.
Many other web services also follow the REST architectural style.
Examples include OAuth 2.0, OpenID Connect 1.0, and User-Managed Access
(UMA).

The ForgeRock Common REST (CREST) API applies RESTful principles
to define common verbs for HTTP-based APIs that access web resources
and collections of web resources.

A.2. About ForgeRock Common REST

ForgeRock® Common REST is a common REST API framework. It works across the
ForgeRock platform to provide common ways to access web resources and
collections of resources. Adapt the examples in this section to your resources
and deployment.

A.2.1. Common REST Resources

Servers generally return JSON-format resources,
though resource formats can depend on the implementation.

Resources in collections can be found by their unique identifiers (IDs).
IDs are exposed in the resource URIs.
For example, if a server has a user collection under /users,
then you can access a user at
/users/user-id.
The ID is also the value of the _id field of the resource.

Resources are versioned using revision numbers.
A revision is specified in the resource's _rev field.
Revisions make it possible to figure out whether to apply changes
without resource locking and without distributed transactions.

A.2.2. Common REST Verbs

The Common REST APIs use the following verbs,
sometimes referred to collectively as CRUDPAQ.
For details and HTTP-based examples of each,
follow the links to the sections for each verb.

A.2.3. Common REST Parameters

Reserved query string parameters include, but are not limited to,
the following names:

_action

_api

_crestapi

_fields

_mimeType

_pageSize

_pagedResultsCookie

_pagedResultsOffset

_prettyPrint

_queryExpression

_queryFilter

_queryId

_sortKeys

_totalPagedResultsPolicy

Note

Some parameter values are not safe for URLs,
so URL-encode parameter values as necessary.

Continue reading for details about how to use each parameter.

A.2.4. Common REST Extension Points

The action verb is the main vehicle for extensions.
For example, to create a new user with HTTP POST rather than HTTP PUT,
you might use /users?_action=create.
A server can define additional actions.
For example, /tasks/1?_action=cancel.

A server can define stored queries to call by ID.
For example, /groups?_queryId=hasDeletedMembers.
Stored queries can call for additional parameters.
The parameters are also passed in the query string.
Which parameters are valid depends on the stored query.

A.2.5. Common REST API Documentation

Common REST APIs often depend at least in part on runtime configuration.
Many Common REST endpoints therefore serve
API descriptors at runtime.
An API descriptor documents the actual API as it is configured.

Use the following query string parameters to retrieve API descriptors:

In production systems, developers expect stable, well-documented APIs.
Rather than retrieving API descriptors at runtime through Common REST,
prepare final versions, and publish them alongside the software in production.

Use the OpenAPI-compliant descriptors to provide API reference documentation
for your developers as described in the following steps:

Configure the software to produce production-ready APIs.

In other words, the software should be configured as in production
so that the APIs are identical to what developers see in production.

Retrieve the OpenAPI-compliant descriptor.

The following command saves the descriptor
to a file, myapi.json:

$ curl -o myapi.json endpoint?_api

(Optional)
If necessary, edit the descriptor.

For example, you might want to add security definitions
to describe how the API is protected.

If you make any changes, then also consider using a source control system
to manage your versions of the API descriptor.

You can customize Swagger UI for your organization
as described in the documentation for the tool.

A.2.6. Create

There are two ways to create a resource,
either with an HTTP POST or with an HTTP PUT.

To create a resource using POST, perform an HTTP POST
with the query string parameter _action=create
and the JSON resource as a payload.
Accept a JSON response.
The server creates the identifier if not specified:

To create a resource using PUT, perform an HTTP PUT
including the case-sensitive identifier for the resource in the URL path,
and the JSON resource as a payload.
Use the If-None-Match: * header.
Accept a JSON response:

The _id and content of the resource depend on the server implementation.
The server is not required to use the _id that the client provides.
The server response to the create request indicates the resource location
as the value of the Location header.

If you include the If-None-Match header, its value must be
*. In this case, the request creates the object if it
does not exist, and fails if the object does exist. If you include the
If-None-Match header with any value other than
*, the server returns an HTTP 400 Bad Request error. For
example, creating an object with
If-None-Match: revision returns
a bad request error. If you do not include If-None-Match: *,
the request creates the object if it does not exist, and
updates the object if it does exist.

Parameters

You can use the following parameters:

_prettyPrint=true

Format the body of the response.

_fields=field[,field...]

Return only the specified fields in the body of the response.

The field values are JSON pointers.
For example if the resource is {"parent":{"child":"value"}},
parent/child refers to the "child":"value".

If the field is left blank, the server returns all default
values.

A.2.7. Read

To retrieve a single resource, perform an HTTP GET on the resource
by its case-sensitive identifier (_id)
and accept a JSON response:

The field values are JSON pointers.
For example if the resource is {"parent":{"child":"value"}},
parent/child refers to the "child":"value".

If the field is left blank, the server returns all default
values.

_mimeType=mime-type

Some resources have fields whose values are multi-media resources
such as a profile photo for example.

By specifying both a single field
and also the mime-type for the response content,
you can read a single field value that is a multi-media resource.

In this case, the content type of the field value returned
matches the mime-type that you specify,
and the body of the response is the multi-media resource.

The Accept header is not used in this case.
For example, Accept: image/png does not work.
Use the _mimeType query string parameter instead.

A.2.8. Update

To update a resource, perform an HTTP PUT
including the case-sensitive identifier (_id)
as the final element of the path to the resource,
and the JSON resource as the payload.
Use the If-Match: _rev header
to check that you are actually updating the version you modified.
Use If-Match: * if the version does not matter.
Accept a JSON response:

When updating a resource, include all the attributes to be retained.
Omitting an attribute in the resource amounts to deleting the attribute
unless it is not under the control of your application.
Attributes not under the control of your application include
private and read-only attributes.
In addition, virtual attributes and relationship references
might not be under the control of your application.

Parameters

You can use the following parameters:

_prettyPrint=true

Format the body of the response.

_fields=field[,field...]

Return only the specified fields in the body of the response.

The field values are JSON pointers.
For example if the resource is {"parent":{"child":"value"}},
parent/child refers to the "child":"value".

If the field is left blank, the server returns all default
values.

A.2.9. Delete

To delete a single resource, perform an HTTP DELETE
by its case-sensitive identifier (_id)
and accept a JSON response:

list semantics array, where the
elements are ordered, and duplicates are allowed.

set semantics array, where the elements
are not ordered, and duplicates are not allowed.

ForgeRock PATCH supports several different operations.
The following sections show each of these operations, along with options
for the field and value:

A.2.10.1. Patch Operation: Add

The add operation ensures that the target field contains
the value provided, creating parent fields as necessary.

If the target field is single-valued, then the value you include in the
PATCH replaces the value of the target. Examples of a single-valued field
include: object, string, boolean, or number.

An add operation has different results on two standard
types of arrays:

List semantic arrays: you can run
any of these add operations on that type of array:

If you add an array of values, the PATCH operation
appends it to the existing list of values.

If you add a single value, specify an ordinal
element in the target array, or use the {-} special
index to add that value to the end of the list.

Set semantic arrays: The list of values
included in a patch are merged with the existing set of values. Any
duplicates within the array are removed.

As an example, start with the following list semantic array resource:

{
"fruits" : [ "orange", "apple" ]
}

The following add operation includes the pineapple to the end of the list of
fruits, as indicated by the - at the end of the
fruits array.

{
"operation" : "add",
"field" : "/fruits/-",
"value" : "pineapple"
}

The following is the resulting resource:

{
"fruits" : [ "orange", "apple", "pineapple" ]
}

A.2.10.2. Patch Operation: Copy

The copy operation takes one or more existing values from the source field.
It then adds those same values on the target field. Once the values are
known, it is equivalent to performing an add operation
on the target field.

The following copy operation takes the value from a field
named mail, and then runs a replace
operation on the target field, another_mail.

[
{
"operation":"copy",
"from":"mail",
"field":"another_mail"
}
]

If the source field value and the target field value are configured as
arrays, the result depends on whether the array has list semantics or set
semantics, as described in "Patch Operation: Add".

A.2.10.3. Patch Operation: Increment

The increment operation changes the value or values of
the target field by the amount you specify. The value that you include
must be one number, and may be positive or negative. The value of the
target field must accept numbers. The following increment
operation adds 1000 to the target value of
/user/payment.

Since the value of the increment is
a single number, arrays do not apply.

A.2.10.4. Patch Operation: Move

The move operation removes existing values on the source field. It
then adds those same values on the target field. It is equivalent to
performing a remove operation on the source, followed
by an add operation with the same values, on the target.

The following move operation is equivalent to a
remove operation on the source field,
surname, followed by a replace
operation on the target field value, lastName. If the
target field does not exist, it is created.

[
{
"operation":"move",
"from":"surname",
"field":"lastName"
}
]

To apply a move operation on an array, you need a
compatible single-value, list semantic array, or set semantic array on
both the source and the target. For details, see the criteria described
in "Patch Operation: Add".

A.2.10.5. Patch Operation: Remove

The remove operation ensures that the target field no
longer contains the value provided. If the remove operation does not include
a value, the operation removes the field. The following
remove deletes the value of the
phoneNumber, along with the field.

[
{
"operation" : "remove",
"field" : "phoneNumber"
}
]

If the object has more than one phoneNumber, those
values are stored as an array.

A remove operation has different results on two standard
types of arrays:

List semantic arrays: A
remove operation deletes the specified element in the
array. For example, the following operation removes the first phone
number, based on its array index (zero-based):

[
{
"operation" : "remove",
"field" : "/phoneNumber/0"
}
]

Set semantic arrays: The list of values
included in a patch are removed from the existing array.

A.2.10.6. Patch Operation: Replace

The replace operation removes any existing value(s) of
the targeted field, and replaces them with the provided value(s). It is
essentially equivalent to a remove followed by a
add operation. If the arrays are used, the criteria is
based on "Patch Operation: Add". However, indexed updates are
not allowed, even when the target is an array.

The following replace operation removes the existing
telephoneNumber value for the user, and then adds the
new value of +1 408 555 9999.

A PATCH replace operation on a list semantic array works in the same
fashion as a PATCH remove operation. The following example demonstrates
how the effect of both operations. Start with the following resource:

The PATCH operations are applied sequentially. The remove
operation removes the first member of that resource, based on its array
index, (fruits/0), with the following result:

[
{
"fruits" : [ "orange", "kiwi", "lime" ],
}
]

The second PATCH operation, a replace, is applied on the
second member (fruits/1) of the intermediate resource,
with the following result:

[
{
"fruits" : [ "orange", "pineapple", "lime" ],
}
]

A.2.10.7. Patch Operation: Transform

The transform operation changes the value of a field
based on a script or some other data transformation command. The following
transform operation takes the value from the field
named /objects, and applies the
something.js script as shown:

A.2.10.8. Patch Operation Limitations

Some HTTP client libraries do not support the HTTP PATCH operation.
Make sure that the library you use supports HTTP PATCH
before using this REST operation.

For example, the Java Development Kit HTTP client does not support
PATCH as a valid HTTP method. Instead, the method
HttpURLConnection.setRequestMethod("PATCH")
throws ProtocolException.

Parameters

You can use the following parameters.
Other parameters might depend on the specific action implementation:

_prettyPrint=true

Format the body of the response.

_fields=field[,field...]

Return only the specified fields in the body of the response.

The field values are JSON pointers.
For example if the resource is {"parent":{"child":"value"}},
parent/child refers to the "child":"value".

If the field is left blank, the server returns all default
values.

A.2.11. Action

Actions are a means of extending Common REST APIs
and are defined by the resource provider,
so the actions you can use depend on the implementation.

The standard action indicated by _action=create
is described in "Create".

Parameters

You can use the following parameters.
Other parameters might depend on the specific action implementation:

_prettyPrint=true

Format the body of the response.

_fields=field[,field...]

Return only the specified fields in the body of the response.

The field values are JSON pointers.
For example if the resource is {"parent":{"child":"value"}},
parent/child refers to the "child":"value".

If the field is left blank, the server returns all default
values.

A.2.12. Query

To query a resource collection
(or resource container if you prefer to think of it that way),
perform an HTTP GET and accept a JSON response, including at least
a _queryExpression,
_queryFilter, or _queryId parameter.
These parameters cannot be used together:

JsonValue components of filter expressions follow
RFC 7159: The JavaScript Object Notation (JSON)
Data Interchange Format.
In particular, as described in section 7 of the RFC,
the escape character in strings is the backslash character.
For example, to match the identifier test\,
use _id eq 'test\\'.
In the JSON resource, the \ is escaped the same way:
"_id":"test\\".

When using a query filter in a URL,
be aware that the filter expression is part of a query string parameter.
A query string parameter must be URL encoded as described in
RFC 3986: Uniform Resource Identifier (URI):
Generic Syntax
For example, white space, double quotes ("), parentheses,
and exclamation characters need URL encoding in HTTP query strings.
The following rules apply to URL query components:

As a result, a backslash escape character
in a JsonValue component
is percent-encoded in the URL query string parameter as %5C.
To encode the query filter expression _id eq 'test\\',
use _id+eq+'test%5C%5C', for example.

A simple filter expression can represent a comparison, presence,
or a literal value.

For comparison expressions use
json-pointer comparator json-value,
where the comparator is one of the following:

Specific queries can take their own query string parameter arguments,
which depend on the implementation.

_pagedResultsCookie=string

The string is an opaque cookie used by the server
to keep track of the position in the search results.
The server returns the cookie in the JSON response
as the value of pagedResultsCookie.

In the request _pageSize must also be set and non-zero.
You receive the cookie value from the provider on the first request,
and then supply the cookie value in subsequent requests
until the server returns a null cookie,
meaning that the final page of results has been returned.

The _pagedResultsCookie parameter is supported
when used with the _queryFilter parameter.
The _pagedResultsCookie parameter
is not guaranteed to work when used with the
_queryExpression and _queryId parameters.

The _pagedResultsCookie
and _pagedResultsOffset parameters
are mutually exclusive, and not to be used together.

_pagedResultsOffset=integer

When _pageSize is non-zero,
use this as an index in the result set indicating the first page to return.

The _pagedResultsCookie
and _pagedResultsOffset parameters
are mutually exclusive, and not to be used together.

_pageSize=integer

Return query results in pages of this size.
After the initial request, use
_pagedResultsCookie or _pageResultsOffset
to page through the results.

_totalPagedResultsPolicy=string

When a _pageSize is specified, and non-zero, the server
calculates the "totalPagedResults", in accordance with the
totalPagedResultsPolicy, and provides the value as part
of the response. The "totalPagedResults" is either an estimate of the total
number of paged results (_totalPagedResultsPolicy=ESTIMATE),
or the exact total result count (_totalPagedResultsPolicy=EXACT).
If no count policy is specified in the query, or if
_totalPagedResultsPolicy=NONE, result counting is
disabled, and the server returns value of -1 for "totalPagedResults".

_sortKeys=[+-]field[,[+-]field...]

Sort the resources returned based on the specified field(s),
either in + (ascending, default) order,
or in - (descending) order.

Because ascending order is the default, including the +
character in the query is unnecessary. If you do include the
+, it must be URL-encoded as %2B,
for example:

The _sortKeys parameter is not supported
for predefined queries (_queryId).

_prettyPrint=true

Format the body of the response.

_fields=field[,field...]

Return only the specified fields in each element
of the "results" array in the response.

The field values are JSON pointers.
For example if the resource is {"parent":{"child":"value"}},
parent/child refers to the "child":"value".

If the field is left blank, the server returns all default
values.

A.2.13. HTTP Status Codes

When working with a Common REST API over HTTP,
client applications should expect at least the following HTTP status codes.
Not all servers necessarily return all status codes identified here:

200 OK

The request was successful and a resource returned, depending on the request.

201 Created

The request succeeded and the resource was created.

204 No Content

The action request succeeded, and there was no content to return.

304 Not Modified

The read request included an If-None-Match header,
and the value of the header matched the revision value of the resource.

400 Bad Request

The request was malformed.

401 Unauthorized

The request requires user authentication.

403 Forbidden

Access was forbidden during an operation on a resource.

404 Not Found

The specified resource could not be found, perhaps because it does not exist.

405 Method Not Allowed

The HTTP method is not allowed for the requested resource.

406 Not Acceptable

The request contains parameters that are not acceptable,
such as a resource or protocol version that is not available.

409 Conflict

The request would have resulted in a conflict
with the current state of the resource.

410 Gone

The requested resource is no longer available,
and will not become available again.
This can happen when resources expire for example.

412 Precondition Failed

The resource's current version does not match the version provided.

415 Unsupported Media Type

The request is in a format not supported
by the requested resource for the requested method.

428 Precondition Required

The resource requires a version, but no version was supplied in the request.

500 Internal Server Error

The server encountered an unexpected condition
that prevented it from fulfilling the request.

501 Not Implemented

The resource does not support the functionality
required to fulfill the request.

503 Service Unavailable

The requested resource was temporarily unavailable.
The service may have been disabled, for example.

A.3. Cross-Site Request Forgery (CSRF) Protection

AM includes a global filter to harden AM's protection
against CSRF attacks. The filter applies to all REST endpoints under
json/ and requires that all requests other than GET, HEAD,
or OPTIONS include, at least, one of the following headers:

X-Requested-With

This header is often sent by Javascript frameworks, and the XUI already
sends it on all requests.

Accept-API-Version

This header specifies which version of the REST API to use. Use this header
in your requests to ensure future changes to the API do not affect your clients.

The json/ endpoint is not vulnerable to CSRF attacks
when the filter is disabled, since it requires the
"Content-Type: application/json" header, which currently
triggers the same protection in browsers. This may change in the future, so it is
recommended to enable the CSRF filter.

A.4. REST API Versioning

In OpenAM 12.0.0 and later, REST API features are assigned version numbers.

Providing version numbers in the REST API helps ensure compatibility
between releases. The version number of a feature increases when AM
introduces a non-backwards-compatible change that affects clients making use
of the feature.

AM provides versions for the following aspects of the REST API.

resource

Any changes to the structure or syntax of a returned response will incur
a resource version change. For example changing
errorMessage to message in a
JSON response.

protocol

Any changes to the methods used to make REST API calls will incur
a protocol version change. For example changing
_action to $action in the required
parameters of an API feature.

To ensure your clients are always compatible with a newer version of AM,
you should always include resource versions in your REST calls.

A.4.1. Supported REST API Versions

The REST API version numbers supported in
AM 6
are as follows:

Supported protocol versions

The protocol versions supported in AM 6
are:

1.0

Supported resource versions

The resource versions supported in AM 6
are shown in the following table.

Supported resource Versions

Base

End Point

Supported Versions

/json

/authenticate

1.1, 2.0

/users

1.1, 1.2, 2.0, 2.1, 3.0

/groups

1.1, 2.0, 2.1, 3.0

/agents

1.1, 2.0, 2.1, 3.0

/realms

1.0

/dashboard

1.0

/sessions

1.2, 2.1, 3.1

/serverinfo/*

1.1

/users/{user}/devices/trusted

1.0

/users/{user}/uma/policies

1.0

/applications

1.0, 2.0

/resourcetypes

1.0

/policies

1.0, 2.0

/applicationtypes

1.0

/conditiontypes

1.0

/subjecttypes

1.0

/subjectattributes

1.0

/decisioncombiners

1.0

/subjectattributes

1.0

/xacml

/policies

1.0

/frrest

/token

1.0

/client

1.0

For information about the supported protocol and resource versions
available in AM 6, see the
API Explorer in the Development Guide
available in the AM console.

If the default REST API version behavior is set to None,
and a REST API call does not include the Accept-API-Version
header, or does not specify a resource version, then a
400 Bad Request status code is returned,
as shown below:

Tip

A.5. Specifying Realms in REST API Calls

This section describes how to work with realms when
making REST API calls to AM.

Realms can be specified in the following ways when making a REST API call to
AM:

DNS Alias

When making a REST API call, the DNS alias of a realm can be
specified in the subdomain and domain name components of the REST endpoint.

To list all users in the top-level realm use the DNS alias of the
AM instance, for example the REST endpoint would be:

https://openam.example.com:8443/openam/json/users?_queryId=*

To list all users in a realm with DNS alias
suppliers.example.com the REST endpoint would be:

https://suppliers.example.com:8443/openam/json/users?_queryId=*

Path

When making a REST API call, specify the realm in the path component of the
endpoint. You must specify the entire hierarchy of the realm, starting at the top-level realm.
Prefix each realm in the hierarchy with the realms/ keyword. For example
/realms/root/realms/customers/realms/europe.

To authenticate a user in the top-level realm, use the root
keyword. For example:

https://openam.example.com:8443/openam/json/realms/root/authenticate

To authenticate a user in a subrealm named customers within the
top-level realm, the REST endpoint would be:

A.6. Authentication and Logout

You can use REST-like APIs under /json/authenticate and
/json/sessions for authentication and for logout.

The /json/authenticate endpoint does not support the
CRUDPAQ verbs and therefore does not technically satisfy REST architectural
requirements. The term REST-like describes this
endpoint better than REST.

The simplest user name/password authentication returns a
tokenId that applications can present as a cookie
value for other operations that require authentication. The type of
tokenId returned varies depending on whether client-based
sessions are enabled in the realm to which the user authenticates:

If client-based sessions are not enabled, the tokenId
is an AM SSO token.

If client-based sessions are enabled, the tokenId is
an AM SSO token that includes an encoded AM session.

Developers should be aware that the size of the tokenId
for client-based sessions—2000 bytes or greater—is
considerably longer than for CTS-based sessions—approximately 100 bytes.
For more information about session tokens,
see "Session Cookies" in the Authentication and Single Sign-On Guide.

When authenticating with a user name and password, use
HTTP POST to prevent the web container from logging the credentials.
Pass the user name in an X-OpenAM-Username header, and
the password in an X-OpenAM-Password header:

This zero page login mechanism works only for name/password
authentication. If you include a POST body with the request, it must
be an empty JSON string as shown in the example. Alternatively, you can
leave the POST body empty. Otherwise, AM interprets the body as a
continuation of an existing authentication attempt, one that uses a
supported callback mechanism.

The authentication service at /json/authenticate
supports callback mechanisms that make it possible to perform other types of
authentication in addition to simple user name/password login.

Callbacks that are not completed based on the content of the client
HTTP request are returned in JSON as a response to the request. Each
callback has an array of output suitable for displaying to the end user,
and input which is what the client must complete and send back to
AM. The default is still user name/password authentication:

AM can be configured to return a failure URL value when
authentication fails. No failure URL is configured by default. The Default
Failure Login URL can be set per realm; see
"Post Authentication Processing" in the Authentication and Single Sign-On Guide
for details. Alternatively, failure URLs can be configured per authentication
chain, which your client can specify using the service
parameter described below. On failure AM then returns HTTP status
code 401 Unauthorized, and the JSON in the reply indicates the failure
URL:

When making a REST API call, specify the realm in the path component of the
endpoint. You must specify the entire hierarchy of the realm, starting at the top-level realm.
Prefix each realm in the hierarchy with the realms/ keyword. For example
/realms/root/realms/customers/realms/europe.

For example, to authenticate to a subrealm customers within the
top-level realm, then the authentication endpoint URL is as follows:
https://openam.example.com:8443/openam/json/realms/root/realms/customers/authenticate

The following additional parameters are supported:

You can use the authIndexType and
authIndexValue query string parameters as a pair
to provide additional information about how you are authenticating.
The authIndexType can be one of the following
types:

composite

Set the value to a composite advice string.

level

Set the value to the authentication level.

module

Set the value to the name of an authentication module.

resource

Set the value to a URL protected by an AM policy.

role

Set the value to an AM role.

service

Set the value to the name of an authentication tree or authentication chain.

user

Set the value to an AM user ID.

For example, to log into AM using the built-in ldapService authentication
chain, you could use the following:

You can use the query string parameter,
sessionUpgradeSSOTokenId=tokenId,
to request session upgrade.
Before the tokenId is searched for in the
query string for session upgrade, the token is grabbed from the cookie.
For an explanation of session upgrade,
see "Session Upgrade" in the Authentication and Single Sign-On Guide.

AM uses the following callback types depending on the
authentication module in use:

ChoiceCallback:
Used to display a list of choices and retrieve the selected choice.

ConfirmationCallback:
Used to ask for a confirmation such as Yes, No, or Cancel and retrieve
the selection.

HiddenValueCallback:
Used to return form values that are not visually rendered to the end user.

HttpCallback:
Used for HTTP handshake negotiations.

LanguageCallback:
Used to retrieve the locale for localizing text presented to the end user.

NameCallback:
Used to retrieve a name string.

PasswordCallback:
Used to retrieve a password value.

PollingWaitCallback:
Used to restrict polling requests by specifying an amount of time to wait before responding.

RedirectCallback:
Used to redirect the client user-agent.

ScriptTextOutputCallback:
Used to insert a script into the page presented to the end user.
The script can, for example, collect data about the user's environment.

TextInputCallback:
Used to retrieve text input from the end user.

TextOutputCallback:
Used to display a message to the end user.

X509CertificateCallback:
Used to retrieve the content of an x.509 certificate.

A.6.1. Logout

Authenticated users can log out with the token cookie value and an HTTP
POST to /json/sessions/?_action=logout:

A.6.3. Load Balancer and Proxy Layer Requirements

When authentication depends on the client IP address and AM lies behind
a load balancer or proxy layer, configure the load balancer or proxy to send
the address by using the X-Forwarded-For header, and
configure AM to consume and forward the header as necessary. For
details, see
"Handling HTTP Request Headers" in the Installation Guide.

A.6.4. Windows Desktop SSO Requirements

When authenticating with Windows Desktop SSO, add an
Authorization header containing the string
Basic , followed by a base64-encoded string of the
username, a colon character, and the password. In the following example, the
credentials demo:changeit are base64-encoded into the
string ZGVtbzpjaGFuZ2VpdA==:

The returned tokenID is known as a session token
(also referred to as an SSO token). REST API calls made after successful
authentication to AM must present the session token in the HTTP header
as proof of authentication.

Next, call one or more additional REST APIs on behalf of the logged-in
user. Each REST API call passes the user's tokenID back
to AM in the HTTP header as proof of previous authentication.

The following is a partial example of
a curl command that inserts the token ID
returned from a prior successful AM authentication attempt into the
HTTP header:

Observe that the session token is inserted into a header field named
iPlanetDirectoryPro. This header field name must
correspond to the name of the AM session cookie—by
default, iPlanetDirectoryPro. You can find the
cookie name in the AM console by navigating to Deployment > Servers >
Server Name > Security > Cookie, in the
Cookie Name field of the AM console.

Once a user has authenticated, it is not
necessary to insert login credentials in the HTTP header in subsequent
REST API calls. Note the absence
of X-OpenAM-Username and
X-OpenAM-Password headers in the preceding example.

Users are required to have appropriate privileges in order to
access AM functionality using the REST API. For example,
users who lack administrative privileges cannot create AM realms.
For more information on the AM privilege model,
see "Delegating Realm Administration Privileges" in the Setup and Maintenance Guide.

Finally, call the REST API to log the user out of AM as described
in "Authentication and Logout". As with
other REST API calls made after a user has authenticated, the REST API call
to log out of AM requires the user's tokenID
in the HTTP header.

A.8. Server Information

You can retrieve AM server information by using HTTP GET on
/json/serverinfo/* as follows:

A.9. Token Encoding

Valid tokens in AM requires configuration either in percent encoding or in C66Encode
format. C66Encode format is encouraged. It is the default token format for
AM, and is used in this section.
The following is an example token that has not been encoded:

AQIC5wM2LY4SfczntBbXvEAOuECbqMY3J4NW3byH6xwgkGE=@AAJTSQACMDE=#

This token includes reserved characters such as +, /,
and = (The @, #, and * are not
reserved characters per se, but substitutions are still required). To c66encode this token,
you would substitute certain characters for others, as follows:

+ is replaced with -

/ is replaced with _

= is replaced with .

@ is replaced with *

# is replaced with *

* (first instance) is replaced with @

* (subsequent instances) is replaced with #

In this case, the translated token would appear as shown here:

AQIC5wM2LY4SfczntBbXvEAOuECbqMY3J4NW3byH6xwgkGE.*AAJTSQACMDE.*

A.10. Logging

AM 6 supports two Audit Logging Services: a new
common REST-based Audit Logging Service, and the legacy Logging Service,
which is based on a Java SDK and is available in AM versions prior to
OpenAM 13. The legacy Logging Service is deprecated.

Both audit facilities log AM REST API calls.

A.10.1. Common Audit Logging of REST API Calls

AM logs information about all REST API calls to the
access topic. For more information about AM audit
topics, see "Audit Log Topics" in the Setup and Maintenance Guide.

Locate specific REST endpoints in the http.path log file
property.

A.10.2. Legacy Logging of REST API Calls

AM logs information about REST API calls to two files:

amRest.access. Records accesses
to a
CREST endpoint, regardless of whether the request successfully reached the
endpoint through policy authorization.

amRest.authz. Records all CREST
authorization results regardless of success. If a request has an entry in the
amRest.access log, but no corresponding entry in
amRest.authz, then that
endpoint was not protected by an authorization filter and therefore the
request was granted access to the resource.

The amRest.authz file contains the
Data field, which specifies the authorization decision,
resource, and type of action performed on that resource.
The Data field has the following syntax:

("GRANT"||"DENY") > "RESOURCE | ACTION"
where
"GRANT > " is prepended to the entry if the request was allowed
"DENY > " is prepended to the entry if the request was not allowed
"RESOURCE" is "ResourceLocation | ResourceParameter"
where
"ResourceLocation" is the endpoint location (e.g., subrealm/applicationtypes)
"ResourceParameter" is the ID of the resource being touched
(e.g., myApplicationType) if applicable. Otherwise, this field is empty
if touching the resource itself, such as in a query.
"ACTION" is "ActionType | ActionParameter"
where
"ActionType" is "CREATE||READ||UPDATE||DELETE||PATCH||ACTION||QUERY"
"ActionParameter" is one of the following depending on the ActionType:
For CREATE: the new resource ID
For READ: empty
For UPDATE: the revision of the resource to update
For DELETE: the revision of the resource to delete
For PATCH: the revision of the resource to patch
For ACTION: the actual action performed (e.g., "forgotPassword")
For QUERY: the query ID if any

AM also provides additional information in its debug notifications for
accesses to any endpoint,
depending on the message type (error, warning or message) including realm,
user, and result of the operation.

A.11. Reference

This reference section covers return codes and system settings relating to
REST API support in AM.

A.11.1. REST APIs

amster service name: rest

The following settings are available in this service:

Default Resource Version

The API resource version to use when the REST request does not specify an explicit version. Choose from:

Latest. If an explicit version is not specified, the latest resource version of an API is used.

Oldest. If an explicit version is not specified, the oldest supported resource version of an API is used. Note that since APIs may be deprecated and fall out of support, the oldest supported version may not be the first version.

None. If an explicit version is not specified, the request will not be handled and an error status is returned.

The possible values for this property are:

Latest

Oldest

None

Default value:
Latest

amster attribute:
defaultVersion

Warning Header

Whether to include a warning header in the response to a request which fails to include the Accept-API-Version header.

Default value:
false

amster attribute:
warningHeader

API Descriptions

Whether API Explorer and API Docs are enabled in OpenAM and how the documentation for them is generated. Dynamic generation includes descriptions from any custom services and authentication modules you may have added. Static generation only includes services and authentication modules that were present when OpenAM was built. Note that dynamic documentation generation may not work in some application containers.

The possible values for this property are:

DYNAMIC. Enabled with Dynamic Documentation

STATIC. Enabled with Static Documentation

DISABLED

Default value:
STATIC

amster attribute:
descriptionsState

Default Protocol Version

The API protocol version to use when a REST request does not specify an explicit version. Choose from:

Oldest. If an explicit version is not specified, the oldest protocol version is used.

Latest. If an explicit version is not specified, the latest protocol version is used.

None. If an explicit version is not specified, the request will not be handled and an error status is returned.

The possible values for this property are:

Oldest

Latest

None

Default value:
Latest

amster attribute:
defaultProtocolVersion

Enable CSRF Protection

If enabled, all non-read/query requests will require the X-Requested-With header to be present.

Requiring a non-standard header ensures requests can only be made via methods (XHR) that have stricter same-origin policy protections in Web browsers, preventing Cross-Site Request Forgery (CSRF) attacks. Without this filter, cross-origin requests are prevented by the use of the application/json Content-Type header, which is less robust.

Default value:
true

amster attribute:
csrfFilterEnabled

Appendix B. About Scripting

You can use scripts for client-side and server-side authentication,
policy conditions, and handling OpenID Connect claims.

B.1. The Scripting Environment

You can use scripts to modify default AM behavior in the
following situations, also known as contexts:

Client-side Authentication

Scripts that are executed on the client during authentication.
Client-side scripts must be in JavaScript.

Server-side Authentication

Scripts are included in an authentication module and are
executed on the server during authentication.

Policy Condition

Scripts used as conditions within policies.

OIDC Claims

Scripts that gather and populate the claims in a request when
issuing an ID token or making a request to the
userinfo endpoint.

AM implements a configurable scripting engine for each of the
context types that are executed on the server.

The scripting engines in AM have two main components: security
settings, and the thread pool.

B.1.1. Security

AM scripting engines provide security features for ensuring that
malicious Java classes are not directly called. The engines validate
scripts by checking all directly-called Java
classes against a configurable blacklist and whitelist, and, optionally,
against the JVM SecurityManager, if it is configured.

Whitelists and blacklists contain class names that
are allowed or denied execution respectively. Specify classes in
whitelists and blacklists by name or by using regular expressions.

Classes called by the script are checked against the whitelist
first, and must match at least one pattern in the list. The
blacklist is applied after the whitelist, and classes matching any
pattern are disallowed.

You can also configure the scripting engine to make an additional
call to the JVM security manager for each class that is accessed. The
security manager throws an exception if a class being called is not
allowed to execute.

For more information on configuring script engine security,
see "Scripting".

Important Points About Script Engine Security

The following points should be considered when configuring the
security settings within each script engine:

The scripting engine only validates directly accessible classes.

The security settings only apply to classes that the script
directly accesses. If the script calls
Foo.a() and then that method
calls Bar.b(), the scripting engine will be unable
to prevent it. You must consider the whole chain of accessible classes.

Note

Access includes actions such as:

Importing or loading a class.

Accessing any instance of that class. For example, passed as a
parameter to the script.

Calling a static method on that class.

Calling a method on an instance of that class.

Accessing a method or field that returns an instance of that
class.

Potentially dangerous Java classes are blacklisted by default.

All Java reflection classes (java.lang.Class,
java.lang.reflect.*)
are blacklisted by default to avoid bypassing the security settings.

The java.security.AccessController class is
also blacklisted by default to prevent access to the
doPrivileged() methods.

Caution

You should not remove potentially dangerous Java classes from the blacklist.

The whitelists and blacklists match class or package names only.

The whitelist and blacklist patterns apply only to the exact class
or package names involved. The script engine does not know anything
about inheritance, so it is best to whitelist known, specific classes.

B.1.2. Thread Pools

Each script is executed in an individual thread. Each scripting
engine starts with an initial number of threads available for executing
scripts. If no threads are available for execution, AM creates
a new thread to execute the script, until the configured maximum number
of threads is reached.

If the maximum number of threads is reached, pending script
executions are queued in a number of buffer threads, until a thread
becomes available for execution. If a created thread has completed script
execution and has remained idle for a configured amount of time, AM terminates
the thread, shrinking the pool.

For more information on configuring script engine thread pools, see
"Scripting".

B.2. Global Scripting API Functionality

This section covers functionality available to each of the
server-side script types.

B.2.1. Accessing HTTP Services

Configure the parameters for the HTTP client object by using the
org.forgerock.http.protocol package. This package contains the
Request class, which has methods for setting the URI and type of request.

The following example, taken from the default server-side Scripted authentication
module script, uses these methods to call an online API to determine the longitude and
latitude of a user based on their postal address:

HTTP client requests are synchronous and blocking until they return.
You can, however, set a global timeout for server-side scripts.
For details, see
"Scripted Authentication Module Properties" in the Authentication and Single Sign-On Guide.

Server-side scripts can access response data by using the methods
listed in the table below.

HTTP Client Response Methods

Method

Parameters

Return Type

Description

HttpClientResponse.getCookies

Void

Map<String, String>

Get the cookies for the returned response, if any exist.

HttpClientResponse.getEntity

Void

String

Get the entity of the returned response.

HttpClientResponse.getHeaders

Void

Map<String, String>

Get the headers for the returned response, if any exist.

HttpClientResponse.getReasonPhrase

Void

String

Get the reason phrase of the returned response.

HttpClientResponse.getStatusCode

Void

Integer

Get the status code of the returned response.

HttpClientResponse.hasCookies

Void

Boolean

Indicate whether the returned response had any cookies.

HttpClientResponse.hasHeaders

Void

Boolean

Indicate whether the returned response had any headers.

B.2.2. Debug Logging

Server-side scripts can write messages to AM debug logs
by using the logger object.

AM does not log debug messages from scripts by default.
You can configure AM to log such messages
by setting the debug log level for the amScript service.
For details, see
"Debug Logging By Service" in the Setup and Maintenance Guide.

B.3. Managing Scripts

This section shows you how to manage scripts used for client-side and
server-side scripted authentication, custom policy conditions, and handling
OpenID Connect claims using the AM console, the ssoadm
command, and the REST API.

B.3.1. Managing Scripts With the AM Console

The following procedures describe how to create, modify, and delete scripts
using the AM console:

User-created scripts are realm-specific, hence the URI for the scripts' API
can contain a realm component, such as
/json{/realm}/scripts.
If the realm is not specified in the URI, the top level realm is
used.

Tip

AM includes some global example scripts that can be
used in any realm.

Scripts are represented in JSON and take the following form.
Scripts are built from standard JSON objects and values
(strings, numbers, objects, sets, arrays, true,
false, and null). Each script
has a system-generated universally unique
identifier (UUID), which must be used when modifying
existing scripts. Renaming a script will not affect the UUID:

B.3.2.3. Validating a Script

To validate a script, perform an HTTP POST using the
/json{/realm}/scripts
endpoint, with an _action parameter
set to validate. Include a JSON representation of the
script and the script language, JAVASCRIPT or
GROOVY, in the POST data.

The value for script must be in UTF-8 format and
then encoded into Base64.

The iPlanetDirectoryPro header is required and should
contain the SSO token of an administrative user, such as amAdmin, who
has access to perform the operation.

B.3.2.5. Updating a Script

To update an individual script in a realm, perform an HTTP
PUT using the /json{/realm}/scripts
endpoint, specifying the UUID in both the URL and the PUT body.
Include a JSON representation of the updated script in the PUT
data, alongside the UUID.

Note

If the realm is not specified in the URL, AM uses the top
level realm.

The iPlanetDirectoryPro header is required and should
contain the SSO token of an administrative user, such as amAdmin, who
has access to perform the operation.

Note

The maximum execution time any individual script should take on
the server (in seconds). OpenAM terminates scripts which take
longer to run than this value.

ssoadm attribute:
serverTimeout

Core thread pool size

The initial number of threads in the thread pool from
which scripts operate. OpenAM will ensure the pool contains at least
this many threads.

ssoadm attribute:
coreThreads

Maximum thread pool size

The maximum number of threads in the thread pool from which
scripts operate. If no free thread is available in the pool, OpenAM
creates new threads in the pool for script execution up to the
configured maximum.

ssoadm attribute:
maxThreads

Thread pool queue size

The number of threads to use for buffering script execution
requests when the maximum thread pool size is reached.

ssoadm attribute:
queueSize

Thread idle timeout (seconds)

Length of time (in seconds) for a thread to be idle before OpenAM
terminates created threads. If the current pool size contains the
number of threads set in Core thread pool size
idle threads will not be terminated, to maintain the initial pool size.

ssoadm attribute:
idleTimeout

Java class whitelist

Specifies the list of class-name patterns allowed to be invoked
by the script. Every class accessed by the script must match at least
one of these patterns.

You can specify the class name as-is or use a
regular expression.

ssoadm attribute:
whiteList

Java class blacklist

Specifies the list of class-name patterns that are NOT allowed
to be invoked by the script. The blacklist is applied AFTER the
whitelist to exclude those classes - access to a class
specified in both the whitelist and the blacklist will be denied.

You can specify the class name to exclude as-is or use a
regular expression.

ssoadm attribute:
blackList

Use system SecurityManager

If enabled, OpenAM will make a call to
System.getSecurityManager().checkPackageAccess(...) for each
class that is accessed. The method throws SecurityException if
the calling thread is not allowed to access the package.

Note

This feature only takes effect if the security manager is
enabled for the JVM.

ssoadm attribute:
useSecurityManager

Scripting languages

Select the languages available for scripts on the chosen type.
Either GROOVY or JAVASCRIPT.

ssoadm attribute:
languages

Default Script

The source code that is presented as the default when creating a
new script of this type.

ssoadm attribute:
defaultScript

Appendix C. Getting Support

For more information or resources about AM and ForgeRock Support, see
the following sections:

C.1. Accessing Documentation Online

ForgeRock publishes comprehensive documentation online:

The ForgeRock
Knowledge Base
offers a large and increasing number of up-to-date, practical articles
that help you deploy and manage ForgeRock software.

While many articles are visible to community members,
ForgeRock customers have access to much more,
including advanced information for customers using ForgeRock software
in a mission-critical capacity.

ForgeRock product documentation, such as this document,
aims to be technically accurate and complete
with respect to the software documented.
It is visible to everyone and covers all product features
and examples of how to use them.

C.2. Using the ForgeRock.org Site

The
ForgeRock.org site
has links to source code for ForgeRock open source software,
as well as links to the ForgeRock forums and technical blogs.

If you are a ForgeRock customer,
raise a support ticket instead of using the forums.
ForgeRock support professionals will get in touch to help you.

C.3. Getting Support and Contacting ForgeRock

ForgeRock provides support services, professional services, training through
ForgeRock University, and partner services to assist you in setting up and
maintaining your deployments.
For a general overview of these services, see
https://www.forgerock.com.

Access control that is based on attributes of a user, such as how old
a user is or whether the user is a paying customer.

Authentication

The act of confirming the identity of a principal.

Authentication chaining

A series of authentication modules configured together which a
principal must negotiate as configured in order to authenticate
successfully.

Authentication level

Positive integer associated with an authentication module, usually
used to require success with more stringent authentication measures when
requesting resources requiring special protection.

Authentication module

AM authentication unit that handles one way of obtaining and
verifying credentials.

Authorization

The act of determining whether to grant or to deny a principal access
to a resource.

Authorization Server

In OAuth 2.0, issues access tokens to the client after authenticating
a resource owner and confirming that the owner authorizes the client to
access the protected resource. AM can play this role in the OAuth 2.0
authorization framework.

Auto-federation

Arrangement to federate a principal's identity automatically based
on a common attribute value shared across the principal's profiles at
different providers.

Bulk federation

Batch job permanently federating user profiles between a service
provider and an identity provider based on a list of matched user
identifiers that exist on both providers.

Circle of trust

Group of providers, including at least one identity provider, who
have agreed to trust each other to participate in a SAML v2.0 provider
federation.

Client

In OAuth 2.0, requests protected web resources on behalf of the
resource owner given the owner's authorization. AM can play this role
in the OAuth 2.0 authorization framework.

Client-based sessions

AM sessions
for which AM returns session state to the client after each request,
and require it to be passed in with the subsequent request. For browser-based
clients, AM sets a cookie in the browser that contains the session
information.

For browser-based clients, AM sets a
cookie in the browser that contains the session state. When the browser
transmits the cookie back to AM, AM decodes the session state from
the cookie.

Conditions

Defined as part of policies,
these determine the circumstances under which which a policy applies.

Environmental conditions reflect circumstances like
the client IP address, time of day, how the subject authenticated,
or the authentication level achieved.

Subject conditions reflect characteristics of the subject like
whether the subject authenticated, the identity of the subject,
or claims in the subject's JWT.

Configuration datastore

LDAP directory service holding AM configuration data.

Cross-domain single sign-on (CDSSO)

AM capability allowing single sign-on across different DNS
domains.

CTS-based sessions

AM sessions
that reside in the Core Token Service's token store.
CTS-based sessions might also be cached in memory on one or more AM
servers. AM tracks these sessions in order to handle
events like logout and timeout, to permit session constraints, and to notify
applications involved in SSO when a session ends.

Delegation

Granting users administrative privileges with AM.

Entitlement

Decision that defines which resource names can and cannot be accessed
for a given identity in the context of a particular application,
which actions are allowed and which are denied,
and any related advice and attributes.

Extended metadata

Federation configuration information specific to AM.

Extensible Access Control Markup Language (XACML)

Standard, XML-based access control policy language, including a
processing model for making authorization decisions based on policies.

Federation

Standardized means for aggregating identities, sharing authentication
and authorization data information between trusted providers, and allowing
principals to access services across different providers without
authenticating repeatedly.

Fedlet

Service provider application capable of participating in a circle of
trust and allowing federation without installing all of AM on the
service provider side; AM lets you create Java
Fedlets.

Hot swappable

Refers to configuration properties for which changes can take effect
without restarting the container where AM runs.

Identity

Set of data that uniquely describes a person or a thing such as a
device or an application.

Identity federation

Linking of a principal's identity across multiple providers.

Identity provider (IdP)

Entity that produces assertions about a principal (such as how and
when a principal authenticated, or that the principal's profile has a
specified attribute value).

Identity repository

Data store holding user profiles and group information; different
identity repositories can be defined for different realms.

Java agent

Java web application installed in a web container that acts as a
policy enforcement point, filtering requests to other applications in the container
with policies based on application resource URLs.

Metadata

Federation configuration information for a provider.

Policy

Set of rules that define who is granted access to a protected resource
when, how, and under what conditions.

Policy agent

Java, web, or custom agent that intercepts requests for resources, directs principals to
AM for authentication, and enforces policy decisions from AM.

Policy Administration Point (PAP)

Entity that manages and stores policy definitions.

Policy Decision Point (PDP)

Entity that evaluates access rights and then issues authorization
decisions.

Policy Enforcement Point (PEP)

Entity that intercepts a request for a resource and then enforces
policy decisions from a PDP.

Policy Information Point (PIP)

Entity that provides extra information, such as user profile attributes
that a PDP needs in order to make a decision.

Principal

Represents an entity that has been authenticated
(such as a user, a device, or an application),
and thus is distinguished from other entities.

When a Subject successfully authenticates,
AM associates the Subject with the Principal.

Privilege

In the context of delegated administration,
a set of administrative tasks that can be performed by specified identities
in a given realm.

Provider federation

Agreement among providers to participate in a circle of trust.

Realm

AM unit for organizing configuration and identity information.

Realms can be used for example when different parts of an organization
have different applications and user data stores,
and when different organizations use the same AM deployment.

Administrators can delegate realm administration.
The administrator assigns administrative privileges to users,
allowing them to perform administrative tasks within the realm.

Resource

Something a user can access over the network such as a web page.

Defined as part of policies,
these can include wildcards in order to match multiple actual resources.

Resource owner

In OAuth 2.0, entity who can authorize access to protected web
resources, such as an end user.

Resource server

In OAuth 2.0, server hosting protected web resources, capable of
handling access tokens to respond to requests for such resources.

Response attributes

Defined as part of policies, these allow AM
to return additional information in the form of "attributes"
with the response to a policy decision.

Role based access control (RBAC)

Access control that is based on whether a user has been granted a set
of permissions (a role).

Security Assertion Markup Language (SAML)

Standard, XML-based language for exchanging authentication and
authorization data between identity providers and service providers.

Service provider (SP)

Entity that consumes assertions about a principal (and provides a
service that the principal is trying to access).

Authentication Session

The interval while the user or entity is authenticating to AM.

Session

The interval that starts after the user has authenticated
and ends when the user logs out, or when their
session is terminated. For browser-based clients, AM manages user
sessions across one or more applications by setting a session cookie.
See also CTS-based sessions
and Client-based sessions.

Session high availability

Capability that lets any AM server in a clustered deployment access
shared, persistent information about users' sessions from the CTS token
store. The user does not need to log in again unless the entire deployment
goes down.

Session token

Unique identifier issued by AM after successful authentication.
For a CTS-based sessions, the session token is used to
track a principal's session.

Single log out (SLO)

Capability allowing a principal to end a session once, thereby ending
her session across multiple applications.

Single sign-on (SSO)

Capability allowing a principal to authenticate once and gain access
to multiple applications without authenticating again.

Site

Group of AM servers configured the same way,
accessed through a load balancer layer. The load balancer handles failover
to provide service-level availability.

The load balancer can also be used to protect AM services.

Standard metadata

Standard federation configuration information that you can share with
other access management software.

Stateless Service

Stateless services do not store any data locally to the service.
When the service requires data to perform any action, it requests it
from a data store. For example, a stateless authentication service stores
session state for logged-in users in a database. This way, any server
in the deployment can recover the session from the database and service
requests for any user.