The REST API version numbers supported in OpenAM 12.0.4 are as follows:

The OpenAM Release Notes section, OpenAM Changes & Deprecated Functionality in the Release Notes describes the differences between API versions.

You can specify which version of the REST API to use by adding an Accept-API-Version header to the request, as in the following example, which is requesting resource version 2.0 and protocol version 1.0.

$ curl \
 --request POST \
 --header "Content-Type: application/json" \
 --header "X-OpenAM-Username: demo" \
 --header "X-OpenAM-Password: changeit" \
 --header "Accept-API-Version: resource=2.0, protocol=1.0" \
 https://openam.example.com:8443/openam/json/authenticate

You can configure the default behavior OpenAM will take when a REST call does not specify explicit version information. For more information, see Configuring REST APIs in the Administration Guide in the OpenAM Administration Guide.

OpenAM provides REST API version messages in the JSON response to a REST API call. You can also configure OpenAM to return version messages in the response headers. See Configuring REST APIs in the Administration Guide in the OpenAM Administration Guide

Messages include:

The resource and protocol version used to service a REST API call are returned in the Content-API-Version header, as shown below.

$ curl \
 -i \
 --request POST \
 --header "Content-Type: application/json" \
 --header "X-OpenAM-Username: demo" \
 --header "X-OpenAM-Password: changeit" \
 --header "Accept-API-Version: resource=2.0, protocol=1.0" \
 https://openam.example.com:8443/openam/json/authenticate

HTTP/1.1 200 OK
Content-API-Version: protocol=1.0,resource=2.0
Server: Restlet-Framework/2.1.7
Content-Type: application/json;charset=UTF-8

{
 "tokenId":"AQIC5wM...TU3OQ*",
 "successUrl":"/openam/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.

$ curl \
 --header "Content-Type: application/json" \
 --header "Accept-API-Version: protocol=1.0" \
 https://openam.example.com:8443/openam/json/serverinfo/*

{
 "code":400,
 "reason":"Bad Request",
 "message":"No requested version specified and behavior set to NONE."
}

If a REST API call does include the Accept-API-Version header, but the specified resource or protocol version does not exist in OpenAM, then a 404 Not Found status code is returned, as shown below.

$ curl \
 --header "Content-Type: application/json" \
 --header "Accept-API-Version: protocol=1.0, resource=999.0" \
 https://openam.example.com:8443/openam/json/serverinfo/*

{
 "code":404,
 "reason":"Not Found",
 "message":"Accept-API-Version: Requested version \"999.0\" does not match any routes."
}

The simplest user name/password authentication returns a tokenId that applications can present as a cookie value for other operations that require authentication. In this case 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.

$ curl \
 --request POST \
 --header "X-OpenAM-Username: demo" \
 --header "X-OpenAM-Password: changeit" \
 --header "Content-Type: application/json" \
 --data "{}" \
 https://openam.example.com:8443/openam/json/authenticate
{ "tokenId": "AQIC5w...NTcy*", "successUrl": "/openam/console" }
   

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, OpenAM 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 OpenAM. The default is still user name/password authentication.

$ curl \
 --request POST \
 --header "Content-Type: application/json" \
 https://openam.example.com:8443/openam/json/authenticate

{
    "authId": "...jwt-value...",
    "template": "",
    "stage": "DataStore1",
    "callbacks": [
        {
            "type": "NameCallback",
            "output": [
                {
                    "name": "prompt",
                    "value": " User Name: "
                }
            ],
            "input": [
                {
                    "name": "IDToken1",
                    "value": ""
                }
            ]
        },
        {
            "type": "PasswordCallback",
            "output": [
                {
                    "name": "prompt",
                    "value": " Password: "
                }
            ],
            "input": [
                {
                    "name": "IDToken2",
                    "value": ""
                }
            ]
        }
    ]
}
   

The "authId" value is a JSON Web Token (JWT) that uniquely identifies the authentication context to OpenAM, and so must also be sent back with the requests.

To respond to the callback, send back the JSON object with the missing values filled, as in this case where the user name is demo and the password is changeit.

$ curl \
 --request POST \
 --header "Content-Type: application/json" \
 --data '{ "authId": "...jwt-value...", "template": "", "stage": "DataStore1",
   "callbacks": [ { "type": "NameCallback", "output": [ { "name": "prompt",
   "value": " User Name: " } ], "input": [ { "name": "IDToken1", "value": "demo" } ] },
   { "type": "PasswordCallback", "output": [ { "name": "prompt", "value": " Password: " } ],
   "input": [ { "name": "IDToken2", "value": "changeit" } ] } ] }' \
 https://openam.example.com:8443/openam/json/authenticate

{ "tokenId": "AQIC5wM2...U3MTE4NA..*", "successUrl": "/openam/console" }
   

The response is a token ID holding the SSO Token value.

Alternatively, you can authenticate without requesting a session using the noSession query string parameter.

$ curl \
 --request POST \
 --header "Content-Type: application/json" \
 --data '{ "authId": "...jwt-value...", "template": "", "stage": "DataStore1",
   "callbacks": [ { "type": "NameCallback", "output": [ { "name": "prompt",
   "value": " User Name: " } ], "input": [ { "name": "IDToken1", "value": "demo" } ] },
   { "type": "PasswordCallback", "output": [ { "name": "prompt", "value": " Password: " } ],
   "input": [ { "name": "IDToken2", "value": "changeit" } ] } ] }' \
 https://openam.example.com:8443/openam/json/authenticate?noSession=true

{ "message": "Authentication Successful", "successUrl": "/openam/console" }
   

OpenAM 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 configured for the Core in the Administration Guide authentication module. Alternatively, failure URLs can be configured per authentication chain, which your client can specify using the service parameter described below. On failure OpenAM then returns HTTP status code 401 Unauthorized, and the JSON in the reply indicates the failure URL.

$ curl \
 --request POST \
 --header "Content-Type: application/json" \
 --header "X-OpenAM-Username: demo" \
 --header "X-OpenAM-Password: badpassword" \
 https://openam.example.com:8443/openam/json/authenticate
{
  "code":401,
  "reason":"Unauthorized",
  "message":"Invalid Password!!",
  "failureUrl": "http://www.example.com/401.html"
}
   

To specify a realm in your request, first make sure that the name of your realm does not match an endpoint name to avoid any potential routing errors. Then, specify the realm in one of two ways. For example, if you have a realm titled "myRealm," you can use it in your request as follows:

You can use the query string parameter, sessionUpgradeSSOTokenId=tokenId, to request session upgrade. For an explanation of session upgrade, see the Administration Guide section on, Authentication Levels & Session Upgrade in the Administration Guide.

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

$ curl \
 --request POST \
 --header "iplanetDirectoryPro: AQIC5wM2...U3MTE4NA..*" \
 --header "Content-Type: application/json" \
 "https://openam.example.com:8443/openam/json/sessions/?_action=logout"

{"result":"Successfully logged out"}
   

Interface Stability: Deprecated in the Administration Guide

Simple authentication with a user name and password returns a token.

$ curl \
 --request POST \
 --data "username=bjensen&password=hifalutin" \
 https://openam.example.com:8443/openam/identity/authenticate

token.id=AQIC5wM2LY4SfcxvdvHOXjtC_eWSs2RB54tgvgK8SuYi7aQ.*AAJTSQACMDE.*
    

If you must specify parameters as when authenticating to /UI/Login, you provide a percent encoded string of the parameters as the value of the uri parameter. The /UI/Login parameter deals with the realm, module, and service parameters. Setting the client parameter sets the user's IP address as part of the token following successful authentication. The default for the client parameter is the IP of the machine making the REST request.

$ curl \
 --request POST \
 --data "username=bjensen&password=hifalutin&uri=realm%3D%2F%26module%3DDataStore\
&client=192.168.1.1" \
 https://openam.example.com:8443/openam/identity/authenticate

token.id=AQIC5wM2LY4SfcxvdvHOXjtC_eWSs2RB54tgvgK8SuYi7aQ.*AAJTSQACMDE.*
    

You log out using the token to end the user session.

$ curl \
 --request POST \
 --data "subjectid=AQIC5w...*AAJTSQACMDE.*" \
 https://openam.example.com:8443/openam/identity/logout
    

To check over REST whether a token is valid, perform an HTTP POST to the resource URL, /json/sessions/tokenId, using the validate action as shown in the following example:

$ curl \
 --request POST \
 --header "Content-Type: application/json" \
 http://openam.example.com:8080/openam/json/sessions/AQIC5...?_action=validate
{"valid":true,"uid":"demo","realm":"/myRealm"}
   

An invalid token returns only information about the validity.

$ curl \
 --request POST \
 --header "Content-Type: application/json" \
 http://openam.example.com:8080/openam/json/sessions/AQIC5...?_action=validate
{"valid":false}
   

You can use REST API calls to:

For these REST endpoints, specify two SSO tokens. Provide the SSO token for the current authenticated user as the value of a header whose name is the name of the SSO token cookie, by default iPlanetDirectoryPro. Specify the SSO token about which you want information as the tokenId query string parameter of the REST URL. In the examples in this section, AQIC5w...NTcy* is the SSO token for the current authenticated user, while BXCCq...NX*1* is the token being queried.

To determine whether a session is active, perform an HTTP POST to the resource URL, /json/sessions/, using the isActive action as shown in the following example:

$ curl \
 --request POST \
 --header "Content-Type: application/json" \
 --header "iplanetDirectoryPro: AQIC5w...NTcy*" \
 http://openam.example.com:8080/openam/json/sessions/?_action=isActive&tokenId=BXCCq...NX*1*
  
{"active":true}

To check the maximum remaining time (in seconds) of a session, perform an HTTP POST to the resource URL, /json/sessions/, using the getMaxTime action as shown in the following example:

$ curl \
 --request POST \
 --header "Content-Type: application/json" \
 --header "iplanetDirectoryPro: AQIC5w...NTcy*" \
 http://openam.example.com:8080/openam/json/sessions/?_action=getMaxTime&tokenId=BXCCq...NX*1*
  
{"maxtime":7022}

To check the amount of time (in seconds) that a session has been idle, perform an HTTP POST to the resource URL, /json/sessions/, using the getIdle action as shown in the following example:

$ curl \
 --request POST \
 --header "Content-Type: application/json" \
 --header "iplanetDirectoryPro: AQIC5w...NTcy*" \
 http://openam.example.com:8080/openam/json/sessions/?_action=getIdle&tokenId=BXCCq...NX*1*
  
{"idletime":355}

To reset a session's idle time, perform an HTTP POST to the resource URL, /json/sessions/, using the isActive action with the refresh=true option as shown in the following example:

$ curl \
 --request POST \
 --header "Content-Type: application/json" \
 --header "iplanetDirectoryPro: AQIC5w...NTcy*" \
 http://openam.example.com:8080/openam/json/sessions/?_action=isActive&refresh=true&tokenId=BXCCq...NX*1*
  
{"active":true}

Interface Stability: Deprecated in the Administration Guide

You check whether a token is valid as follows:

$ curl \
 --request POST \
 --data "tokenid=AQIC5w...*AAJTSQACMDE.*" \
 https://openam.example.com:8443/openam/identity/isTokenValid
boolean=true
   

An invalid token returns boolean=false.

$ curl \
 --request POST \
 --data "tokenid=INVALID" \
 https://openam.example.com:8443/openam/identity/isTokenValid
boolean=false
   

With a valid token, you can retrieve attributes about the subject. OpenAM returns a series of name, value pairs.

The newer API for retrieving user information is demonstrated in Reading Identities. What follows describes the legacy API.

$ curl \
 --request POST \
 --data "subjectid=AQIC5w...*AAJTSQACMDE.*" \
 https://openam.example.com:8443/openam/identity/attributes
userdetails.token.id=
 AQIC5wM2LY4SfcxuxIP0VnP2lVjs7ypEM6VDx6srk56CN1Q.*AAJTSQACMDE.*
userdetails.attribute.name=uid
userdetails.attribute.value=bjensen
userdetails.attribute.name=mail
userdetails.attribute.value=bjensen@example.com
userdetails.attribute.name=sn
userdetails.attribute.value=Jensen
userdetails.attribute.name=userpassword
userdetails.attribute.value={SSHA}rhusOfYpkapDWEHcfT2Y7y83LMuC++F4Abqvig==
userdetails.attribute.name=cn
userdetails.attribute.value=Babs Jensen
userdetails.attribute.value=Barbara Jensen
userdetails.attribute.name=givenname
userdetails.attribute.value=Barbara
userdetails.attribute.name=dn
userdetails.attribute.value=uid=bjensen,ou=people,dc=example,dc=com
userdetails.attribute.name=telephonenumber
userdetails.attribute.value=+1 408 555 1862
userdetails.attribute.name=objectclass
userdetails.attribute.value=organizationalPerson
userdetails.attribute.value=person
userdetails.attribute.value=posixAccount
userdetails.attribute.value=inetOrgPerson
userdetails.attribute.value=krbprincipalaux
userdetails.attribute.value=krbTicketPolicyAux
userdetails.attribute.value=top
   

You can specify attributes to limit what you retrieve.

$ curl "https://openam.example.com:8443/openam/identity/attributes?\
subjectid=AQIC5wM2LY4SfcxuxIP0VnP2lVjs7ypEM6VDx6srk56CN1Q.*AAJTSQACMDE.*\
&attributenames=mail\
&attributenames=uid"
userdetails.token.id=
 AQIC5wM2LY4SfcxuxIP0VnP2lVjs7ypEM6VDx6srk56CN1Q.*AAJTSQACMDE.*
userdetails.attribute.name=uid
userdetails.attribute.value=bjensen
userdetails.attribute.name=mail
userdetails.attribute.value=bjensen@example.com
   

When retrieving attributes, you can refresh the session thus setting the idle time to 0, by adding the boolean parameter refresh=true to the query string.

$ curl "https://openam.example.com:8443/openam/identity/attributes?\
subjectid=AQIC5wM2LY4SfcxuxIP0VnP2lVjs7ypEM6VDx6srk56CN1Q.*AAJTSQACMDE.*\
&attributenames=cn\
&refresh=true"
userdetails.token.id=
 AQIC5wM2LY4SfcxuxIP0VnP2lVjs7ypEM6VDx6srk56CN1Q.*AAJTSQACMDE.*
userdetails.attribute.name=cn
userdetails.attribute.value=Babs Jensen
userdetails.attribute.value=Barbara Jensen
   

You can specify the following attributes to retrieve information about the user's session time limits and current session: maxsessiontime (maximum length of a session), maxidletime (maximum idle time allowed during a session), idletime (actual idle time during the current session), timeleft (actual time left in session). The unit for maximum times is minutes. The unit for actual times is seconds.

Also use the parameter refresh=false to avoid changing the idletime with your request.

$ curl \
--data "subjectid=AQIC5w....*AAJTSQACMDE.*\
 &attributenames=idletime\
 &attributenames=maxidletime\
 &attributenames=timeleft\
 &attributenames=maxsessiontime\
 &refresh=false" \
 https://openam.example.com:8443/openam/identity/attributes

userdetails.token.id=AQIC5w....*AAJTSQACMDE.*
userdetails.attribute.name=maxsessiontime
userdetails.attribute.value=120
userdetails.attribute.name=maxidletime
userdetails.attribute.value=30
userdetails.attribute.name=idletime
userdetails.attribute.value=664
userdetails.attribute.name=timeleft
userdetails.attribute.value=6319
  

This section shows how you can request a policy decision over REST for specific resources.

To request policy decisions for specific resources, perform an HTTP POST using the evaluation action to the appropriate path under the URI where OpenAM is deployed, /json[/realm][/ subrealm]/policies?_action=evaluate, where realm and subrealm optionally specifies the realm. The payload for the HTTP POST is a JSON object that specifies at least the resources, and takes the following form.

{
    "resources": [
        "resource1",
        "resource2",
        ...,
        "resourceN"
    ],
    "application": "defaults to iPlanetAMWebAgentService if not specified",
    "subject": {
        "ssoToken": "SSO token ID string",
        "jwt": "JSON Web Token string",
        "claims": {
            "key": "value",
            ...
        }
    },
    "environment": {
        "optional key1": [
            "value",
            "another value",
            ...
        ],
        "optional key2": [
            "value",
            "another value",
            ...
        ],
        ...
    }
}
     

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

$ curl \
 --request POST \
 --header "iPlanetDirectoryPro: AQIC5..." \
 --header "Content-Type: application/json" \
 --data '{
    "resources": [
        "http://www.example.com/index.html",
        "http://www.example.com/do?action=run"
    ],
    "application": "iPlanetAMWebAgentService"
 }' \
 https://openam.example.com:8443/openam/json/policies?_action
    =evaluate
[ {
  "resource" : "http://www.example.com/do?action=run",
  "actions" : {
  },
  "attributes" : {
  },
  "advices" : {
    "AuthLevelConditionAdvice" : [ "3" ]
  }
}, {
  "resource" : "http://www.example.com/index.html",
  "actions" : {
    "POST" : false,
    "GET" : true
  },
  "attributes" : {
    "cn" : [ "demo" ]
  },
  "advices" : {
  }
} ]
     

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.

When OpenAM returns a policy decision, the JSON for the decision can include an "advices" field. This field contains hints for the policy enforcement point.

{
    "advices": {
        "type": [
            "advice"
        ]
    }
}
   

The "advices" returned depend on policy conditions. For more information about OpenAM policy conditions, see "Managing Policies".

This section shows examples of the different types of policy decision advice and the conditions that cause OpenAM to return the advice.

"AuthLevel" and "LEAuthLevel" condition failures can result in advice showing the expected or maximum possible authentication level. For example, failure against the following condition:

{
    "type": "AuthLevel",
    "authLevel": 2
}
   

Leads to this advice:

{
    "AuthLevelConditionAdvice": [
        "2"
    ]
}
   

An "AuthScheme" condition failure can result in advice showing one or more required authentication modules. For example, failure against the following condition:

{
    "type": "AuthScheme",
    "authScheme": [
        "HOTP"
    ],
    "applicationName": "iPlanetAMWebAgentService",
    "applicationIdleTimeout": 10
}
   

Leads to this advice:

{
    "AuthSchemeConditionAdvice": [
        "HOTP"
    ]
}
   

An "AuthenticateToRealm" condition failure can result in advice showing the name of the realm to which authentication is required. For example, failure against the following condition:

{
    "type": "AuthenticateToRealm",
    "authenticateToRealm": "MyRealm"
}
   

Leads to this advice:

{
    "AuthenticateToRealmConditionAdvice": [
        "/myRealm"
    ]
}
   

An "AuthenticateToService" condition failure can result in advice showing the name of the required authentication chain. For example, failure against the following condition:

{
    "type": "AuthenticateToService",
    "authenticateToService": "MyAuthnChain"
}
   

Leads to this advice:

{
    "AuthenticateToServiceConditionAdvice": [
        "MyAuthnChain"
    ]
}
   

A "ResourceEnvIP" condition failure can result in advice 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:

{
    "type": "ResourceEnvIP",
    "resourceEnvIPConditionValue": [
        "IF IP=[127.0.0.12] THEN authlevel=4"
    ]
}
   

Leads to this advice:

{
    "AuthLevelConditionAdvice": [
        "4"
    ]
}
   

Failure against a different type of "ResourceEnvIP" condition such as the following:

{
    "type": "ResourceEnvIP",
    "resourceEnvIPConditionValue": [
        "IF IP=[127.0.0.11] THEN service=MyAuthnChain"
    ]
}
   

Leads to this advice:

{
    "AuthenticateToServiceConditionAdvice": [
        "MyAuthnChain"
    ]
}
   

A "Session" condition failure can result in advice showing that access has been denied because the user's session has been active longer than allowed by the condition. The advice will also show if the the user's session was terminated and reauthentication is required. For example, failure against the following condition:

{
    "type": "Session",
    "maxSessionTime": "10",
    "terminateSession": false
}
   

Leads to this advice:

{
    "SessionConditionAdvice": [
        "deny"
    ]
}
   

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

This section shows how you can request policy decisions over REST for a resource and all other resources in the subtree beneath it.

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 OpenAM is deployed, /json[/realm]/policies?_action=evaluateTree, where realm optionally specifies the realm. The payload for the HTTP POST is a JSON object that specifies at least the root resource, and takes the following form.

{
    "resource": "resource string",
    "application": "defaults to iPlanetAMWebAgentService if not specified",
    "subject": {
        "ssoToken": "SSO token ID string",
        "jwt": "JSON Web Token string",
        "claims": {
            "key": "value",
            ...
        }
    },
    "environment": {
        "optional key1": [
            "value",
            "another value",
            ...
        ],
        "optional key2": [
            "value",
            "another value",
            ...
        ],
        ...
    }
}
   

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

$ curl \
 --request POST \
 --header "iPlanetDirectoryPro: AQIC5...NDU1*" \
 --header "Content-Type: application/json" \
 --data '{
    "resource": "http://www.example.com/",
    "subject": { "ssoToken": "AQIC5...zE4*" }
 }' \
 https://openam.example.com:8443/openam/json/policies?_action=evaluateTree
[ {
  "resource" : "http://www.example.com/",
  "actions" : {
    "GET" : true,
    "OPTIONS" : true,
    "HEAD" : true
  },
  "attributes" : {
  },
  "advices" : {
  }
}, {
  "resource" : "http://www.example.com/*",
  "actions" : {
    "POST" : false,
    "PATCH" : false,
    "GET" : true,
    "DELETE" : true,
    "OPTIONS" : true,
    "HEAD" : true,
    "PUT" : true
  },
  "attributes" : {
    "myStaticAttr" : [ "myStaticValue" ]
  },
  "advices" : {
  }
}, {
  "resource" : "http://www.example.com/*?*",
  "actions" : {
    "POST" : false,
    "PATCH" : false,
    "GET" : false,
    "DELETE" : false,
    "OPTIONS" : true,
    "HEAD" : false,
    "PUT" : false
  },
  "attributes" : {
  },
  "advices" : {
    "AuthLevelConditionAdvice" : [ "3" ]
  }
} ]
  

Notice that OpenAM returns decisions not only for the specified resource, but also for matching resource names in the tree whose root is the specified resource.

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.

To create a policy, either perform an HTTP PUT indicating the full path to the resource and the name in the resource matching the name in the path, or perform an HTTP POST with the name to use specified in the resource.

The HTTP PUT form includes the policy definition as the JSON resource data, with the header Content-Type: application/json and uses the If-None-Match: * header.

The iPlanetDirectoryPro header sets the SSO token for a user who has access to perform the operation.

Do not use special characters within policy, application or referral names (for example, "my+referral") using the Policy Editor or REST endpoints as OpenAM returns a 400 Bad Request error. The special characters are: double quotes ("), plus sign (+), comma (,), less than (<), equals (=), greater than (>), backslash (\), and null (\u0000).

$ curl \
 --request PUT \
 --header "iPlanetDirectoryPro: AQIC5w..." \
 --header "If-None-Match: *" \
 --header "Content-Type: application/json" \
 --data '{
    "name": "example",
    "active": true,
    "description": "Example Policy",
    "resources": [
        "http://www.example.com:80/*",
        "http://www.example.com:80/*?*"
    ],
    "actionValues": {
        "POST": false,
        "GET": true
    },
    "subject": {
        "type": "Identity",
        "subjectValues": [
            "uid=scarter,ou=People,dc=example,dc=com"
        ]
    }
}' \
 https://openam.example.com:8443/openam/json/policies/example

{
  "name" : "example",
  "active" : true,
  "description" : "Example Policy",
  "applicationName" : "iPlanetAMWebAgentService",
  "actionValues" : {
    "POST" : false,
    "GET" : true
  },
  "resources" : [
    "http://www.example.com:80/*",
    "http://www.example.com:80/*?*"
  ],
  "subject" : {
   "type": "Identity",
    "subjectValues": [
      "uid=scarter,ou=People,dc=example,dc=com"
    ]
  },
  "lastModifiedBy" :
  "id=demo,ou=user,o=realm,ou=services,dc=openam,dc=forgerock,dc=org",
  "lastModified" : "2014-04-24T16:23:34Z",
  "createdBy" :
  "id=demo,ou=user,o=realm,ou=services,dc=openam,dc=forgerock,dc=org",
  "creationDate" : "2014-04-24T16:23:34Z"
}
   

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.

The HTTP POST form includes the policy definition as the JSON resource data, with the header Content-Type: application/json and uses the _action=create operation.

The iPlanetDirectoryPro header sets the SSO token for a user who has access to perform the operation.

$ curl \
 --request POST \
 --header "iPlanetDirectoryPro: AQIC5..." \
 --header "Content-Type: application/json" \
 --data '{
    "name": "example",
    "active": true,
    "description": "Example Policy",
    "resources": [
        "http://www.example.com:80/*",
        "http://www.example.com:80/*?*"
    ],
    "actionValues": {
        "POST": false,
        "GET": true
    },
    "subject": {
        "type": "Identity",
        "subjectValues": [
            "uid=scarter,ou=People,dc=example,dc=com"
        ]
    }
}' \
 https://openam.example.com:8443/openam/json/policies?_action=create
      
{
  "name" : "example",
  "active" : true,
  "description" : "Example Policy",
  "applicationName" : "iPlanetAMWebAgentService",
  "actionValues" : {
    "POST" : false,
    "GET" : true
  },
  "resources" : [
    "http://www.example.com:80/*",
    "http://www.example.com:80/*?*"
  ],
  "subject" : {
    "type": "Identity",
    "subjectValues": [
      "uid=scarter,ou=People,dc=example,dc=com"
    ]
  },
  "lastModifiedBy" :
   "id=demo,ou=user,o=realm,ou=services,dc=openam,dc=forgerock,dc=org",
  "lastModified" : "2014-04-29T07:33:54Z",
  "createdBy" :
   "id=demo,ou=user,o=realm,ou=services,dc=openam,dc=forgerock,dc=org",
  "creationDate" : "2014-04-29T07:33:54Z"
}
      

To read a policy definition, perform an HTTP GET specifying the resource name.

The iPlanetDirectoryPro header sets the SSO token for a user who has access to perform the operation.

$ curl \
 --header "iPlanetDirectoryPro: AQIC5..." \
 https://openam.example.com:8443/openam/json/policies/example

{
  "name" : "example",
  "active" : true,
  "description" : "Example Policy",
  "applicationName" : "iPlanetAMWebAgentService",
  "actionValues" : {
    "POST" : false,
    "GET" : true
  },
  "resources" : [
    "http://www.example.com:80/*",
    "http://www.example.com:80/*?*"
  ],
  "subject" : {
    "type": "Identity",
    "subjectValues": [
      "uid=scarter,ou=People,dc=example,dc=com"
    ]
  },
  "lastModifiedBy" :
  "id=demo,ou=user,o=realm,ou=services,dc=openam,dc=forgerock,dc=org",
  "lastModified" : "2014-04-24T16:23:34Z",
  "createdBy" :
  "id=demo,ou=user,o=realm,ou=services,dc=openam,dc=forgerock,dc=org",
  "creationDate" : "2014-04-24T16:23:34Z"
}
   

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.

To update a policy definition, perform an HTTP PUT specifying the resource name with the policy definition as the JSON resource data, and with the header Content-Type: application/json. This is essentially the same as creating a policy, but without the If-None-Match: * header.

The iPlanetDirectoryPro header sets the SSO token for a user who has access to perform the operation.

$ curl \
 --request PUT \
 --header "iPlanetDirectoryPro: AQIC5w..." \
 --header "Content-Type: application/json" \
 --data '{
    "name": "example",
    "active": true,
    "description": "Updated example policy",
    "resources": [
        "http://www.example.com:80/*",
        "http://www.example.com:80/*?*"
    ],
    "actionValues": {
        "POST": true,
        "GET": true
    },
    "subject": {
        "type": "Identity",
        "subjectValues": [
            "uid=scarter,ou=People,dc=example,dc=com"
        ]
    }
}' \
 https://openam.example.com:8443/openam/json/policies/example

{
  "name" : "example",
  "active" : true,
  "description" : "Updated example policy",
  "applicationName" : "iPlanetAMWebAgentService",
  "actionValues" : {
    "POST" : true,
    "GET" : true
  },
  "resources" : [
    "http://www.example.com:80/*",
    "http://www.example.com:80/*?*"
  ],
  "subject" : {
    "type": "Identity",
    "subjectValues": [
      "uid=scarter,ou=People,dc=example,dc=com"
    ]
  },
  "lastModifiedBy" :
  "id=demo,ou=user,o=realm,ou=services,dc=openam,dc=forgerock,dc=org",
  "lastModified" : "2014-04-24T16:44:01Z",
  "createdBy" :
  "id=demo,ou=user,o=realm,ou=services,dc=openam,dc=forgerock,dc=org",
  "creationDate" : "2014-04-24T16:23:34Z"
}
   

$ curl \
 --request PUT \
 --header "iPlanetDirectoryPro: AQIC5w..." \
 --header "Content-Type: application/json" \
 --data '{
     "name": "new-example",
     "active": true,
     "description": "Renamed example policy",
     "resources": [
         "http://www.example.com:80/*",
         "http://www.example.com:80/*?*"
     ],
     "actionValues": {
         "POST": true,
         "GET": true
     },
     "subject": {
         "type": "Identity",
         "subjectValues": [
             "uid=scarter,ou=People,dc=example,dc=com"
         ]
     }
 }' \
 https://openam.example.com:8443/openam/json/policies/example

{
    "name" : "new-example",
    "active" : true,
    "description" : "Renamed example policy",
    "applicationName" : "iPlanetAMWebAgentService",
    "actionValues" : {
        "POST" : true,
        "GET" : true
    },
    "resources" : [
        "http://www.example.com:80/*",
        "http://www.example.com:80/*?*"
    ],
    "subject" : {
        "type": "Identity",
        "subjectValues": [
            "uid=scarter,ou=People,dc=example,dc=com"
        ]
    },
    "lastModifiedBy" :
    "id=demo,ou=user,o=realm,ou=services,dc=openam,dc=forgerock,dc=org",
    "lastModified" : "2014-04-24T16:48:01Z",
    "createdBy" :
    "id=demo,ou=user,o=realm,ou=services,dc=openam,dc=forgerock,dc=org",
    "creationDate" : "2014-04-24T16:23:34Z"
}
   

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.

To delete a policy definition, perform an HTTP DELETE specifying the resource name.

The iPlanetDirectoryPro header sets the SSO token for a user who has access to perform the operation.

$ curl \
 --header "iPlanetDirectoryPro: AQIC5w..." \
 --request DELETE \
 https://openam.example.com:8443/openam/json/policies/myPolicy
{}
   

To list policy definitions, perform an HTTP GET on the endpoint, setting the _queryFilter query string parameter.

$ curl \
 --header "iPlanetDirectoryPro: AQIC5w..." \
 https://openam.example.com:8443/openam/json/policies?_queryFilter=true
   
{
  "result" : [ ...policies... ],
  "resultCount" : 0,
  "pagedResultsCookie" : null,
  "remainingPagedResults" : -1
}
   

The _queryFilter parameter can take true to match every policy, false to match no policies, or a filter of the following form to match field values: field operator value where field represents the field name, operator is the operator code, value is the value to match, and the entire filter is URL-encoded. Supported operators are as follows:

Filters can be composed of multiple expressions by a using boolean operator AND, and by using parentheses, (expression), to group expressions. You must URL encode the filter expression in _queryFilter=filter.

You can use the query string parameters _prettyPrint=true to make the output easier to read, _fields=field-name[,field-name...] to limit the fields returned in the output.

You can use _pageSize=integer to limit the number of results returned, as shown in the following example that returns only the first of three policies.

$ curl \
 --header "iPlanetDirectoryPro: AQIC5w..." \
 https://openam.example.com:8443/openam/json/policies?_queryFilter=true\&_fields=name\&_pageSize=1
{
  "result" : [ {
    "name" : "My Other Policy"
  } ],
  "resultCount" : 1,
  "pagedResultsCookie" : null,
  "remainingPagedResults" : 2
}
   

You can use _sortKeys=[+-]field[,field...] to sort the results returned, where field represents a field in the JSON policy objects returned. Optionally use the + prefix to sort in ascending order (the default), or - to sort in descending order. The following example sorts the policy objects by their names.

$ curl \
  --header "iPlanetDirectoryPro: AQIC5w..." \
 https://openam.example.com:8443/openam/json/policies?_queryFilter=true\&_sortKeys=name
  {
  "result" : [ {
    "name" : "Another Example Policy",
    ...
  }, {
    "name" : "My Other Policy",
    ...
  }, {
    "name" : "Sample Policy",
    ...
  } ],
  "resultCount" : 3,
  "pagedResultsCookie" : null,
  "remainingPagedResults" : 0
}
   

OpenAM supports exporting policies into XACML 3.0 format. OpenAM 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:

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:

OpenAM supports the import of XACML 3.0-based policy sets into OpenAM policies using the REST /xacml/policies endpoint. To test an import, OpenAM 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
   

$ curl \
  --request POST \
  --header "iPlanetDirectoryPro: AQIC5..." \
  --header "Content-Type: application/xml" \
  --data @xacml-policy.xml
  http://openam.example.com:8080/openam/xacml/{realm}/policies
     

To create an application definition, either perform an HTTP PUT indicating the full path to the resource and the name in the resource matching the name in the path, or perform an HTTP POST with the name to use specified in the resource.

The HTTP PUT form includes the application definition as the JSON resource data, with the header Content-Type: application/json and uses the If-None-Match: * header.

The iPlanetDirectoryPro header sets the SSO token for a user who has access to perform the operation.

Do not use special characters within policy, application or referral names (for example, "my+referral") using the Policy Editor or REST endpoints as OpenAM returns a 400 Bad Request error. The special characters are: double quotes ("), plus sign (+), comma (,), less than (<), equals (=), greater than (>), backslash (\), and null (\u0000).

$ curl \
 --request PUT \
 --header "If-None-Match: *" \
 --header "iPlanetDirectoryPro: AQIC5..." \
 --header "Content-Type: application/json" \
 --data '{
    "name": "myApplication",
    "resources": [
        "http://www.example.com:8080/*",
        "http://www.example.com:8080/*?*"
    ],
    "actions": {
        "UPDATE": true,
        "PATCH": true,
        "QUERY": true,
        "CREATE": true,
        "DELETE": true,
        "READ": true,
        "ACTION": true
    },
    "conditions": [
        "AND",
        "OR",
        "NOT",
        "AMIdentityMembership",
        "AuthLevel",
        "AuthScheme",
        "AuthenticateToRealm",
        "AuthenticateToService",
        "IPv4",
        "IPv6",
        "LDAPFilter",
        "LEAuthLevel",
        "OAuth2Scope",
        "ResourceEnvIP",
        "Session",
        "SessionProperty",
        "SimpleTime"
    ],
    "realm": "/",
    "applicationType": "iPlanetAMWebAgentService",
    "description": "An example application",
    "resourceComparator": "com.sun.identity.entitlement.URLResourceName",
    "subjects": [
        "AND",
        "OR",
        "NOT",
        "AuthenticatedUsers",
        "Identity",
        "JwtClaim"
    ],
    "entitlementCombiner": "DenyOverride",
    "saveIndex": null,
    "searchIndex": null,
    "attributeNames": []
}
' \
 https://openam.example.com:8443/openam/json/applications/myApplication
{
  "name" : "myApplication",
  "resources" : [
    "http://www.example.com:8080/*",
    "http://www.example.com:8080/*?*"
  ],
  "actions" : {
    "UPDATE" : true,
    "PATCH" : true,
    "QUERY" : true,
    "CREATE" : true,
    "DELETE" : true,
    "READ" : true,
    "ACTION" : true
  },
  "conditions": [
    "AND",
    "OR",
    "NOT",
    "AMIdentityMembership",
    "AuthLevel",
    "AuthScheme",
    "AuthenticateToRealm",
    "AuthenticateToService",
    "IPv4",
    "IPv6",
    "LDAPFilter",
    "LEAuthLevel",
    "OAuth2Scope",
    "ResourceEnvIP",
    "Session",
    "SessionProperty",
    "SimpleTime"
  ],
  "realm" : "/",
  "creationDate" : 1398761708295,
  "lastModifiedDate" : 1398761708295,
  "createdBy" : "id=amadmin,ou=user,dc=openam,dc=forgerock,dc=org",
  "lastModifiedBy" : "id=amadmin,ou=user,dc=openam,dc=forgerock,dc=org",
  "applicationType" : "iPlanetAMWebAgentService",
  "description" : "An example application",
  "resourceComparator" : "com.sun.identity.entitlement.URLResourceName",
  "subjects" : [
    "AND",
    "OR",
    "NOT",
    "AuthenticatedUsers",
    "Identity",
    "JwtClaim"
  ],
  "entitlementCombiner" : "DenyOverride",
  "saveIndex" : null,
  "searchIndex" : null,
  "attributeNames" : [ ]
}
   

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.

The HTTP POST form includes the application definition as the JSON resource data, with the header Content-Type: application/json and uses the _action=create operation.

The iPlanetDirectoryPro header sets the SSO token for a user who has access to perform the operation.

$ curl \
 --request POST \
 --header "iPlanetDirectoryPro: AQIC5..." \
 --header "Content-Type: application/json" \
 --data '{
    "name": "myApplication",
    "resources": [
        "http://www.example.com:8080/*",
        "http://www.example.com:8080/*?*"
    ],
    "actions": {
        "UPDATE": true,
        "PATCH": true,
        "QUERY": true,
        "CREATE": true,
        "DELETE": true,
        "READ": true,
        "ACTION": true
    },
    "conditions": [
        "AND",
        "OR",
        "NOT",
        "AMIdentityMembership",
        "AuthLevel",
        "AuthScheme",
        "AuthenticateToRealm",
        "AuthenticateToService",
        "IPv4",
        "IPv6",
        "LDAPFilter",
        "LEAuthLevel",
        "OAuth2Scope",
        "ResourceEnvIP",
        "Session",
        "SessionProperty",
        "SimpleTime"
    ],
    "realm": "/",
    "applicationType": "iPlanetAMWebAgentService",
    "description": "An example application",
    "resourceComparator": "com.sun.identity.entitlement.URLResourceName",
    "subjects": [
        "AND",
        "OR",
        "NOT",
        "AuthenticatedUsers",
        "Identity",
        "JwtClaim"
    ],
    "entitlementCombiner": "DenyOverride",
    "saveIndex": null,
    "searchIndex": null,
    "attributeNames": []
}' \
 https://openam.example.com:8443/openam/json/applications/?_action=create
{
  "name" : "myApplication",
  "resources" : [
    "http://www.example.com:8080/*",
    "http://www.example.com:8080/*?*"
  ],
  "actions" : {
    "UPDATE" : true,
    "PATCH" : true,
    "QUERY" : true,
    "CREATE" : true,
    "DELETE" : true,
    "READ" : true,
    "ACTION" : true
  },
  "conditions": [
    "AND",
    "OR",
    "NOT",
    "AMIdentityMembership",
    "AuthLevel",
    "AuthScheme",
    "AuthenticateToRealm",
    "AuthenticateToService",
    "IPv4",
    "IPv6",
    "LDAPFilter",
    "LEAuthLevel",
    "OAuth2Scope",
    "ResourceEnvIP",
    "Session",
    "SessionProperty",
    "SimpleTime"
  ],
  "realm" : "/",
  "creationDate" : 1398762452667,
  "lastModifiedDate" : 1398762452667,
  "createdBy" : "id=amadmin,ou=user,dc=openam,dc=forgerock,dc=org",
  "lastModifiedBy" : "id=amadmin,ou=user,dc=openam,dc=forgerock,dc=org",
  "applicationType" : "iPlanetAMWebAgentService",
  "description" : "An example application",
  "resourceComparator" : "com.sun.identity.entitlement.URLResourceName",
  "subjects" : [
    "AND",
    "OR",
    "NOT",
    "AuthenticatedUsers",
    "Identity",
    "JwtClaim"
  ],
  "entitlementCombiner" : "DenyOverride",
  "saveIndex" : null,
  "searchIndex" : null,
  "attributeNames" : [ ]
}
   

To read an application definition, perform an HTTP GET specifying the resource name.

The iPlanetDirectoryPro header sets the SSO token for a user who has access to perform the operation.

$ curl \
 --header "iPlanetDirectoryPro: AQIC5..." \
 https://openam.example.com:8443/openam/json/applications/myApplication
{
  "name" : "myApplication",
  "resources" : [
    "http://www.example.com:8080/*",
    "http://www.example.com:8080/*?*"
  ],
  "actions" : {
    "POST" : true,
    "PATCH" : true,
    "GET" : true,
    "DELETE" : true,
    "OPTIONS" : true,
    "PUT" : true,
    "HEAD" : true
  },
  "conditions": [
    "AND",
    "OR",
    "NOT",
    "AMIdentityMembership",
    "AuthLevel",
    "AuthScheme",
    "AuthenticateToRealm",
    "AuthenticateToService",
    "IPv4",
    "IPv6",
    "LDAPFilter",
    "LEAuthLevel",
    "OAuth2Scope",
    "ResourceEnvIP",
    "Session",
    "SessionProperty",
    "SimpleTime"
  ],
  "realm" : "/",
  "creationDate" : 1398760362341,
  "lastModifiedDate" : 1398760362341,
  "createdBy" : "id=dsameuser,ou=user,dc=openam,dc=forgerock,dc=org",
  "lastModifiedBy" : "id=dsameuser,ou=user,dc=openam,dc=forgerock,dc=org",
  "applicationType" : "iPlanetAMWebAgentService",
  "description" : null,
  "resourceComparator" : "com.sun.identity.entitlement.URLResourceName",
  "subjects" : [
    "AND",
    "OR",
    "NOT",
    "AuthenticatedUsers",
    "Identity",
    "JwtClaim"
  ],
  "entitlementCombiner" : "DenyOverride",
  "saveIndex" : null,
  "searchIndex" : null,
  "attributeNames" : [ ]
}
   

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.

To update an application definition, perform an HTTP PUT specifying the resource name with the application definition as the JSON resource data, and with the header Content-Type: application/json. This is essentially the same as creating an application definition, but without the If-None-Match: * header.

The iPlanetDirectoryPro header sets the SSO token for a user who has access to perform the operation.

$ curl \
 --request PUT \
 --header "iPlanetDirectoryPro: AQIC5..." \
 --header "Content-Type: application/json" \
 --data '{
    "name": "myApplication",
    "resources": [
        "http://www.example.com:8080/*",
        "http://www.example.com:8080/*?*"
    ],
    "actions": {
        "UPDATE": false,
        "PATCH": false,
        "QUERY": true,
        "CREATE": false,
        "DELETE": false,
        "READ": true,
        "ACTION": false
    },
    "conditions": [
        "SimpleTime"
    ],
    "realm": "/",
    "applicationType": "iPlanetAMWebAgentService",
    "description": "Updated application with fewer conditions and subjects",
    "resourceComparator": "com.sun.identity.entitlement.URLResourceName",
    "subjects": [
        "AuthenticatedUsers",
        "JwtClaim"
    ],
    "entitlementCombiner": "DenyOverride",
    "saveIndex": null,
    "searchIndex": null,
    "attributeNames": []
}' \
 https://openam.example.com:8443/openam/json/applications/myApplication
{
  "name" : "myApplication",
  "resources" : [
    "http://www.example.com:8080/*",
    "http://www.example.com:8080/*?*"
  ],
  "actions" : {
    "UPDATE" : false,
    "PATCH" : false,
    "QUERY" : true,
    "CREATE" : false,
    "DELETE" : false,
    "READ" : true,
    "ACTION" : false
  },
  "conditions" : [
    "SimpleTime"
  ],
  "realm" : "/",
  "creationDate" : 1398762194628,
  "lastModifiedDate" : 1398762194628,
  "createdBy" : "id=amadmin,ou=user,dc=openam,dc=forgerock,dc=org",
  "lastModifiedBy" : "id=amadmin,ou=user,dc=openam,dc=forgerock,dc=org",
  "applicationType" : "iPlanetAMWebAgentService",
  "description" : "Updated application with fewer conditions and subjects",
  "resourceComparator" : "com.sun.identity.entitlement.URLResourceName",
  "subjects" : [
    "AuthenticatedUsers",
    "JwtClaim"
  ],
  "entitlementCombiner" : "DenyOverride",
  "saveIndex" : null,
  "searchIndex" : null,
  "attributeNames" : [ ]
}
   

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.

To delete an application definition, perform an HTTP DELETE specifying the resource name.

The iPlanetDirectoryPro header sets the SSO token for a user who has access to perform the operation.

$ curl \
 --request DELETE \
 --header "iPlanetDirectoryPro: AQIC5..." \
 https://openam.example.com:8443/openam/json/applications/myApplication
{}
   

To list application definitions, perform an HTTP GET on the endpoint, setting the _queryFilter query string parameter.

$ curl \
 --header "iPlanetDirectoryPro: AQIC5..." \
 https://openam.example.com:8443/openam/json/applications?_queryFilter=true
   
{
  "result" : [ {
    "name" : "myApplication",
    "resources" : [
      "http://www.example.com:8080/*",
      "http://www.example.com:8080/*?*"
    ],
    "actions" : {
      "POST" : true,
      "PATCH" : true,
      "GET" : true,
      "DELETE" : true,
      "OPTIONS" : true,
      "PUT" : true,
      "HEAD" : true
    },
    "conditions" : [
      "SimpleTime"
    ],
    "attributeNames" : [
    ],
    "realm":"/",
    "creationDate":1416428109115,
    "lastModifiedDate":1416428109115,
    "lastModifiedBy":"id=dsameuser,ou=user,dc=openam,dc=forgerock,dc=org",
    "subjects":[
      "JwtClaim",
      "AuthenticateUsers"
    ],
    "description":"Updated application with fewer conditions and subjects",
    "createdBy":id=dsameuser,ou=user,dc=openam,dc=forgerock,dc=org",
    "applicationType":"iPlanetAMWebServices",
    "entitlementCombiner":"DenyOverride",
    },
  ],
  "resultCount":1,
  "pagedResultsCookie":null,
  "remainingPagedResults":0
}
   

The _queryFilter parameter can take true to match every policy, false to match no policies, or a filter of the following form to match field values: field operator value where field represents the field name, operator is the operator code, value is the value to match, and the entire filter is URL-encoded. Supported operators are as follows:

The String fields only support the eq operator, which is implemented using regular expression pattern matching.

The Date files support the eq, ge, gt, le, and lt operators. The implementation of eq for the Date fields do not use regular expression pattern matching.

Filters can be composed of multiple expressions by a using boolean operator AND, and by using parentheses, (expression), to group expressions. You must URL encode the filter expression in _queryFilter=filter.

Since regular expressions are implemented for some operators, you can specify a filter that can include or exclude specified elements. For example, the following query searches for application names containing 'iPlanet'. The queryFilter string is URL-encoded.

$ curl --header "iPlanetDirectoryPro" AQIC5..." \
https://openam.example.com:8443/openam/json/applications?_queryFilter=name%20eq%20%22iPlanet.*%22
   

You can use the query string parameters _prettyPrint=true to make the output easier to read, _fields=field-name[,field-name...] to limit the fields returned in the output.

You can use _pageSize=integer to limit the number of results returned.

To read an application type, perform an HTTP GET specifying the resource name.

The iPlanetDirectoryPro header sets the SSO token for a user who has access to perform the operation.

$ curl \
 --header "iPlanetDirectoryPro: AQIC5..." \
 https://openam.example.com:8443/openam/json/applicationtypes/crestPolicyService
{
  "name" : "crestPolicyService",
  "actions" : {
    "UPDATE" : true,
    "PATCH" : true,
    "QUERY" : true,
    "CREATE" : true,
    "DELETE" : true,
    "READ" : true,
    "ACTION" : true
  },
  "resourceComparator" : "com.sun.identity.entitlement.URLResourceName",
  "saveIndex" : "org.forgerock.openam.entitlement.indextree.TreeSaveIndex",
  "searchIndex" : "org.forgerock.openam.entitlement.indextree.TreeSearchIndex",
  "applicationClassName" : "com.sun.identity.entitlement.Application"
}

   

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.

To list application types, perform an HTTP GET on the endpoint, setting the _queryFilter query string parameter as in the following example:

$ curl \
 --header "iPlanetDirectoryPro: AQIC5..." \
 https://openam.example.com:8443/openam/json/applicationtypes?_queryFilter=true
{
  "result" : [ ... application types ... ],
  "resultCount" : 8,
  "pagedResultsCookie" : null,
  "remainingPagedResults" : -1
}
   

To read a environment condition type, perform an HTTP GET specifying the resource name.

The iPlanetDirectoryPro header sets the SSO token for a user who has access to perform the operation.

You can use the query string parameter _prettyPrint=true to make the output easier to read.

$ curl \
 --header "iPlanetDirectoryPro: AQIC5..." \
 https://openam.example.com:8443/openam/json/conditiontypes/IPv4
{
  "title" : "IPv4",
  "logical" : false,
  "config" : {
    "type" : "object",
    "properties" : {
      "startIp" : {
        "type" : "string"
      },
      "endIp" : {
        "type" : "string"
      },
      "dnsName" : {
        "type" : "array",
        "items" : {
          "type" : "string"
        }
      }
    }
  }
}
   

Notice that the environment condition type has a title, a "logical" field that indicates whether the type is a logical operator or takes a predicate, and a configuration specification. The configuration specification in this case indicates that an IPv4 environment condition has two properties, "startIp" and "endIp", that each take a single string value, and a third property, "dnsName," that takes an array of string values. In other words, a concrete IP environment condition specification without a DNS name constraint could be represented in a policy definition as in the following example:

{
   "type": "IPv4",
   "startIp": "127.0.0.1",
   "endIp": "127.0.0.255"
}
   

The configuration is what differs the most across environment condition types. The NOT condition, for example, takes a single condition object as the body of its configuration.

$ curl \
 --header "iPlanetDirectoryPro: AQIC5..." \
 https://openam.example.com:8443/openam/json/conditiontypes
    /NOT
{
  "title" : "NOT",
  "logical" : true,
  "config" : {
    "type" : "object",
    "properties" : {
      "condition" : {
        "type" : "object",
        "properties" : {
        }
      }
    }
  }
}
   

The concrete NOT condition therefore takes the following form.

{
    "type": "NOT",
    "condition": {
        ...
    }
}
   

The OR condition takes an array of conditions.

$ curl \
 --header "iPlanetDirectoryPro: AQIC5..." \
 https://openam.example.com:8443/openam/json/conditiontypes/OR
{
  "title" : "OR",
  "logical" : true,
  "config" : {
    "type" : "object",
    "properties" : {
      "conditions" : {
        "type" : "array",
        "items" : {
          "type" : "any"
        }
      }
    }
  }
}
   

A corresponding concrete OR condition thus takes the following form.

{
    "type": "OR",
    "conditions": [
        {
            ...
        },
        {
            ...
        },
        ...
    ]
}
   

To list all environment condition types, perform an HTTP GET on the endpoint, setting the query string parameter, _queryFilter=true, as in the following example:

$ curl \
 --header "iPlanetDirectoryPro: AQIC5..." \
 https://openam.example.com:8443/openam/json/conditiontypes?_queryFilter=true
{
  "result" : [ ... condition types ... ],
  "resultCount" : 18,
  "pagedResultsCookie" : null,
  "remainingPagedResults" : 0
}
   

You can use the query string parameter _prettyPrint=true to make the output easier to read.

To read a subject condition type, perform an HTTP GET specifying the resource name.

The iPlanetDirectoryPro header sets the SSO token for a user who has access to perform the operation.

You can use the query string parameter _prettyPrint=true to make the output easier to read.

$ curl \
 --header "iPlanetDirectoryPro: AQIC5..." \
 https://openam.example.com:8443/openam/json/subjecttypes/Identity
{
  "title" : "Identity",
  "logical" : false,
  "config" : {
    "type" : "object",
    "properties" : {
      "subjectValues" : {
        "type" : "array",
        "items" : {
          "type" : "string"
        }
      }
    }
  }
}
   

Notice that the subject type has a title, a "logical" field that indicates whether the type is a logical operator or takes a predicate, and a configuration specification. The configuration specification in this case indicates that an Identity subject condition has one property, "subjectValues", which takes an array of string values. In other words, a concrete Identity subject condition specification is represented in a policy definition as in the following example:

{
   "type": "Identity",
   "subjectValues": [
       "uid=scarter,ou=People,dc=example,dc=com"
   ]
}
   

The configuration is what differs the most across subject condition types. The AND condition, for example, takes an array of subject condition objects as the body of its configuration.

$ curl \
 --header "iPlanetDirectoryPro: AQIC5..." \
 https://openam.example.com:8443/openam/json/subjecttypes/AND
{
  "title" : "AND",
  "logical" : true,
  "config" : {
    "type" : "object",
    "properties" : {
      "subjects" : {
        "type" : "array",
        "items" : {
          "type" : "any"
        }
      }
    }
  }
}
   

The concrete AND subject condition therefore takes the following form.

{
    "type": "AND",
    "subject": [
      {
        ...
      },
      ...
    ]
}
   

To list all subject condition types, perform an HTTP GET on the endpoint, setting the query string parameter, _queryFilter=true, as in the following example:

$ curl \
 --header "iPlanetDirectoryPro: AQIC5..." \
 https://openam.example.com:8443/openam/json/subjecttypes/?_queryFilter=true
{
  "result" : [ ... subject types ... ],
  "resultCount" : 8,
  "pagedResultsCookie" : null,
  "remainingPagedResults" : 0
}
   

You can use the query string parameter _prettyPrint=true to make the output easier to read.

To create a referral, either perform an HTTP PUT indicating the full path to the resource and the name in the resource matching the name in the path, or perform an HTTP POST with the name to use specified in the resource.

Do not use special characters within policy, application or referral names (for example, "my+referral") using the Policy Editor or REST endpoints as OpenAM returns a 400 Bad Request error. The special characters are: double quotes ("), plus sign (+), comma (,), less than (<), equals (=), greater than (>), backslash (\), and null (\u0000).

The HTTP PUT form includes the referral definition as the JSON resource data, with the header Content-Type: application/json and uses the If-None-Match: * header.

The iPlanetDirectoryPro header sets the SSO token for a user who has access to perform the operation.

The following example creates a referral named MyReferral in the top-level realm. The referral causes OpenAM policy evaluation to search for policies defined in the /MySubrealm and /MySubrealm/ChildSubrealms realms that have application type iPlanetAMWebAgentService and protect pages under http://example.com/hr/.

    $ curl \
    --request PUT \
    --header "iPlanetDirectoryPro: AQIC5w..." \
    --header "If-None-Match: *" \
    --header "Content-Type: application/json" \
    --data '{
      "name": "MyReferral",
      "description": "Look for policies in two additional subrealms to protect HR pages",
      "resources": {
        "iPlanetAMWebAgentService" : [ "http://example.com/hr/*"://example.com/hr/*"]
      },
      "realms" : ["/MySubrealm", "/MySubrealm/ChildSubrealm"]
    }' \
    https://openam.example.com:8443/openam/json/referrals/MyReferral
   
    {
     "creationDate" : 1416956012949,
     "lastModifiedDate" : 1416956012949,
     "realms" : [ "/MySubrealm", "/MySubrealm/ChildSubrealm" ],
     "createdBy" : "id=amadmin,ou=user,dc=example,dc=com",
     "lastModifiedBy" : "id=amadmin,ou=user,dc=example,dc=com",
     "resources" : {
       "iPlanetAMWebAgentService" : [ "http://example.com/hr/*" ://example.com/hr/*" ]
     },
     "name" : "MyReferral"
    }
   

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.

The HTTP POST form includes the referral definition as the JSON resource data, with the header Content-Type: application/json and uses the _action=create operation.

The iPlanetDirectoryPro header sets the SSO token for a user who has access to perform the operation.

    $ curl \
    --request POST \
    --header "iPlanetDirectoryPro: AQIC5..." \
    --header "Content-Type: application/json" \
    --data '{
      "name": "MyReferralTwo",
      "description": "Look for policies in two additional subrealms to protect IT pages",
      "resources": {
        "iPlanetAMWebAgentService" : [ "http://example.com/it/*"://example.com/it/*"]
      },
      "realms" : ["/MySubrealm", "/MySubrealm/ChildSubrealm"]
    }' \
    https://openam.example.com:8443/openam/json/referrals?_action=create
   
   
   {
     "creationDate" : 1416956884965,
     "lastModifiedDate" : 1416956884965,
     "realms" : [ "/MySubrealm", "/MySubrealm/ChildSubrealm" ],
     "createdBy" : "id=amadmin,ou=user,dc=example,dc=com",
     "lastModifiedBy" : "id=amadmin,ou=user,dc=example,dc=com",
     "resources" : {
       "iPlanetAMWebAgentService" : [ "http://example.com/it/*" ://example.com/it/*" ]
     },
     "name" : "MyReferralTwo"
   }
   
   

To read a referral definition, perform an HTTP GET specifying the resource name.

The iPlanetDirectoryPro header sets the SSO token for a user who has access to perform the operation.

    $ curl \
    --header "iPlanetDirectoryPro: AQIC5..." \
    https://openam.example.com:8443/openam/json/referrals/MyReferral
   
   
   {
     "creationDate" : 1416956012949,
     "lastModifiedDate" : 1416956012949,
     "realms" : [ "/MySubrealm", "/MySubrealm/ChildSubrealm" ],
     "createdBy" : "id=amadmin,ou=user,dc=example,dc=com",
     "lastModifiedBy" : "id=amadmin,ou=user,dc=example,dc=com",
     "resources" : {
       "iPlanetAMWebAgentService" : [ "http://example.com/hr/*" ://example.com/hr/*" ]
     },
     "name" : "MyReferral"
   }
   

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.

To update a referral, perform an HTTP PUT specifying the resource name with the referral definition as the JSON resource data, and with the header Content-Type: application/json. This is essentially the same as creating a referral, but without the If-None-Match: * header.

The iPlanetDirectoryPro header sets the SSO token for a user who has access to perform the operation.

    $ curl \
    --request PUT \
    --header "iPlanetDirectoryPro: AQIC5w..." \
    --header "Content-Type: application/json" \
    --data '{
      "name": "MyReferral",
      "description": "Update referral to protect HR US pages only",
      "resources": {
        "iPlanetAMWebAgentService" : [ "http://example.com/hr/us/*"://example.com/hr/us/*"]
      },
      "realms" : ["/MySubrealm", "/MySubrealm/ChildSubrealm"]
    }' \
    https://openam.example.com:8443/openam/json/referrals/MyReferral
   
   
   {
     "creationDate" : 1416959024216,
     "lastModifiedDate" : 1416959024216,
     "realms" : [ "/MySubrealm", "/MySubrealm/ChildSubrealm" ],
     "createdBy" : "id=amadmin,ou=user,dc=example,dc=com",
     "lastModifiedBy" : "id=amadmin,ou=user,dc=example,dc=com",
     "resources" : {
       "iPlanetAMWebAgentService" : [ "http://example.com/hr/us/*" ://example.com/hr/us/*" ]
     },
     "name" : "MyReferral"
   }
   
   

     $ curl \
     --request PUT \
     --header "iPlanetDirectoryPro: AQIC5w..." \
     --header "Content-Type: application/json" \
     --data '{
       "name": "MyReferralHRUS",
       "description": "Update referral to protect HR US pages only",
       "resources": {
         "iPlanetAMWebAgentService" : [ "http://example.com/hr/us/*"://example.com/hr/us/*"]
       },
       "realms" : ["/MySubrealm", "/MySubrealm/ChildSubrealm"]
     }' \
     https://openam.example.com:8443/openam/json/referrals/MyReferral
    
    
    {
      "creationDate" : 1416959240491,
      "lastModifiedDate" : 1416959240491,
      "realms" : [ "/MySubrealm", "/MySubrealm/ChildSubrealm" ],
      "createdBy" : "id=amadmin,ou=user,dc=example,dc=com",
      "lastModifiedBy" : "id=amadmin,ou=user,dc=example,dc=com",
      "resources" : {
        "iPlanetAMWebAgentService" : [ "http://example.com/hr/us/*" ://example.com/hr/us/*" ]
      },
      "name" : "MyReferralHRUS"
    }
    

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.

To delete a referral, perform an HTTP DELETE specifying the resource name.

The iPlanetDirectoryPro header sets the SSO token for a user who has access to perform the operation.

    $ curl \
    --header "iPlanetDirectoryPro: AQIC5w..." \
    --request DELETE \
    https://openam.example.com:8443/openam/json/referrals/MyReferralHRUS
    {}
   

To list referrals, perform an HTTP GET on the endpoint, setting the _queryFilter query string parameter.

    $ curl \
    --header "iPlanetDirectoryPro: AQIC5w..." \
    https://openam.example.com:8443/openam/json/referrals?_queryFilter=true
   
   
   {
     "result" : [ {
       "creationDate" : 1416956689230,
       "lastModifiedDate" : 1416956689230,
       "realms" : [ "/MySubrealm", "/MySubrealm/ChildSubrealm" ],
       "createdBy" : "id=amadmin,ou=user,dc=example,dc=com",
       "lastModifiedBy" : "id=amadmin,ou=user,dc=example,dc=com",
       "resources" : {
         "iPlanetAMWebAgentService" : [ "http://example.com/it/*" ://example.com/it/*" ]
       },
       "name" : "MyReferralOne"
       }, {
       "creationDate" : 1416956884965,
       "lastModifiedDate" : 1416956884965,
       "realms" : [ "/MySubrealm", "/MySubrealm/ChildSubrealm" ],
       "createdBy" : "id=amadmin,ou=user,dc=example,dc=com",
       "lastModifiedBy" : "id=amadmin,ou=user,dc=example,dc=com",
       "resources" : {
         "iPlanetAMWebAgentService" : [ "http://example.com/finance/*" ://example.com/finance/*" ]
       },
       "name" : "MyReferralTwo"
     } ],
     "resultCount" : 2,
     "pagedResultsCookie" : null,
     "remainingPagedResults" : 2
   }
   
   

The _queryFilter parameter can take true to match every referral, false to match no referrals, or a filter of the following form to match field values: field operator value where field represents the field name, operator is the operator code, value is the value to match, and the entire filter is URL-encoded. Supported operators are as follows:

Filters can be composed of multiple expressions by a using boolean operator AND, and by using parentheses, (expression), to group expressions. You must URL encode the filter expression in _queryFilter=filter.

You can use the query string parameters _prettyPrint=true to make the output easier to read, _fields=field-name[,field-name...] to limit the fields returned in the output.

You can use _pageSize=integer to limit the number of results returned.

You can use _sortKeys=[+-]field[,field...] to sort the results returned, where field represents a field in the JSON referral objects returned. Optionally use the + prefix to sort in ascending order (the default), or - to sort in descending order. The following example sorts the referrals by their names in descending order.

    $ curl \
    --header "iPlanetDirectoryPro: AQIC5w..." \
    https://openam.example.com:8443/openam/json/referrals?_queryFilter=true\&_sortKeys=-name
    
    {
      "result" : [ {
        "name" : "MyReferralTwo"
       }, {
         "name" : "MyReferralOne"
       } ],
       "resultCount" : 2,
       "pagedResultsCookie" : null,
       "remainingPagedResults" : 2
     }
    
   

OpenAM provides additional REST APIs for requesting policy decisions.

Authentication for these interfaces uses cookies, so if your application is not running in a browser, first authenticate as described in REST APIs for Authentication & Logout.

To request a decision for a single resource, use an HTTP GET on /ws/1/entitlement/decision as in the following example:

$ curl \
 --request GET \
 --cookie "iPlanetDirectoryPro=AQIC5...DU3*" \
 "https://openam.example.com:8443/openam/ws/1/entitlement/decision\
?subject=MJ3QFTr4ZV2QrtlJvXlg0Q2dMRM=&action=GET\
&application=iPlanetAMWebAgentService\
&resource=http%3A%2F%2Fwww.example.com%2Findex.html"
allow
   

If access is denied, the result is deny.

To request decisions for multiple resources, use an HTTP GET on /ws/1/entitlement/decisions as in the following example:

$ curl \
 --request GET \
 --cookie "iPlanetDirectoryPro=AQIC5...DU3*" \
 "https://openam.example.com:8443/openam/ws/1/entitlement/decisions\
?subject=MJ3QFTr4ZV2QrtlJvXlg0Q2dMRM=&action=GET\
&application=iPlanetAMWebAgentService\
&resources=http%3A%2F%2Fwww.example.com%2Findex.html\
&resources=http%3A%2F%2Fwww.example.com%2Ffavicon.ico"
{
    "statusCode": 200,
    "body": {
        "results": [
            {
                "actionsValues": {
                    "POST": true,
                    "GET": true
                },
                "attributes": {},
                "advices": {},
                "resourceName": "http://www.example.com:80/index.html"
            },
            {
                "actionsValues": {
                    "POST": true,
                    "GET": true
                },
                "attributes": {},
                "advices": {},
                "resourceName": "http://www.example.com:80/favicon.ico"
            }
        ]
    },
    "statusMessage": "OK"
}
   

To request decisions for a given resource, use an HTTP GET on /ws/1/entitlement/entitlement as in the following example:

$ curl \
 --request GET \
 --cookie "iPlanetDirectoryPro=AQIC5...DU3*" \
 "https://openam.example.com:8443/openam/ws/1/entitlement/entitlement\
?subject=MJ3QFTr4ZV2QrtlJvXlg0Q2dMRM=\
&application=iPlanetAMWebAgentService\
&resource=http%3A%2F%2Fwww.example.com%2F*"
{
    "statusCode": 200,
    "body": {
        "actionsValues": {
            "POST": true,
            "GET": true
        },
        "attributes": {},
        "advices": {},
        "resourceName": "http://www.example.com:80/*"
    },
    "statusMessage": "OK"
}
   

To request decisions for all resources underneath a given resource, use an HTTP GET on /ws/1/entitlement/entitlements as in the following example:

$ curl \
 --request GET \
 --cookie "iPlanetDirectoryPro=AQIC5...DU3*" \
 "https://openam.example.com:8443/openam/ws/1/entitlement/entitlements\
?subject=MJ3QFTr4ZV2QrtlJvXlg0Q2dMRM=\
&application=iPlanetAMWebAgentService\
&resource=http%3A%2F%2Fwww.example.com%2F"
{
    "statusCode": 200,
    "body": {
        "results": [
            {
                "actionsValues": {},
                "resourceName": "http://www.example.com:80/"
            },
            {
                "actionsValues": {
                    "POST": true,
                    "GET": true
                },
                "advices": {},
                "resourceName": "http://www.example.com:80/*"
            },
            {
                "actionsValues": {
                    "POST": true,
                    "GET": true
                },
                "attributes": {},
                "advices": {},
                "resourceName": "http://www.example.com:80/*?*"
            }
        ]
    },
    "statusMessage": "OK"
}
   

As described in the Administration Guide chapter on Managing OAuth 2.0 Authorization in the Administration Guide, OpenAM exposes REST endpoints for making calls to OpenAM acting as an authorization server.

The /oauth2/authorize, and /oauth2/access_token endpoints function as described in RFC 6749.

The /oauth2/authorize endpoint is protected by the policy created during OAuth 2.0 authorization server configuration, which grants all authenticated users access.

The /oauth2/tokeninfo endpoint takes an HTTP GET on /oauth2/tokeninfo?access_token=token-id, and returns information about the token.

Resource servers — or any party having the token ID — can get token information through this endpoint without authenticating. This means any application or user can validate the token without having to be registered with OpenAM.

The following example shows OpenAM issuing an access token, and then returning token information:

$ curl \
 --request POST \
 --user "myClientID:password" \
 --data "grant_type=password&username=demo&password=changeit&scope=cn%20mail" \
 https://openam.example.com:8443/openam/oauth2/access_token
{
    "expires_in": 599,
    "token_type": "Bearer",
    "refresh_token": "f6dcf133-f00b-4943-a8d4-ee939fc1bf29",
    "access_token": "f9063e26-3a29-41ec-86de-1d0d68aa85e9"
}

$ curl https://openam.example.com:8443/openam/oauth2/tokeninfo\
?access_token=f9063e26-3a29-41ec-86de-1d0d68aa85e9
{
    "mail": "demo@example.com",
    "scope": [
        "mail",
        "cn"
    ],
    "cn": "demo",
    "realm": "/",
    "token_type": "Bearer",
    "expires_in": 577,
    "access_token": "f9063e26-3a29-41ec-86de-1d0d68aa85e9"
}
   

The resource server making decisions about whether the token is valid can thus use the /oauth2/tokeninfo endpoint to retrieve expiration information about the token. Depending on the scopes implementation, the JSON response about the token can also contain scope information. As described in the Administration Guide, the default scopes implementation in OpenAM considers scopes to be names of attributes in the resource owner's user profile. Notice that the JSON response contains the values for those attributes from the user's profile, as in the preceding example, with scopes set to mail and cn.

Both the /oauth2/authorize and /oauth2/access_token endpoints can take additional parameters. In particular you must specify the realm using the realm=realm-name parameter if the OpenAM OAuth 2.0 provider is configured for a subrealm rather than / (Top-Level Realm). For example, if the OAuth 2.0 provider is configured for the /customers realm, then use /oauth2/authorize?realm=/customers and /oauth2/access_token?realm=/customers. The realm can be passed either as a URL query string parameter as shown here, or as parameters in the POST data.

The /oauth2/authorize endpoint can also take module and service parameters. Use either as described in Authenticating To OpenAM in the Administration Guide, where module specifies the authentication module instance to use or service specifies the authentication chain to use when authenticating the resource owner.

The OpenAM-specific OAuth 2.0 token administration endpoint lets administrators read, list, and delete OAuth 2.0 tokens. OAuth 2.0 clients can also manage their own tokens.

OpenAM exposes the token administration endpoint at /frrest/oauth2/token, such as https://openam.example.com:8443/openam/frrest/oauth2/token.

To get a token, perform an HTTP GET on /frrest/oauth2/token/token-id, as in the following example:

$ curl \
 --request POST \
 --user "myClientID:password" \
 --data "grant_type=password&username=demo&password=changeit&scope=cn" \
 https://openam.example.com:8443/openam/oauth2/access_token
{
    "scope": "cn",
    "expires_in": 60,
    "token_type": "Bearer",
    "access_token": "f5fb4833-ba3d-41c8-bba4-833b49c3fe2c"
}

$ curl \
 --header "iplanetDirectoryPro: AQIC5wM2LY4Sfcxs...EwNDU2NjE0*" \
 https://openam.example.com:8443/openam/frrest/oauth2/token/9c6a48fc...fba468b0f
{
    "expireTime": [
        "1418818601396"
    ],
    "tokenName": [
        "access_token"
    ],
    "scope": [
        "cn"
    ],
    "grant_type": [
        "password"
    ],
    "clientID": [
        "myClientID"
    ],
    "parent": [],
    "id": [
        "f5fb4833-ba3d-41c8-bba4-833b49c3fe2c"
    ],
    "tokenType": [
        "Bearer"
    ],
    "redirectURI": [],
    "nonce": [],
    "realm": [
        "/"
    ],
    "userName": [
        "demo"
    ]
}
   

To list tokens, perform an HTTP GET on /frrest/oauth2/token/?_queryId=string, where string is either access_token to request the list of access tokens for the current user or all users if requested by amAdmin, or any other string to request the list of access tokens and refresh tokens.

The following example shows a search for the demo user's access tokens.

$ curl \
 --header "iplanetDirectoryPro: AQIC5wM2LY4Sfcw..." \
 https://openam.example.com:8443/openam/frrest/oauth2/token/?_queryId=access_token
{
    "result": [
        {
            "expireTime": "Dec 17, 2014 1:02 PM",
            "tokenName": [
                "access_token"
            ],
            "scope": [
                "cn"
            ],
            "grant_type": [
                "password"
            ],
            "clientID": [
                "myClientID"
            ],
            "parent": [],
            "id": [
                "d2bbd4f9-955f-4683-bb83-bc0d7523b0f9"
            ],
            "tokenType": [
                "Bearer"
            ],
            "redirectURI": [],
            "nonce": [],
            "realm": [
                "/"
            ],
            "userName": [
                "demo"
            ],
            "display_name": "",
            "scopes": "cn"
        },
        {
            "expireTime": "Dec 17, 2014 1:02 PM",
            "tokenName": [
                "access_token"
            ],
            "scope": [
                "cn"
            ],
            "grant_type": [
                "password"
            ],
            "clientID": [
                "myClientID"
            ],
            "parent": [],
            "id": [
                "12f9907f-dbfb-4c4c-a231-2b24964fee8b"
            ],
            "tokenType": [
                "Bearer"
            ],
            "redirectURI": [],
            "nonce": [],
            "realm": [
                "/"
            ],
            "userName": [
                "demo"
            ],
            "display_name": "",
            "scopes": "cn"
        }
    ],
    "resultCount": 2,
    "pagedResultsCookie": null,
    "remainingPagedResults": -1
}
   

To delete a token, perform an HTTP DELETE on /frrest/oauth2/token/token-id, as in the following example:

$ curl \
 --request POST \
 --data "grant_type=client_credentials&username=demo&password=changeit\
&client_id=myClientID&client_secret=password&scope=cn%20mail" \
 https://openam.example.com:8443/openam/oauth2/access_token
{
    "expires_in": 599,
    "token_type": "Bearer",
    "access_token": "867aaab2-61d7-4b78-9b80-4f9098034540"
}

$ curl \
 --request DELETE \
 --header "iplanetDirectoryPro: AQIC5wM2LY4Sfcxs...EwNDU2NjE0*" \
 https://openam.example.com:8443/openam/frrest/oauth2/token/867aaab2..098034540
{
    "success": "true"
}
   

The OAuth 2.0 administration endpoint lets OpenAM administrators and agent administrators create (that is, register) and delete OAuth 2.0 clients.

OpenAM exposes this endpoint at /frrest/oauth2/client, such as https://openam.example.com:8443/openam/frrest/oauth2/client.

To create an OAuth 2.0 client, perform an HTTP POST to /frrest/oauth2/client/?_action=create with a JSON object fully specifying the client, as in the following example.

$ curl \
 --request POST \
 --header "iplanetDirectoryPro: AQIC5wM...3MTYxOA..*" \
 --header "Content-Type: application/json" \
 --data \
 '{"client_id":["testClient"],
   "realm":["/"],
   "userpassword":["secret12"],
   "com.forgerock.openam.oauth2provider.clientType":["Confidential"],
   "com.forgerock.openam.oauth2provider.redirectionURIs":
     ["www.client.com","www.example.com"],
   "com.forgerock.openam.oauth2provider.scopes":["cn","sn"],
   "com.forgerock.openam.oauth2provider.defaultScopes":["cn"],
   "com.forgerock.openam.oauth2provider.name":["My Test Client"],
   "com.forgerock.openam.oauth2provider.description":["OAuth 2.0 Client"]
  }' \
 https://openam.example.com:8443/openam/frrest/oauth2/client/?_action=create
{"success":"true"}
   

To delete an OAuth 2.0 client, perform an HTTP DELETE on /frrest/oauth2/client/client-id, as in the following example:

$ curl \
 --request DELETE \
 --header "iplanetDirectoryPro: AQIC5wM...3MTYxOA..*" \
 https://openam.example.com:8443/openam/frrest/oauth2/client/myClient
{"success":"true"}
   

$ curl \
 --request DELETE \
 --header "iplanetDirectoryPro: AQIC5wM...3MTYxOA..*" \
 https://openam.example.com:8443/openam/frrest/oauth2/client/myClient?realm=myRealm
{"success":"true"}

OpenAM exposes endpoints for discovering information about the provider configuration, and about the provider for a given end user.

For examples, see Configuring OpenAM For OpenID Connect Discovery in the Administration Guide.

OpenAM allows both static and dynamic registration of OpenID Connect client applications. For dynamic registration according to the OpenID Connect Dynamic Client Registration 1.0 specification, the endpoint is /oauth2/connect/register. See To Register a Client Dynamically in the Administration Guide for details.

Registered clients can request authorization through OpenAM.

OpenID Connect 1.0 supports both a Basic Client Profile using the OAuth 2.0 authorization code grant, and an Implicit Client Profile using the OAuth 2.0 implicit grant. These client profiles rely on the OAuth 2.0 endpoints for authorization. Those endpoints are described in "OAuth 2.0 Client & Resource Server Endpoints".

In addition, authorized clients can access end user information through the OpenID Connect 1.0 specific endpoint /oauth2/userinfo.

For examples, see Client Examples in the Administration Guide.

Registered clients can use OpenID Connect Session Management 1.0 to handle end user logout actions.

For an example, see Managing User Sessions in the Administration Guide.

OpenAM lets administrators create a user profile by making an HTTP POST of the JSON representation of the profile to /json/subrealm/users/?_action=create. To add a user to the Top Level Realm, you do not need to specify the realm.

The following example shows an administrator creating a new user. The only required fields are username and userpassword. If no other name is provided, the entry you make for username defaults to both the user id and the user's last name.

$ curl \
 --request POST \
 --header "iplanetDirectoryPro: AQIC5w...2NzEz*" \
 --header "Content-Type: application/json" \
 --data \
 '{
   "username": "bjensen",
   "userpassword": "secret12",
   "mail": "bjensen@example.com"
 }' \
 https://openam.example.com:8443/openam/json/users/?_action=create
{
    "username": "bjensen",
    "realm": "/",
    "uid": [
        "bjensen"
    ],
    "mail": [
        "bjensen@example.com"
    ],
    "sn": [
        "bjensen"
    ],
    "userpassword": [
        "{SSHA}0pXpKLPRKCGY7g3YqZygJmKMW6IC2BLJimmlwg=="
    ],
    "cn": [
        "bjensen"
    ],
    "inetuserstatus": [
        "Active"
    ],
    "dn": [
        "uid=bjensen,ou=people,dc=openam,dc=forgerock,dc=org"
    ],
    "objectclass": [
        "person",
        "sunIdentityServerLibertyPPService",
        "sunFederationManagerDataStore",
        "inetorgperson",
        "iPlanetPreferences",
        "iplanet-am-auth-configuration-service",
        "organizationalperson",
        "sunFMSAML2NameIdentifier",
        "inetuser",
        "iplanet-am-managed-person",
        "sunAMAuthAccountLockout",
        "iplanet-am-user-service",
        "top"
    ],
    "universalid": [
        "id=bjensen,ou=user,dc=openam,dc=forgerock,dc=org"
    ]
}
   

Alternatively, administrators can create user profiles with specific user IDs by doing an HTTP PUT of the JSON representation of the changes to /json/users/user-id, as shown in the following example:

$ curl \
 --request PUT \
 --header "iplanetDirectoryPro: AQIC5w...2NzEz*" \
 --header "Content-Type: application/json" \
 --header "If-None-Match: *" \
 --data \
 '{
   "username": "janedoe",
   "userpassword": "secret12",
   "mail": "janedoe@example.com"
 }' \
 https://openam.example.com:8443/openam/json/users/janedoe
{
    "username": "janedoe",
    "realm": "/",
    "uid": [
        "janedoe"
    ],
    "mail": [
        "janedoe@example.com"
    ],
    "sn": [
        "janedoe"
    ],
    "userpassword": [
        "{SSHA}e4DJoxvYVW/nsp62XJf29ZADE16YQgrxK+XuKA=="
    ],
    "cn": [
        "janedoe"
    ],
    "inetuserstatus": [
        "Active"
    ],
    "dn": [
        "uid=janedoe,ou=people,dc=openam,dc=forgerock,dc=org"
    ],
    "objectclass": [
        "devicePrintProfilesContainer",
        "person",
        "sunIdentityServerLibertyPPService",
        "inetorgperson",
        "sunFederationManagerDataStore",
        "iPlanetPreferences",
        "iplanet-am-auth-configuration-service",
        "organizationalperson",
        "sunFMSAML2NameIdentifier",
        "inetuser",
        "forgerock-am-dashboard-service",
        "iplanet-am-managed-person",
        "iplanet-am-user-service",
        "sunAMAuthAccountLockout",
        "top"
    ],
    "universalid": [
        "id=janedoe,ou=user,dc=openam,dc=forgerock,dc=org"
    ]
}
    

As shown in the examples, OpenAM returns the JSON representation of the profile on successful creation. On failure, OpenAM returns a JSON representation of the error including the HTTP status code. For example, version 2.0 of the CREST /json/users, /json/groups, and /json/agents endpoints return 403 if the user making the request is not authorized to do so.

The same HTTP POST and PUT mechanisms also work for other objects such as policy agent profiles and groups.

$ curl \
 --request POST \
 --header "iPlanetDirectoryPro: AQIC5w...2NzEz*" \
 --header "Content-Type: application/json" \
 --data \
 '{
   "name":"myWebAgent","realm":"/",
   "com.sun.identity.agents.config.fqdn.default":["www.example.com"],
   "sunidentityserverdevicekeyvalue":
     ["agentRootURL=http://www.example.com:80/"],
   "com.sun.identity.agents.config.remote.logfile":
     ["amAgent_www_example_com_80.log"],
   "com.sun.identity.agents.config.repository.location":["centralized"],
   "agenttype":["WebAgent"],
    "com.sun.identity.agents.config.cdsso.cdcservlet.url":
     ["[0]=https://openam.example.com:8443/openam/cdcservlet"],
   "com.sun.identity.client.notification.url":
     ["http://www.example.com:80/UpdateAgentCacheServlet?shortcircuit=false"],
   "com.sun.identity.agents.config.agenturi.prefix":
     ["http://www.example.com:80/amagent"],
   "userpassword":["password"],
   "com.sun.identity.agents.config.login.url":
     ["[0]=https://openam.example.com:8443/openam/UI/Login"],
   "com.sun.identity.agents.config.logout.url":
     ["[0]=https://openam.example.com:8443/openam/UI/Logout"],
   "sunidentityserverdevicestatus":["Active"]
 }' \
 https://openam.example.com:8443/openam/json/agents/?_action=create
{
    "name": "myWebAgent",
    "realm": "/",
    "com.sun.identity.agents.config.cdsso.enable": [
        "false"
    ],
    "com.sun.identity.agents.config.cdsso.cookie.domain": [
        "[0]="
    ],
    "com.sun.identity.agents.config.get.client.host.name": [
        "false"
    ],
    "com.sun.identity.agents.config.profile.attribute.fetch.mode": [
        "NONE"
    ],
    "com.sun.identity.agents.config.notenforced.ip": [
        "[0]="
    ],
    "com.sun.identity.agents.config.fqdn.check.enable": [
        "true"
    ],
    "com.sun.identity.agents.config.cleanup.interval": [
        "30"
    ],
    "com.sun.identity.agents.config.notenforced.url.attributes.enable": [
        "false"
    ],
    "com.sun.identity.agents.config.ignore.preferred.naming.url": [
        "true"
    ],
    "com.sun.identity.agents.config.client.ip.header": [],
    "com.sun.identity.agents.config.session.attribute.mapping": [
        "[]="
    ],
    "com.sun.identity.agents.config.audit.accesstype": [
        "LOG_NONE"
    ],
    "com.sun.identity.agents.config.proxy.override.host.port": [
        "false"
    ],
    "com.sun.identity.agents.config.load.balancer.enable": [
        "false"
    ],
    "com.sun.identity.agents.config.encode.url.special.chars.enable": [
        "false"
    ],
    "com.sun.identity.agents.config.convert.mbyte.enable": [
        "false"
    ],
    "com.sun.identity.agents.config.domino.check.name.database": [
        "false"
    ],
    "com.sun.identity.agents.config.iis.owa.enable": [
        "false"
    ],
    "com.sun.identity.agents.config.override.port": [
        "false"
    ],
    "com.sun.identity.agents.config.policy.clock.skew": [
        "0"
    ],
    "com.sun.identity.agents.config.sso.only": [
        "false"
    ],
    "com.sun.identity.agents.config.iis.owa.enable.session.timeout.url": [],
    "com.sun.identity.agents.config.domino.ltpa.config.name": [
        "LtpaToken"
    ],
    "com.sun.identity.agents.config.cookie.reset": [
        "[0]="
    ],
    "com.sun.identity.agents.config.fqdn.default": [
        "www.example.com"
    ],
    "sunIdentityServerDeviceKeyValue": [
        "agentRootURL=http://www.example.com:80/"
    ],
    "com.sun.identity.agents.config.domino.ltpa.cookie.name": [
        "LtpaToken"
    ],
    "com.sun.identity.agents.config.iis.password.header": [
        "false"
    ],
    "com.sun.identity.agents.config.response.attribute.mapping": [
        "[]="
    ],
    "com.sun.identity.agents.config.userid.param.type": [
        "session"
    ],
    "com.sun.identity.agents.config.url.comparison.case.ignore": [
        "true"
    ],
    "com.sun.identity.agents.config.profile.attribute.cookie.maxage": [
        "300"
    ],
    "com.sun.identity.agents.config.remote.logfile": [
        "amAgent_www_example_com_80.log"
    ],
    "com.sun.identity.agents.config.domino.ltpa.enable": [
        "false"
    ],
    "com.sun.identity.agents.config.notenforced.url": [
        "[0]="
    ],
    "com.sun.identity.agents.config.notification.enable": [
        "true"
    ],
    "com.sun.identity.agents.config.profile.attribute.cookie.prefix": [
        "HTTP_"
    ],
    "com.sun.identity.agents.config.logout.cookie.reset": [
        "[0]="
    ],
    "com.sun.identity.agents.config.polling.interval": [
        "60"
    ],
    "com.sun.identity.agents.config.attribute.multi.value.separator": [
        "|"
    ],
    "com.sun.identity.agents.config.debug.file.rotate": [
        "true"
    ],
    "com.sun.identity.agents.config.debug.level": [
        "Error"
    ],
    "com.sun.identity.agents.config.local.log.rotate": [
        "false"
    ],
    "com.sun.identity.agents.config.repository.location": [
        "centralized"
    ],
    "com.sun.identity.agents.config.client.ip.validation.enable": [
        "false"
    ],
    "com.sun.identity.agents.config.override.protocol": [
        "false"
    ],
    "AgentType": [
        "WebAgent"
    ],
    "com.sun.identity.agents.config.logout.redirect.url": [],
    "com.sun.identity.agents.config.ignore.path.info": [
        "false"
    ],
    "com.sun.identity.agents.config.override.notification.url": [
        "false"
    ],
    "com.sun.identity.agents.config.session.attribute.fetch.mode": [
        "NONE"
    ],
    "com.sun.identity.agents.config.policy.cache.polling.interval": [
        "3"
    ],
    "com.sun.identity.agents.config.cdsso.cdcservlet.url": [
        "[0]=https://openam.example.com:8443/openam/cdcservlet"
    ],
    "com.sun.identity.agents.config.cookie.name": [
        "iPlanetDirectoryPro"
    ],
    "com.sun.identity.agents.config.profile.attribute.mapping": [
        "[]="
    ],
    "com.sun.identity.agents.config.iis.filter.priority": [
        "HIGH"
    ],
    "com.sun.identity.agents.config.iis.auth.type": [],
    "com.sun.identity.client.notification.url": [
        "http://www.example.com:80/UpdateAgentCacheServlet?shortcircuit=false"
    ],
    "com.sun.identity.agents.config.cookie.secure": [
        "false"
    ],
    "com.sun.identity.agents.config.ignore.path.info.for.not.enforced.list": [
        "true"
    ],
    "com.sun.identity.agents.config.remote.log.interval": [
        "5"
    ],
    "com.sun.identity.agents.config.notenforced.url.invert": [
        "false"
    ],
    "universalid": [
        "id=myWebAgent,ou=agent,dc=openam,dc=forgerock,dc=org"
    ],
    "com.sun.identity.agents.config.replaypasswd.key": [],
    "com.sun.identity.agents.config.iis.owa.enable.change.protocol": [
        "false"
    ],
    "com.sun.identity.agents.config.userid.param": [
        "UserToken"
    ],
    "userpassword": [
        "{SHA-1}W6ph5Mm5Pz8GgiULbPgzG37mj9g="
    ],
    "com.sun.identity.agents.config.response.attribute.fetch.mode": [
        "NONE"
    ],
    "com.sun.identity.agents.config.freeformproperties": [
        "sunidentityserverdevicestatus=Active",
        "sunidentityserverdevicekeyvalue=agentRootURL=http://www.example.com:80/",
        "realm=/",
        "name=myWebAgent"
    ],
    "com.sun.identity.agents.config.postdata.preserve.enable": [
        "false"
    ],
    "com.sun.identity.agents.config.log.disposition": [
        "REMOTE"
    ],
    "com.sun.identity.agents.config.agenturi.prefix": [
        "http://www.example.com:80/amagent"
    ],
    "com.sun.identity.agents.config.override.host": [
        "false"
    ],
    "com.sun.identity.agents.config.cookie.reset.enable": [
        "false"
    ],
    "com.sun.identity.agents.config.local.log.size": [
        "52428800"
    ],
    "com.sun.identity.agents.config.access.denied.url": [],
    "com.sun.identity.agents.config.debug.file.size": [
        "10000000"
    ],
    "com.sun.identity.agents.config.change.notification.enable": [
        "true"
    ],
    "com.sun.identity.agents.config.anonymous.user.enable": [
        "false"
    ],
    "com.sun.identity.agents.config.domino.ltpa.org.name": [],
    "com.sun.identity.agents.config.agent.logout.url": [
        "[0]="
    ],
    "com.sun.identity.agents.config.poll.primary.server": [
        "5"
    ],
    "com.sun.identity.agents.config.fqdn.mapping": [
        "[]="
    ],
    "com.sun.identity.agents.config.auth.connection.timeout": [
        "2"
    ],
    "com.sun.identity.agents.config.client.hostname.header": [],
    "com.sun.identity.agents.config.iis.logonuser": [
        "false"
    ],
    "com.sun.identity.agents.config.ignore.server.check": [
        "false"
    ],
    "com.sun.identity.agents.config.fetch.from.root.resource": [
        "false"
    ],
    "com.sun.identity.agents.config.login.url": [
        "[0]=https://openam.example.com:8443/openam/UI/Login"
    ],
    "com.sun.identity.agents.config.redirect.param": [
        "goto"
    ],
    "com.sun.identity.agents.config.logout.url": [
        "[0]=https://openam.example.com:8443/openam/UI/Logout"
    ],
    "sunIdentityServerDeviceStatus": [
        "Active"
    ],
    "com.sun.identity.agents.config.sso.cache.polling.interval": [
        "3"
    ],
    "com.sun.identity.agents.config.anonymous.user.id": [
        "anonymous"
    ],
    "com.sun.identity.agents.config.encode.cookie.special.chars.enable": [
        "false"
    ],
    "com.sun.identity.agents.config.locale": [
        "en_US"
    ],
    "com.sun.identity.agents.config.postcache.entry.lifetime": [
        "10"
    ]
}
   

$ curl \
 --request POST \
 --header "iPlanetDirectoryPro: AQIC5w...2NzEz*" \
 --header "Content-Type: application/json" \
 --data '{
   "username":"newGroup",
   "uniquemember":["uid=demo,ou=people,dc=openam,dc=forgerock,dc=org"]
 }' \
 https://openam.example.com:8443/openam/json/groups?_action=create
{
    "username": "newGroup",
    "realm": "/",
    "uniqueMember": [
        "uid=demo,ou=people,dc=openam,dc=forgerock,dc=org"
    ],
    "cn": [
        "newGroup"
    ],
    "dn": [
        "cn=newGroup,ou=groups,dc=openam,dc=forgerock,dc=org"
    ],
    "objectclass": [
        "groupofuniquenames",
        "top"
    ],
    "universalid": [
        "id=newGroup,ou=group,dc=openam,dc=forgerock,dc=org"
    ]
}

$ curl \
 --request PUT \
 --header "If-None-Match: *" \
 --header "iPlanetDirectoryPro: AQIC5w...2NzEz*" \
 --header "Content-Type: application/json" \
 --data '{
   "username":"anotherGroup",
   "uniquemember":["uid=demo,ou=people,dc=openam,dc=forgerock,dc=org"]
 }' \
 https://openam.example.com:8443/openam/json/groups/anotherGroup
{
    "username": "anotherGroup",
    "realm": "/",
    "uniqueMember": [
        "uid=demo,ou=people,dc=openam,dc=forgerock,dc=org"
    ],
    "cn": [
        "anotherGroup"
    ],
    "dn": [
        "cn=anotherGroup,ou=groups,dc=openam,dc=forgerock,dc=org"
    ],
    "objectclass": [
        "groupofuniquenames",
        "top"
    ],
    "universalid": [
        "id=anotherGroup,ou=group,dc=openam,dc=forgerock,dc=org"
    ]
}
   

OpenAM lets users and administrators read profiles by requesting an HTTP GET on /json/subrealm/users/user-id. This allows users and administrators to verify user data, status, and directory. If users or administrators see missing or incorrect information, they can write down the correct information and add it using "Updating Identities". To read a profile on the Top Level Realm, you do not need to specify the realm.

Users can review the data associated with their accounts and administrators can read other user's profiles. The following example shows an administrator accessing user data. Users can view their information by changing username=amadmin to user-id.

$ curl \
 --header "iplanetDirectoryPro: AQIC5w...2NzEz*" \
 https://openam.example.com:8443/openam/json/users/demo
{
    "username": "demo",
    "realm": "dc=openam,dc=forgerock,dc=org",
    "uid": [
        "demo"
    ],
    "userpassword": [
        "{SSHA}BKPAKRS3QKkvQRw25MfXbVC4VEuVNUf+yCaejg=="
    ],
    "sn": [
        "demo"
    ],
    "cn": [
        "demo"
    ],
    "inetuserstatus": [
        "Active"
    ],
    "dn": [
        "uid=demo,ou=people,dc=openam,dc=forgerock,dc=org"
    ],
    "objectclass": [
        "devicePrintProfilesContainer",
        "person",
        "sunIdentityServerLibertyPPService",
        "inetorgperson",
        "sunFederationManagerDataStore",
        "iPlanetPreferences",
        "iplanet-am-auth-configuration-service",
        "organizationalperson",
        "sunFMSAML2NameIdentifier",
        "inetuser",
        "forgerock-am-dashboard-service",
        "iplanet-am-managed-person",
        "iplanet-am-user-service",
        "sunAMAuthAccountLockout",
        "top"
    ],
    "universalid": [
        "id=demo,ou=user,dc=openam,dc=forgerock,dc=org"
    ]
}
    

Use the _fields query string parameter to restrict the list of attributes returned. This parameter takes a comma-separated list of JSON object fields to include in the result.

$ curl \
 --header "iPlanetDirectoryPro: AQIC5w...2NzEz*" \
 https://openam.example.com:8443/openam/json/users/demo?_fields=username,uid
{"username":"demo","uid":["demo"]}
   

As shown in the examples, OpenAM returns the JSON representation of the profile on success. On failure, OpenAM returns a JSON representation of the error including the HTTP status code.

Using HTTP GET to read also works for other objects such as agent profiles and groups.

$ curl \
 --header "iplanetDirectoryPro: AQIC5w...2NzEz*" \
 https://openam.example.com:8443/openam/json/agents/myClientID
{
    "username": "myClientID",
    "realm": "dc=openam,dc=forgerock,dc=org",
    "com.forgerock.openam.oauth2provider.accesstoken": [],
    "com.forgerock.openam.oauth2provider.clientsessionuri": [],
    "com.forgerock.openam.oauth2provider.defaultscopes": [
        "[0]="
    ],
    "com.forgerock.openam.oauth2provider.clientname": [],
    "com.forgerock.openam.oauth2provider.clienttype": [
        "Confidential"
    ],
    "universalid": [
        "id=myClientID,ou=agent,dc=openam,dc=forgerock,dc=org"
    ],
    "com.forgerock.openam.oauth2provider.responsetypes": [
        "[6]=code token id_token",
        "[0]=code",
        "[2]=id_token",
        "[4]=token id_token",
        "[3]=code token",
        "[1]=token",
        "[5]=code id_token"
    ],
    "userpassword": [
        "{SHA-1}W6ph5Mm5Pz8GgiULbPgzG37mj9g="
    ],
    "com.forgerock.openam.oauth2provider.name": [
        "[0]="
    ],
    "com.forgerock.openam.oauth2provider.redirectionuris": [
        "[0]="
    ],
    "com.forgerock.openam.oauth2provider.idtokensignedresponsealg": [
        "HS256"
    ],
    "com.forgerock.openam.oauth2provider.scopes": [
        "[0]="
    ],
    "com.forgerock.openam.oauth2provider.postlogoutredirecturi": [],
    "sunidentityserverdevicestatus": [
        "Active"
    ],
    "agenttype": [
        "OAuth2Client"
    ],
    "com.forgerock.openam.oauth2provider.description": [
        "[0]="
    ]
}
   

The _prettyPrint query string parameter can make the resulting JSON easier to read when you are viewing the resulting JSON directly.

$ curl \
 --header "iPlanetDirectoryPro: AQIC5w...2NzEz*" \
 https://openam.example.com:8443/openam/json/groups/myGroup?_prettyPrint=true
{
    "username": "myGroup",
    "realm": "dc=openam,dc=forgerock,dc=org",
    "uniquemember": [
        "uid=demo,ou=people,dc=openam,dc=forgerock,dc=org"
    ],
    "cn": [
        "myGroup"
    ],
    "dn": [
        "cn=myGroup,ou=groups,dc=openam,dc=forgerock,dc=org"
    ],
    "objectclass": [
        "groupofuniquenames",
        "top"
    ],
    "universalid": [
        "id=myGroup,ou=group,dc=openam,dc=forgerock,dc=org"
    ]
}
   

OpenAM lets users update their own profiles, and lets administrators update other users' profiles. To update an identity do an HTTP PUT of the JSON representation of the changes to /json/subrealm/users/user-id. To update a profile on the Top Level Realm, you do not need to specify the realm.

The following example shows how users can update their own profiles.

$ curl \
 --request PUT \
 --header "iplanetDirectoryPro: AQIC5...Y3MTAx*" \
 --header "Content-Type: application/json" \
 --data '{ "mail": "demo@example.com" }' \
 https://openam.example.com:8443/openam/json/users/demo
{
    "username": "demo",
    "realm": "/",
    "uid": [
        "demo"
    ],
    "mail": [
        "demo@example.com"
    ],
    "sn": [
        "demo"
    ],
    "userpassword": [
        "{SSHA}S14oR2gusLWtiDkAS4twj63slXNNaMKpwrOWdw=="
    ],
    "cn": [
        "demo"
    ],
    "inetuserstatus": [
        "Active"
    ],
    "dn": [
        "uid=demo,ou=people,dc=openam,dc=forgerock,dc=org"
    ],
    "objectclass": [
        "person",
        "sunIdentityServerLibertyPPService",
        "sunFederationManagerDataStore",
        "inetorgperson",
        "iPlanetPreferences",
        "iplanet-am-auth-configuration-service",
        "organizationalperson",
        "sunFMSAML2NameIdentifier",
        "inetuser",
        "iplanet-am-managed-person",
        "sunAMAuthAccountLockout",
        "iplanet-am-user-service",
        "top"
    ],
    "universalid": [
        "id=demo,ou=user,dc=openam,dc=forgerock,dc=org"
    ]
}
    

As shown in the example, OpenAM returns the JSON representation of the profile on success. On failure, OpenAM returns a JSON representation of the error including the HTTP status code.

You can use HTTP PUT to update other objects as well, such as policy agent profiles and groups.

The following example creates a web policy agent profile.

$ curl \
 --request PUT \
 --header "iPlanetDirectoryPro: AQIC5...Y3MTAx*" \
 --header "Content-Type: application/json" \
 --header "If-None-Match: *" \
 --data '{
  "username" : "myWebAgent",
  "realm" : "/",
  "com.sun.identity.agents.config.fqdn.default" : [ "www.example.com" ],
  "sunIdentityServerDeviceKeyValue" :
   [ "agentRootURL=http://www.example.com:80/" ],
  "com.sun.identity.agents.config.remote.logfile" :
   [ "amAgent_www_example_com_80.log" ],
  "com.sun.identity.agents.config.repository.location" : [ "centralized" ],
  "AgentType" : [ "WebAgent" ],
  "com.sun.identity.agents.config.cdsso.cdcservlet.url" :
   [ "[0]=https://openam.example.com:8443/openam/cdcservlet" ],
  "com.sun.identity.client.notification.url" :
   [ "http://www.example.com:80/UpdateAgentCacheServlet?shortcircuit=false" ],
  "universalid" : [ "id=myWebAgent,ou=agent,dc=openam,dc=forgerock,dc=org" ],
  "userpassword" : [ "changeit" ],
  "com.sun.identity.agents.config.agenturi.prefix" :
   [ "http://www.example.com:80/amagent" ],
  "com.sun.identity.agents.config.login.url" :
   [ "[0]=https://openam.example.com:8443/openam/UI/Login" ],
  "com.sun.identity.agents.config.logout.url" :
   [ "[0]=https://openam.example.com:8443/openam/UI/Logout" ],
  "sunIdentityServerDeviceStatus" : [ "Active" ]
 }' \
 https://openam.example.com:8443/openam/json/agents/myWebAgent?_prettyPrint=true
   

When you create a policy agent profile, OpenAM returns the full profile in JSON format.

Notice in the following example that updates myGroup the object class value is not included in the JSON sent to OpenAM.

$ curl \
 --request PUT \
 --header "iPlanetDirectoryPro: AQIC5...Y3MTAx*" \
 --header "Content-Type: application/json" \
 --data '{
   "name":"myGroup",
   "realm":"/",
   "uniquemember":["uid=demo,ou=people,dc=openam,dc=forgerock,dc=org"],
   "cn":["myGroup"],
   "description":["Updated the group"]
 }' \
 https://openam.example.com:8443/openam/json/groups/myGroup
{
    "name": "myGroup",
    "realm": "/",
    "uniqueMember": [
        "uid=demo,ou=people,dc=openam,dc=forgerock,dc=org"
    ],
    "cn": [
        "myGroup"
    ],
    "dn": [
        "cn=myGroup,ou=groups,dc=openam,dc=forgerock,dc=org"
    ],
    "objectclass": [
        "groupofuniquenames",
        "top"
    ],
    "universalid": [
        "id=myGroup,ou=group,dc=openam,dc=forgerock,dc=org"
    ]
}
   

OpenAM lets administrators delete a user profile by making an HTTP DELETE call to /json/subrealm/users/user-id. To delete a user from the Top Level Realm, you do not need to specify the realm.

The following example removes a user from the top level realm. Only administrators should delete users. The user id is the only field required to delete a user.

$ curl \
 --request DELETE \
 --header "iplanetDirectoryPro: AQIC5w...2NzEz*" \
 https://openam.example.com:8443/openam/json/users/bjensen
{"success":"true"}
   

On success, OpenAM returns a JSON object indicating success. On failure, OpenAM returns a JSON representation of the error including the HTTP status code.

You can use this same logic for other resources such as performing an HTTP DELETE of an agent profile or of a group.

$ curl \
 --request DELETE \
 --header "iplanetDirectoryPro: AQIC5w...2NzEz*" \
 https://openam.example.com:8443/openam/json/agents/myOAuth2ClientAgent
{"success":"true"}
   

$ curl \
 --request DELETE \
 --header "iPlanetDirectoryPro: AQIC5w...2NzEz*" \
 https://openam.example.com:8443/openam/json/groups/myGroup
{"success":"true"}
   

OpenAM lets administrators list identities by making an HTTP GET call to /json/subrealm/users/?_queryId=*. To query the Top Level Realm, you do not need to specify the realm.

$ curl \
 --header "iPlanetDirectoryPro: AQIC5w...2NzEz*" \
 "https://openam.example.com:8443/openam/json/users?_queryID=*"
{
  "result" : [ "amAdmin", "demo", "anonymous" ],
  "resultCount" : 3,
  "pagedResultsCookie" : null,
  "remainingPagedResults" : -1
}
   

This also works for other types of objects, such as agent profiles and groups.

$ curl \
 --header "iPlanetDirectoryPro: AQIC5w...2NzEz*" \
 "https://openam.example.com:8443/openam/json/agents?_queryID=*"
{
  "result" : [ "wsp", "wsc", "agentAuth", "SecurityTokenService" ],
  "resultCount" : 4,
  "pagedResultsCookie" : null,
  "remainingPagedResults" : -1
}
   

$ curl \
 --header "iPlanetDirectoryPro: AQIC5w...2NzEz*" \
 "https://openam.example.com:8443/openam/json/groups?_queryID=*"
{
  "result" : [ "myOtherGroup", "myGroup" ],
  "resultCount" : 2,
  "pagedResultsCookie" : null,
  "remainingPagedResults" : -1
}
   

As the result lists include all objects, this capability to list identity names is mainly useful in testing.

As shown in the examples, OpenAM returns the JSON representation of the resource list if successful. On failure, OpenAM returns a JSON representation of the error including the HTTP status code.

If you only have access to the iPlanetDirectoryPro session cookie, you can retrieve the user ID by performing an HTTP POST operation on the /json/users endpoint using the idFromSession action.

$ curl \
 --verbose \
 --request POST \
 --header "iplanetdirectorypro: AQIC5wM2LY4SfczUFNs-TJwFrCVAKgR0NulIAyNaIkQmjis.*AAJTSQACMDEA
 AlNLABQtNTQ3NDE2Njc5ODk4MjYzMzA2MQ..*" \
 --header "Content-Type: application/json" http://openam.example.com:8080/openam/json/users?_action=idFromSession

{
  "id":"demo",
  "realm":"/",
  "dn":"id=demo,ou=user,dc=openam,dc=forgerock,dc=org",
  "successURL":"/openam/console",
  "fullLoginURL":null
}
   

A user can change their own password with an HTTP POST to /json/subrealm/users/username?_action=changePassword including the new password as the value of userpassword in the request data.

A user must provide the current password, which is set in the request as the value of the currentpassword.

For the case where the user has forgotten their password, see Resetting Forgotten Passwords instead.

The following example shows a successful request to change the demo user's password to password.

$ curl \
 --request POST \
 --header "iPlanetDirectoryPro: AQIC5w...NTcy*" \
 --header "Content-Type: application/json" \
 --data '{
     "currentpassword":"changeit",
     "userpassword":"password"
 }' \
 https://openam.example.com:8443/openam/json/users/demo?_action=changePassword
{}
   

On success, the response is an empty JSON object {} as shown in the example.

On failure, OpenAM returns a JSON representation of the error including the HTTP status code. See also REST Status Codes for more information.

Interface Stability: Deprecated in the Administration Guide

OpenAM lets you create user profiles, and also create web and J2EE policy agent profiles. When you create an entry, you must provide the following parameters.

$ curl "https://openam.example.com:8443/openam/identity/create?\
admin=AQIC5wM2LY4SfcxSYA8eG-vrNHb_W7nG8XkfAGyRyuaebDY.*AAJTSQACMDE.*\
&identity_name=testuser\
&identity_attribute_names=cn\
&identity_attribute_values_cn=Test%20User\
&identity_attribute_names=sn\
&identity_attribute_values_sn=User\
&identity_attribute_names=userpassword\
&identity_attribute_values_userpassword=secret12\
&identity_realm=%2F\
&identity_type=user"
    

Interface Stability: Deprecated in the Administration Guide

Reading is similar to attribute retrieval, as described in Token Validation, but obtained using the token of a user with permissions to perform the search, as shown in the following example.

$ curl "https://openam.example.com:8443/openam/identity/read?\
admin=AQIC5wM2LY4SfcxSYA8eG-vrNHb_W7nG8XkfAGyRyuaebDY.*AAJTSQACMDE.*\
&name=testuser\
&attributes_names=realm\
&attributes_values_realm=%2F"
identitydetails.name=testuser
identitydetails.type=user
identitydetails.realm=o=openam
identitydetails.attribute=
identitydetails.attribute.name=uid
identitydetails.attribute.value=testuser
identitydetails.attribute=
identitydetails.attribute.name=sn
identitydetails.attribute.value=User
identitydetails.attribute=
identitydetails.attribute.name=userpassword
identitydetails.attribute.value={SSHA}AzpT+N1sjrQhL1wfX2ETWh/Aqbd+lH9LOlhDqg==
identitydetails.attribute=
identitydetails.attribute.name=cn
identitydetails.attribute.value=Test User
identitydetails.attribute=
identitydetails.attribute.name=inetuserstatus
identitydetails.attribute.value=Active
identitydetails.attribute=
identitydetails.attribute.name=dn
identitydetails.attribute.value=uid=testuser,ou=people,dc=example,dc=com
identitydetails.attribute=
identitydetails.attribute.name=objectclass
identitydetails.attribute.value=person
identitydetails.attribute.value=sunIdentityServerLibertyPPService
identitydetails.attribute.value=inetorgperson
identitydetails.attribute.value=sunFederationManagerDataStore
identitydetails.attribute.value=iPlanetPreferences
identitydetails.attribute.value=iplanet-am-auth-configuration-service
identitydetails.attribute.value=organizationalperson
identitydetails.attribute.value=sunFMSAML2NameIdentifier
identitydetails.attribute.value=inetuser
identitydetails.attribute.value=iplanet-am-managed-person
identitydetails.attribute.value=iplanet-am-user-service
identitydetails.attribute.value=sunAMAuthAccountLockout
identitydetails.attribute.value=top
identitydetails.attribute=
identitydetails.attribute.name=universalid
identitydetails.attribute.value=id=testuser,ou=user,o=openam
   

You can search for user IDs by providing the following parameters.

$ curl "https://openam.example.com:8443/openam/identity/search?\
admin=AQIC5wM2LY4SfcxSYA8eG-vrNHb_W7nG8XkfAGyRyuaebDY.*AAJTSQACMDE.*\
&attributes_names=sn\
&attributes_values_sn=Jensen\
&attributes_names=mail\
&attributes_values_mail=bjensen*\
&attributes_names=realm\
&attributes_values_realm=%2F"
string=bjensen
   

Interface Stability: Deprecated in the Administration Guide

You can update an identity with the same parameters used to create identities, provided the token corresponds to a user with access to update the identity.

$ curl "https://openam.example.com:8443/openam/identity/update?\
admin=AQIC5wM2LY4SfcxSYA8eG-vrNHb_W7nG8XkfAGyRyuaebDY.*AAJTSQACMDE.*\
&identity_name=testuser\
&identity_attribute_names=mail\
&identity_attribute_values_mail=testuser%40example.com\
&identity_realm=%2F\
&identity_type=user"
   

Interface Stability: Deprecated in the Administration Guide

You can also delete an identity.

$ curl "https://openam.example.com:8443/openam/identity/delete?\
admin=AQIC5wM2LY4SfcxSYA8eG-vrNHb_W7nG8XkfAGyRyuaebDY.*AAJTSQACMDE.*\
&identity_name=testuser\
&identity_realm=%2F\
&identity_type=user"
   

Realms have a number of fields entered with the default loading. The following table provides information on what the default realm settings are, and these settings can be updated, added, or deleted when updating a realm.

OpenAM lets administrators create a realm by making an HTTP POST of the JSON representation of the profile to /json/realms/?_action=create.

You can create realms using an HTTP POST of the JSON representation of the profile to /json/realms/?_action=create, as shown in the following example. The only required field is realm, but the realm will not be active if the status is not set.

$ curl \
 --request POST \
 --header "iplanetDirectoryPro: AQIC5w...2NzEz*" \
 --header "Content-Type: application/json" \
 --data '{ "realm": "myRealm" }' \
 https://openam.example.com:8443/openam/json/realms/?_action=create
{"realmCreated":"/myRealm"}
     

You can also set the sunOrganizationAliases parameter, but it can only be assigned to one realm (usually the top level realm). Before setting this parameter, make sure it is not already assigned elsewhere. If you replace remove it from another realm, you will lose your configuration.

Alternatively, administrators can create realms by the specific realm name using the HTTP PUT of the JSON representation of the changes to /json/realms/realm-id, as shown in the following example:

$ curl \
 --request PUT \
 --header "iplanetDirectoryPro: AQIC5w...2NzEz*" \
 --header "Content-Type: application/json" \
 --data '{ }' \
 https://openam.example.com:8443/openam/json/realms/myRealm
     

OpenAM returns the JSON representation of the profile on success. On failure, OpenAM returns a JSON representation of the error including the HTTP status code.

OpenAM lets administrators read realms by requesting an HTTP GET on /json/realms/realm-id. This allows administrators to review all active realm services for the realm, like policy configuration and modules. If users or administrators see missing information (such as Active status) or incorrect information, they can write down the correct information and add it using "Updating Realms"

The following example shows an administrator receiving information about a realm called myRealm.

$ curl \
 --header "iplanetDirectoryPro: AQIC5w...2NzEz*" \
 https://openam.example.com:8443/openam/json/realms/myRealm
{
    "serviceNames":[
      "sunAMAuthHOTPService",
      "iPlanetAMAuthConfiguration",
      "sunAMAuthFederationService",
      "sunIdentityRepositoryService",
      "iPlanetAMPolicyConfigService",
      "iPlanetAMAuthService",
      "iPlanetAMAuthLDAPService",
      "sunAMAuthDataStoreService",
      "sunAMAuthSAEService",
      "sunAMDelegationService",
      "sunAMAuthWSSAuthModuleService",
      "iPlanetAMAuthOATHService"
    ]
}
    

As shown in the example, OpenAM returns the JSON representation of the profile on success. On failure, OpenAM returns a JSON representation of the error including the HTTP status code.

To read the top-level realm, use toplevelrealm with the realms endpoint.

$ curl \
 --header "iplanetDirectoryPro: AQIC5w...2NzEz*" \
 https://openam.example.com:8443/openam/json/realms/toplevelrealm
{
      "serviceNames" : [
       "sunAMAuthFederationService",
       "sunEntitlementIndexes",
       "iPlanetAMAuthService",
       "sunAMAuthDataStoreService",
       "sunAMAuthWSSAuthModuleService",
       "sunAMDelegationService",
       "iPlanetAMAuthOATHService",
       "iPlanetAMAuthConfiguration",
       "sunAMAuthHOTPService",
       "sunIdentityRepositoryService",
       "iPlanetAMPolicyConfigService",
       "iPlanetAMAuthLDAPService",
       "sunEntitlementService",
       "iPlanetAMPolicyService",
       "sunAMAuthSAEService",
       "AgentService" ]
}
   

If the realm you want to read is not an immediate subrealm of the top-level realm, specify its parent realm to the left of realms in the URL, and specify the realm's final qualifier to the right of realms. For example, to read the /myRealm/myRealmsChildRealm realm:

$ curl \
 --header "iplanetDirectoryPro: AQIC5w...2NzEz*" \
 https://openam.example.com:8443/openam/json/myRealm/realms/myRealmsChildRealm
{
      "serviceNames" : [
       "sunAMAuthHOTPService",
       "iPlanetAMAuthConfiguration",
       "sunAMAuthFederationService",
       "sunIdentityRepositoryService",
       "iPlanetAMPolicyConfigService",
       "iPlanetAMAuthService",
       "iPlanetAMAuthLDAPService",
       "sunAMAuthDataStoreService",
       "sunAMAuthSAEService",
       "sunAMDelegationService",
       "sunAMAuthWSSAuthModuleService",
       "iPlanetAMAuthOATHService"
      ]
}
   

To list a realm and its subrealms, perform an HTTP GET on the endpoint, setting the _queryFilter query string parameter as in the following example, which lists the top-level realm and all of its subrealms:

 $ curl \
 --header "iPlanetDirectoryPro: AQIC5..." \
 https://openam.example.com:8443/openam/json/realms?_queryFilter=true
 {
     "result" : [ "/", "/myRealm", "/myRealm/myRealmsChildRealm" ],
     "resultCount" : 3,
     "pagedResultsCookie" : null,
     "remainingPagedResults" : -1
 }
   

You can start listing realms from below the top-level realm by placing the starting realm name in the URL. The following example lists the realm myRealm and all of its subrealms.

$ curl \
 --header "iPlanetDirectoryPro: AQIC5..." \
 https://openam.example.com:8443/openam/json/myRealm/realms?_queryFilter=true
 {
     "result" : [ "/myRealm", "/myRealm/myRealmsChildRealm" ],
     "resultCount" : 2,
     "pagedResultsCookie" : null,
     "remainingPagedResults" : -1
 }
 

OpenAM lets administrators update realms. To update a realm, do an HTTP PUT of the JSON representation of the changes to /json/realms/realm-id.

The following example shows how to update a realm called myRealm. The example command sets the realm's status to Inactive.

$ curl \
 --request PUT \
 --header "iplanetDirectoryPro: AQIC5...Y3MTAx*" \
 --header "Content-Type: application/json" \
 --data '{ "sunOrganizationStatus": "Inactive" }' \
 https://openam.example.com:8443/openam/json/realms/myRealm
     

OpenAM returns the JSON representation of the profile on success. On failure, OpenAM returns a JSON representation of the error including the HTTP status code.

OpenAM lets administrators delete a realm by making an HTTP DELETE call to /json/realms/realm-id.

The following example deletes a realm called myRealm. The top level realm cannot be deleted. Only administrators should delete realms. The name of the realm is the only field required to delete the realm.

Make sure that you do not have any information you need within a realm before deleting it. Once a realm is deleted, the only way to restore it is to return to a backed up deployment of OpenAM.

$ curl \
 --request DELETE \
 --header "iplanetDirectoryPro: AQIC5w...2NzEz*" \
 https://openam.example.com:8443/openam/json/realms/myRealm
{"success":"true"}
    

On success, OpenAM returns a JSON object indicating success. On failure, OpenAM returns a JSON representation of the error including the HTTP status code.

If the realm you want to delete is not an immediate subrealm of the top-level realm, specify its parent realm to the left of realms in the URL, and specify the realm's final qualifier to the right of realms. For example, to delete the /myRealm/myRealmsChildRealm realm:

 $ curl \
 --request DELETE
 --header "iplanetDirectoryPro: AQIC5w...2NzEz*" \
 https://openam.example.com:8443/openam/json/myRealm/realms/myRealmsChildRealm
 { "success":"true" }
   

Each REST STS instance issues SAML 2.0 assertions for a single ServiceProvider. As a result, each REST STS instance is configured with the following elements:

For signing and encryption support, each REST STS instance has a configuration state specifying the keystore location containing the signing and encryption keys.

If you configure assertion signing, you must specify the keystore path and password, as well as the alias and password corresponding to the private key used to sign the assertion.

If you configure assertion encryption, you must specify the keystore path and password, as well as the alias corresponding to the SP’s X509 certificate, which encapsulates the public key used to encrypt the symmetric key that encrypted the generated assertion.

You can encrypt the entire assertion, or the NameID and/or the AttributeStatement attributes.

All statements constituting a SAML 2.0 assertion can be fully customized. For each REST STS instance, you can write custom plug-ins for the Conditions, Subject, AuthenticationStatements, AttributeStatements, and AuthorizationDecisionStatements classes. If you specify the classes in the configuration of the published REST STS instance, these custom classes are consulted to provide the specific statements. See the interfaces in the org.forgerock.openam.sts.tokengeneration.saml2.statements package for details.

Each REST STS instance must specify the AuthnContext in the AuthenticationStatements of the generated assertion. This AuthnContext allows the generated SAML 2.0 assertion to specify the manner in which the assertion’s subject was authenticated. For a token transformation, this AuthnContext is a function of the input token type.

By default, the following AuthnContext string is included in the SAML2 assertion, generated as part of the transformation of the following input token types:

You can set the mapping of SAML attribute names (Map keys) to local OpenAM attributes (Map values) using the org.forgerock.openam.sts.tokengeneration.saml2.statements.DefaultAttributeMapper class, which looks at profile attributes in the data stores or in the session properties for each published REST STS instance. The keys define the name of the attributes in the Assertion Attribute statements, and the values define these attribute names. REST STS pulls the data from the subject's directory entry or from the session state that corresponds to the map value.

The keys can have the following format:

[NameFomatURI|]SAML ATTRIBUTE NAME
   

If the attribute value is enclosed in quotes, that quoted value is included in the attribute without mapping. Binary attributes should be followed by ;binary as seen in the following example:

EmailAddress=mail,
Address=postaladdress,
urn:oasis:names:tc:SAML:2.0:attrname-format:uri|urn:mace:dir:attribute-def:cn=cn,
partnerID="staticPartnerIDValue",
urn:oasis:names:tc:SAML:2.0:attrname-format:uri|nameID="staticNameIDValue",
photo=photo;binary,
urn:oasis:names:tc:SAML:2.0:attrname-format:uri|photo=photo;binary
  

If this attribute mapping is insufficient, implement the org.forgerock.openam.sts.tokengeneration.saml2.statements.AttributeMapper interface and specify the name of the custom AttributeMapper in the configuration corresponding to your published REST STS instance.

The input tokens in REST STS token transformations are authenticated via OpenAM’s restful authentication context. This context needs to be configured for every input token type in the set of token transformations. For example, if you select the transformation OPENIDCONNECT->SAML2, the STS instance must be configured with information specifying which elements of the OpenAM restful authentication context needs to be consumed to validate the OPENIDCONNECT token.

The elements of the configuration tuple are separated by '|'.

When transforming OpenID Connect ID tokens, the OpenID Connect authentication module must be consumed, and thus a deployed REST STS instance must be configured with the name of the header/cookie element where the OpenID Connect ID token is placed. For example, the following Admin Console string defines these configurations:

OPENIDCONNECT|module|oidc|oidc_id_token_auth_target_header_key=oidc_id_token.
  

In this case, oidc is the name of the OpenID Connect authentication module created to authenticate OpenID Connect tokens. REST STS looks for the name of the header key in the string oidc_id_token_auth_target_header_key, which is the header where the oidc module expects to find the OpenID Connect ID Token.

When transforming a X509 Certificate, the Certificate module must be consumed, and the published REST STS instance must be configured with the name of the Certificate module (or the service containing the module), and the header name configured for the Certificate module corresponding to where the Certificate module can expect to find the to-be-validated Certificate.

The following Admin Console string would define these configurations (note that these configurations can be created in a more intuitive, fluent way using the builders supporting the programmatic publishing of REST STS instances):

X509|module|cert_module|x509_token_token_auth_target_header_key=client_cert
  

In this case cert_module is the name of the Certificate module, and client_cert is the header name where Certificate module has been configured to find the client's Certificate. REST STS looks for the name of the header key in the string x509_token_token_auth_target_header_keyy, which is the header x509 ID Token.

An x509 Certificate is a representation of subject identity only when ownership of the associated private key is demonstrated, as performed by the TLS-handshake, and described in the AsymmetricBinding examples 2.2.1 and 2.2.2 in WS-SecurityPolicy.

Because the REST STS is not protected by WS-SecurityPolicy bindings (this is the domain of the SOAP STS), a REST STS token transformation, which defines an x509 Certificate as an input token, can only be consumed by two-way TLS. Here the client must present their certificate, with the TLS handshake certifying that the private key corresponding to the presented certificate is in the possession of the certificate presenter. In such a deployment, REST STS obtains the client's certificate from the javax.servlet.request.X509Certificate attribute in the ServletRequest.

However, if OpenAM is deployed in a TLS-offloaded context, REST STS obtains the client's certificate from the header key defined in the published REST STS instance. The header key is specified in the "Client Certificate Header Key" under the "Deployment Configuration" section of a REST STS instance in the Admin Console, or in the org.forgerock.openam.sts.rest.config.user. RestDeploymentConfig.RestDeploymentConfigBuilder#offloadedTwoWayTLSHeaderKey method.

If a header key referencing a client's certificate is defined, then only this header is examined for the client's certificate. If this header is undefined, only the javax.servlet.request.X509Certificate ServletRequest attribute is examined. Note that the token transformation definition specifying an x509 input token does not actually encapsulate the caller's certificate. This token state only triggers REST STS to consult one of the two locations described above.

If the REST STS is configured to pull the client’s certificate out of a specified header, the set of hosts trusted to set this header must also be specified. See the "Trusted Remote Hosts" list in the "Deployment Configuration" section of the Admin Console or the org.forgerock.openam.sts.rest.config.user.RestDeploymentConfig. RestDeploymentConfigBuilder#tlsOffloadEngineHostIpAddrs method.

Authentication of the client-presented certificate is performed by the Certificate module. This module optionally performs certificate revocation list (CRL) or Online Certificate Status Protocol (OCSP) checking, and optionally checks to see that the specified certificate is in a LDAP datastore.

The Certificate module also expects to reference the caller's certificate in a specified header value, and that the IP addresses of hosts trusted to provide this information must also be specified. See the "Trusted Remote Hosts" and the "Http Header Name for Client Certificate" in the Certificate module configuration at Hints for the Certificate Authentication module in the Administration Guide. This header must be specified in the Authentication Target Mapping definition for X509 tokens for the published REST STS instance, so that the REST STS instance can know which header should reference the client’s x509 certificate when consuming the Certificate module.

For example, given the following authentication target mapping:

X509|module|cert_module|x509_token_token_auth_target_header_key=client_cert
  

X509 specifies that for X509 input tokens, a module named cert_module should be invoked, and that this module expects to find the client’s X509 Certificate in a header named client_cert. Thus the string client_cert must appear in the HTTP Header Name for Client Certificate configuration field for the Certificate module named cert_module. Also, the IP address of the OpenAM deployment must be added to the Trusted Remote Hosts configuration of the targeted Certificate module.

For more information on mapping x509 Certificate state to a subject in the OpenAM datastore, see Hints for the Certificate Authentication module in the Administration Guide.

The Username token passed to the REST STS represents the <username, password> combination in clear text. This means that REST STS instances that support Username Token-based token transformations should only be deployed on TLS.

REST STS instances must be configured to consume an appropriately-configured OpenID Connect authentication module for OpenID Connect-based token transformations. The OIDC authentication module expects to reference the id token in a header value. Thus, the AuthTargetMapping of the published REST STS instance must be configured with the name of the header configured for the referenced OIDC authentication module.

The OIDC authentication module must be configured with either the discovery URL, the jwk URL or the client secret corresponding to the issuer, and the issuer name must be set (for OpenAM issued OIDC tokens, the issuer name corresponds to the OpenAM deployment url).

The OIDC authentication module also checks the authorized party (azp) and audience (aud) claims. The OIDC token aud claim must match that configured for the OIDC authentication module (that is, set to the OAuth2 client's ID). If the OIDC token has a azp claim, it must match that configured for the OIDC authentication module (again, set to the OAuth2 client ID). You must configure the attribute mappings, so that jwk claim state is mapped to an entry in the OpenAM user data store.

For additional details on the OpenID Connect authentication module, Hints for the OpenID Connect Module in the Administration Guide.

The Java Fedlet includes a JSP file, saml2/jsp/fedletSSOInit.jsp, that you can call to initiate single sign-on from the Fedlet (SP) side. The Fedlet home page, index.jsp, calls this page when the user does Fedlet-initiated single sign-on.

When calling this JSP, the parameters to use are those also used by saml2/jsp/spSSOInit.jsp in OpenAM. Those parameters are described in the Administration Guide section, spSSOInit.jsp Parameters in the Administration Guide.

For IDP-initiated single sign-on, call the appropriate page on the Identity Provider. OpenAM's page is described in the Administration Guide section, idpSSOInit.jsp Parameters in the Administration Guide.

After single sign-on, the user-agent is directed by default to the assertion consumer URI set in the Fedlet metadata, which by default is /fedletapplication. Also by default that URI points to the JSP, fedletSampleApp.jsp

The Java Fedlet includes a JSP file, saml2/jsp/spSingleLogoutInit.jsp, that you can call to initiate single logout from the Fedlet (SP) side. The Fedlet assertion consumer page, fedletSampleApp.jsp, calls this when the user does Fedlet-initiated single logout.

When calling this JSP, the parameters to use are those also used by saml2/jsp/spSingleLogoutInit.jsp in OpenAM. Those parameters are described in the Administration Guide section, spSingleLogoutInit.jsp Parameters in the Administration Guide.

For IDP-initiated single logout, call the appropriate page on the Identity Provider. OpenAM's page is described in the Administration Guide section, idpSingleLogoutInit.jsp Parameters in the Administration Guide.

Set the RelayState parameter when initiating logout to redirect the user-agent appropriately when the process is complete.

As seen in the procedure, "To Try the Fedlet Attribute Query", an attribute query allows the Fedlet to get profile information about a subject from the Attribute Authority. The Fedlet must be configured to deal with responses from the Attribute Authority, including configuration for signing and encryption. Also, an Identity Provider and Attribute Authority is likely to share only those attributes that the Fedlet absolutely requires to provide service, such as, for example, a name to customize a page. The attributes must then be mapped in the Attribute Authority and Fedlet metadata.

The Java Fedlet includes a JSP file, fedletAttrQuery.jsp, which is used in the procedure described above to prepare an attribute query using the transient subject identifier obtained during single sign-on. The fedletAttrQuery.jsp also supports using the Subject name from an X.509 identity certificate.

Another JSP file, fedletAttrResp.jsp, sends the query to the Attribute Authority using com.sun.identity.saml2.profile.AttributeQueryUtil.html.getAttributesForFedlet(), and if successful processes the result, which is a java.util.Map of the attribute types and their values.

As seen in the procedure, "To Try the Fedlet XACML Query", a XACML query allows the Fedlet to request a policy decision from a XACML PDP. You can configure OpenAM to respond to such queries as described in that procedure.

The Java Fedlet includes a JSP file, fedletXACMLQuery.jsp, which is used in the procedure described above to prepare a XACML query, identifying a resource URL and a type of HTTP operation to perform, and specifying the subject identifier obtained during single sign-on.

Another JSP file, fedletXACMLResp.jsp, sends the query to the XACML PDP using com.sun.identity.saml2.profile.XACMLQueryUtil.getPolicyDecisionForFedlet(), and if successful processes the result, which is a java.lang.String representing the decision, such as Permit if the decision is to allow access, or Deny if the decision is to deny access.

OpenAM passes authState and sharedState to server-side scripts in order for the scripts to access authentication state.

Server-side scripts can access the current authentication state through the authState object.

The authState value is SUCCESS if the authentication is currently successful, or FAILED if authentication has failed. Server-side scripts must set a value for authState before completing.

If an earlier authentication module in the authentication chain has set the login name of the user, server-side scripts can access the login name through username. This is shared by Anonymous, Certificate, Data Store, Federation, HTTP Basic, JDBC, LDAP, Membership, RADIUS, SecurID, Windows Desktop SSO, & Windows NT authentication modules.

Client-side scripts add data they gather into a String object named clientScriptOutputData. Client-side scripts then cause the user-agent automatically to return the data to OpenAM by HTTP POST of a self-submitting form.

OpenAM passes an HTTP client object, httpClient, to server-side scripts. Server-side scripts can call HTTP services with the httpClient.get and httpClient.post methods. The methods return an HttpClientResponse.

The requestData object is a map where the keys are cookies and headers. OpenAM ignores other keys.

The cookies value, specifying the cookie headers in the request, is a list of Maps where the keys are domain, field, and value.

The headers value, specifying the headers in the request, is a list of Maps where the keys are field, and value.

An example requestData JavaScript object using GET would be as follows:

var response = httpClient.get("http://example.com:8080/openam/json/users" + username,
 {
   cookies:[
    {
       "domain": ".example.com",
       "field": "iPlanetDirectoryPro,
       "value": "E8cDkvlad83kdKDodkIEIxqJ938DKSDLIE31djkiefjekda.*DLEDLKJKD09dkleuhDK3kEJKj"
    }
   ],
   headers:[
    {
       "field": "Content-type",
       "value": "application/json"
    }
   ]
 });
   

An example requestData JavaScript object using POST would be as follows:

var response = httpClient.post("http://example.com:8080/openam/json/authenticate","{
  "authId": "eyAiYWxnIjogIkhTMjU2IiwgInR5cCI6ICJqd3QiIH0.eyAib3RrIjogIm03ODVzN2x
   sbnR1bjZvbGZ1MHZhOGVtYTQxIiwgInNlc3Npb25JZCI6ICJBUUlDNXdNMkxZNFNmY3lEeDY3QnB
   PdzJtRU9rUzNpLWhfNDdRWlMwNHBEN1ppdy4qQUFKVFNRQUNNREVBQWxOTEFCUXROak15TURjNU1
   UZzROVFUwTXpnNE5qRTNNQS4uKiIsICJyZWFsbSI6ICJkYz1vcGVuYW0sZGM9Zm9yZ2Vyb2NrLGR
   jPW9yZyIgfQ.VDRqaekQuXBm2lNI29hfwVADLxjepezuO0241VNDsIM",
  "template": "",
  "stage": "DataStore1",
  "callbacks": [
    {
      "type": "NameCallback",
      "output": [
        {
          "name": "prompt",
          "value": "User Name:"
        }
       ],
      "input": [
        {
          "name": "IDToken1",
          "value": "demo"
        }
       ]
    },
    {
      "type": "PasswordCallback",
      "output": [
        {
          "name": "prompt",
          "value": "Password:"
        }
       ],
      "input": [
        {
          "name": "IDToken2",
          "value": "changeit"
        }
      ]
    }
  ]
 }",
 {
   cookies:[
   ],
   headers:[
    {
      "field": "Content-Type",
      "value": "application/json"
    }
   ]
 });

HTTP client requests are synchronous, blocking until they return. You can, however, set a global timeout for server-side scripts. For details, see the Administration Guide section, Hints For Scripted Authentication Modules in the Administration Guide.

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

Server-side scripts can access profile data through the methods of the idRepository object.

Server-side scripts can log messages to OpenAM debug logs by using the methods of the logger object.

By default, OpenAM does not log debug messages from scripts. You can configure OpenAM to log such messages by setting the debug log level for the amScript service. For details, see the Administration Guide section, Debug Logging by Service in the Administration Guide.

The following table lists the logger methods.

Server-side scripts can get access to the login request by using the methods of the requestData object.

The following table lists the methods of the requestData object. Note that this object differs from the client-side requestData object (see "HTTP Client Methods") and contains information about the original authentication request made by the user.

Build the module with Apache Maven, and install the module in OpenAM.

After you successfully build the module, you find the .jar file in the target/ directory of the project.

For information on downloading and building OpenAM sample source code, see How do I access and build the sample code provided for OpenAM 12.x, 13.x and AM (All versions)? in the Knowledge Base.

Installing the sample authentication module consists of copying the .jar to OpenAM's WEB-INF/lib/ directory, registering the module with OpenAM, and then restarting OpenAM or the web application container where it runs.

Your identity repository plugin class must extend the com.sun.identity.idm.IdRepo abstract class, and must include a constructor method that takes no arguments.

When OpenAM instantiates your IdRepo plugin, it calls the initialize() method.

public void initialize(Map configParams)

The configParams are service configuration parameters for the realm where the IdRepo plugin is configured. The configParams normally serve to set up communication with the underlying identity data store. OpenAM calls the initialize() method once, and considers the identity repository ready for use.

If you encounter errors or exceptions during initialization, catch and store them in your plugin for use later when OpenAM calls other plugin methods.

After initialization, OpenAM calls the addListener() and removeListener() methods to register listeners that inform OpenAM client code of changes to identities managed by your IdRepo.

public int addListener(SSOToken token, IdRepoListener listener)
public void removeListener()

You must handle listener registration in your IdRepo plugin, and also return events to OpenAM through the IdRepoListener.

When stopping, OpenAM calls your IdRepo plugin shutdown() method.

public void shutdown()

You are not required to implement shutdown() unless your IdRepo plugin has shut down work of its own to do, such as close connections to the underlying identity data store.

Your IdRepo plugin provides OpenAM with a generic means to manage subjects—including users and groups but also special types such as roles, realms, and agents— and to create, read, update, delete, and search subjects. In order for OpenAM to determine your plugin's capabilities, it calls the methods described in this section.

public Set getSupportedTypes()

The getSupportedTypes() method returns a set of IdType objects, such as IdType.USER and IdType.GROUP. You can either hard-code the supported types into your plugin, or make them configurable through the IdRepo service.

public Set getSupportedOperations(IdType type)

The getSupportedOperations() method returns a set of IdOperation objects, such as IdOperation.CREATE and IdOperation.EDIT. You can also either hard-code these, or make them configurable.

public boolean supportsAuthentication()

The supportsAuthentication() method returns true if your plugin supports the authenticate() method.