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

{ "errorMessage": "Invalid Password!!",
  "failureUrl": "http://www.example.com/401.html" }

You can set the realm by using the realm query string parameter as in ?realm=myRealm.

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

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 Section 3.3, "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 all resource underneath 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"
}

OpenAM exposes a REST API through the /ws/1/entitlement/privilege endpoint under the deployment URI. The API lets you create, read, update, delete, and query policies.

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

$ cat entitlement.json
{
    "name": "Example HTTP",
    "eSubject": {
        "state": {
            "className": "com.sun.identity.policy.plugins.AuthenticatedUsers",
            "exclusive": false,
            "name": "All Authenticated Users",
            "values": []
        },
        "className": "com.sun.identity.entitlement.opensso.PolicySubject"
    },
    "entitlement": {
        "actionsValues": {
            "POST": true,
            "GET": true
        },
        "applicationName": "iPlanetAMWebAgentService",
        "name": "authorize",
        "resourceNames": [
            "http://www.example.com:80/*"
        ]
    }
}$ curl
 --request POST
 --cookie "iPlanetDirectoryPro=AQIC5...DU3*"
 --data-urlencode "privilege.json@entitlement.json"
 https://openam.example.com:8443/openam/ws/1/entitlement/privilege
{"statusCode":201,"body":"Created","statusMessage":"Created"}

$ cat entitlement2.json
{
    "name": "Example HTTPS",
    "eSubject": {
        "state": {
            "className": "com.sun.identity.policy.plugins.AuthenticatedUsers",
            "exclusive": false,
            "name": "All Authenticated Users",
            "values": []
        },
        "className": "com.sun.identity.entitlement.opensso.PolicySubject"
    },
    "entitlement": {
        "actionsValues": {
            "POST": false,
            "GET": true
        },
        "applicationName": "iPlanetAMWebAgentService",
        "name": "authorize",
        "resourceNames": [
            "https://www.example.com:443/*?*"
        ]
    }
}$ curl
 --request POST
 --cookie "iPlanetDirectoryPro=AQIC5...DU3*"
 --data-urlencode "privilege.json@entitlement2.json"
 https://openam.example.com:8443/openam/ws/1/entitlement/privilege
{"statusCode":201,"body":"Created","statusMessage":"Created"}

$ curl
 --request GET
 --cookie "iPlanetDirectoryPro=AQIC5...DU3*"
 https://openam.example.com:8443/openam/ws/1/entitlement/privilege/Example%20HTTP
{
    "statusCode": 200,
    "body": {
        "results": {
            "name": "Example HTTP",
            "eSubject": {
                "state": "{\n  \"className\": \"com.sun.identity.policy...}",
                "className": "com.sun.identity.entitlement.opensso.PolicySubject"
            },
            "entitlement": {
                "actionsValues": {
                    "POST": true,
                    "GET": true
                },
                "applicationName": "iPlanetAMWebAgentService",
                "name": "authorize",
                "resourceNames": [
                    "http://www.example.com:80/*"
                ]
            }
        }
    },
    "statusMessage": "OK"
}

$ curl
 --request GET
 --cookie "iPlanetDirectoryPro=AQIC5...DU3*"
 https://openam.example.com:8443/openam/ws/1/entitlement/privilege/Example%20HTTPS
{
    "statusCode": 200,
    "body": {
        "results": {
            "name": "Example HTTPS",
            "eSubject": {
                "state": "{\n  \"className\": \"com.sun.identity.policy...}",
                "className": "com.sun.identity.entitlement.opensso.PolicySubject"
            },
            "entitlement": {
                "actionsValues": {
                    "POST": false,
                    "GET": true
                },
                "applicationName": "iPlanetAMWebAgentService",
                "name": "authorize",
                "resourceNames": [
                    "https://www.example.com:443/*?*"
                ]
            }
        }
    },
    "statusMessage": "OK"
}

$ cat update.json {
    "name": "Example HTTP",
    "eSubject": {
        "state": {
            "className": "com.sun.identity.policy.plugins.AuthenticatedUsers",
            "exclusive": false,
            "name": "All Authenticated Users",
            "values": []
        },
        "className": "com.sun.identity.entitlement.opensso.PolicySubject"
    },
    "entitlement": {
        "actionsValues": {
            "POST": false,
            "GET": true
        },
        "applicationName": "iPlanetAMWebAgentService",
        "name": "authorize",
        "resourceNames": [
            "http://www.example.com:80/*?*"
        ]
    }
}$ curl
 --request PUT
 --cookie "iPlanetDirectoryPro=AQIC5...DU3*"
 --data-urlencode "privilege.json@update.json"
 https://openam.example.com:8443/openam/ws/1/entitlement/privilege/Example%20HTTP
{"statusCode":200,"body":"OK","statusMessage":"OK"}

$ curl
 --request DELETE
 --cookie "iPlanetDirectoryPro=AQIC5...DU3*"
 https://openam.example.com:8443/openam/ws/1/entitlement/privilege/Example%20HTTPS
{"statusCode":200,"body":"OK","statusMessage":"OK"}

$ curl
 --request GET
 --cookie "iPlanetDirectoryPro=AQIC5...DU3*"
 https://openam.example.com:8443/openam/ws/1/entitlement/privilege
{
    "statusCode": 200,
    "body": {
        "results": [
            "Example HTTPS",
            "Example HTTP"
        ]
    },
    "statusMessage": "OK"
}

$ curl
 --request GET
 --cookie "iPlanetDirectoryPro=AQIC5...DU3*"
 "https://openam.example.com:8443/openam/ws/1/entitlement/privilege
 ?subject=MJ3QFTr4ZV2QrtlJvXlg0Q2dMRM=&filter=name%3D*HTTP"
{
    "statusCode": 200,
    "body": {
        "results": [
            "Example HTTP"
        ]
    },
    "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 /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%20mail"
 https://openam.example.com:8443/openam/oauth2/access_token
{
    "expires_in": 599,
    "token_type": "Bearer",
    "refresh_token": "f838e7d4-7e84-4743-af7c-9a9c42c2969e",
    "access_token": "9c6a48fc-44b1-4a0c-b4f0-672fba468b0f"
}
$ curl
 --header "iplanetDirectoryPro: AQIC5wM2LY4Sfcxs...EwNDU2NjE0*"
 https://openam.example.com:8443/openam/frrest/oauth2/token/9c6a48fc...fba468b0f
{
    "scope": [
        "mail",
        "cn"
    ],
    "type": [
        "access_token"
    ],
    "username": [
        "demo"
    ],
    "realm": [
        "/"
    ],
    "id": [
        "9c6a48fc-44b1-4a0c-b4f0-672fba468b0f"
    ],
    "parent": [
        "f838e7d4-7e84-4743-af7c-9a9c42c2969e"
    ],
    "expiry_time": [
        "1355741494888"
    ],
    "client_id": [
        "myClientID"
    ]
}

To list tokens, perform an HTTP GET on /frrest/oauth2/token/?_query_id=conditions, where conditions is a comma-separated list of field=value conditions. The fields are taken from the fields returned in the token object through this endpoint.

The following example shows a search for current access tokens that were issued to myClientID.

$ curl
 --header "iplanetDirectoryPro: AQIC5wM2LY4Sfcxs...EwNDU2NjE0*"
 https://openam.example.com:8443/openam/frrest/oauth2/token/?_queryID
 =username%3DmyClientID%2Ctype%3Daccess_token
{
    "result": [
        {
            "scope": [
                "mail",
                "cn"
            ],
            "id": [
                "1b836369-4fcf-4fb2-b819-ee4b1314d4f1"
            ],
            "type": [
                "access_token"
            ],
            "username": [
                "myClientID"
            ],
            "realm": [
                "/"
            ],
            "expiry_time": [
                "1355741986154"
            ]
        },
        {
            "scope": [
                "mail",
                "cn"
            ],
            "type": [
                "access_token"
            ],
            "username": [
                "myClientID"
            ],
            "realm": [
                "/"
            ],
            "id": [
                "5f1763fc-37ae-4698-9e84-d301d49e1f7e"
            ],
            "expiry_time": [
                "1355741982091"
            ]
        }
    ],
    "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/testClient
{"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 Section 3.7.1, "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.

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 '{"name":"newGroup","realm":"/",
    "uniquemember":["uid=demo,ou=people,dc=openam,dc=forgerock,dc=org"]}'
 "https://openam.example.com:8443/openam/json/groups?_action=create"
{
    "name": "newGroup",
    "realm": "/",
    "uniqueMember": [
        "uid=demo,ou=people,dc=openam,dc=forgerock,dc=org"
    ],
    "cn": [
        "newGroup"
    ],
    "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 '{"name":"anotherGroup","realm":"/",
    "uniquemember":["uid=demo,ou=people,dc=openam,dc=forgerock,dc=org"]}'
 https://openam.example.com:8443/openam/json/groups/anotherGroup
{
    "name": "anotherGroup",
    "realm": "/",
    "uniqueMember": [
        "uid=demo,ou=people,dc=openam,dc=forgerock,dc=org"
    ],
    "cn": [
        "anotherGroup"
    ],
    "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 Section 3.12.3, "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": "/",
    "uid": [
        "demo"
    ],
    "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"
    ]
}

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=name,uid
{"name":"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
{
    "name": "myClientID",
    "realm": "/",
    "com.forgerock.openam.oauth2provider.accessToken": [],
    "com.forgerock.openam.oauth2provider.clientSessionURI": [],
    "com.forgerock.openam.oauth2provider.subjectType": [
        "Pairwise"
    ],
    "com.forgerock.openam.oauth2provider.defaultScopes": [
        "[1]=profile",
        "[0]=openid"
    ],
    "com.forgerock.openam.oauth2provider.clientType": [
        "Confidential"
    ],
    "universalid": [
        "id=myClientID,ou=agent,dc=openam,dc=forgerock,dc=org"
    ],
    "userpassword": [
        "{SHA-1}W6ph5Mm5Pz8GgiULbPgzG37mj9g="
    ],
    "com.forgerock.openam.oauth2provider.name": [
        "[0]="
    ],
    "com.forgerock.openam.oauth2provider.redirectionURIs": [
        "[1]=https://openam.example.com:8443/openid/cb-implicit.html",
        "[0]=https://openam.example.com:8443/openid/cb-basic.html"
    ],
    "com.forgerock.openam.oauth2provider.scopes": [
        "[1]=profile",
        "[0]=openid"
    ],
    "com.forgerock.openam.oauth2provider.idTokenSignedResponseAlg": [
        "HmacSHA256"
    ],
    "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"
{
  "name" : "myGroup",
  "realm" : "/",
  "uniquemember" : [ "uid=demo,ou=people,dc=openam,dc=forgerock,dc=org" ],
  "cn" : [ "myGroup" ],
  "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 groups.

$ curl --request PUT --header "iPlanetDirectoryPro: AQIC5...Y3MTAx*"
 --header "Content-Type: application/json"
 --data '{"name":"masterClient","realm":"/","accesstoken":[],
    "clientsessionuri":[],"subjecttype":["Pairwise"],
    "defaultscopes":["[0]=openid"],"clienttype":["Confidential"],
    "universalid":["id=masterClient,ou=agent,dc=openam,dc=forgerock,dc=org"],
    "userpassword":"changeit","name":["[0]="],"redirectionuris":["[0]="],
    "idtokensignedresponsealg":["HmacSHA512"],"scopes":["[0]=openid"],
    "postlogoutredirecturi":[],"sunidentityserverdevicestatus":["Active"],
    "agenttype":["OAuth2Client"],"description":["[0]="]}'
 https://openam.example.com:8443/openam/json/agents/masterClient
{
    "name": "masterClient",
    "realm": "/",
    "com.forgerock.openam.oauth2provider.accesstoken": [],
    "com.forgerock.openam.oauth2provider.clientsessionuri": [],
    "com.forgerock.openam.oauth2provider.subjecttype": [
        "Pairwise"
    ],
    "com.forgerock.openam.oauth2provider.defaultscopes": [
        "[0]="
    ],
    "com.forgerock.openam.oauth2provider.clienttype": [
        "Confidential"
    ],
    "universalid": [
        "id=masterClient,ou=agent,dc=openam,dc=forgerock,dc=org"
    ],
    "userpassword": [
        "{SHA-1}W6ph5Mm5Pz8GgiULbPgzG37mj9g="
    ],
    "com.forgerock.openam.oauth2provider.name": [
        "[0]="
    ],
    "com.forgerock.openam.oauth2provider.redirectionuris": [
        "[0]="
    ],
    "com.forgerock.openam.oauth2provider.idtokensignedresponsealg": [
        "HmacSHA256"
    ],
    "com.forgerock.openam.oauth2provider.scopes": [
        "[0]="
    ],
    "com.forgerock.openam.oauth2provider.postlogoutredirecturi": [],
    "sunidentityserverdevicestatus": [
        "Active"
    ],
    "agenttype": [
        "OAuth2Client"
    ],
    "com.forgerock.openam.oauth2provider.description": [
        "[0]="
    ]
}

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.

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 Section 3.5, "Token Validation, Attribute Retrieval", 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": "testRealm" }'
 https://openam.example.com:8443/openam/json/realms/?_action=create
{"realmCreated":"/testRealm"}

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 '{ "sunOrganizationStatus": "Active" }'
 https://openam.example.com:8443/openam/json/realms/testRealm
{

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.

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 Section 3.13.4, "Updating Realms"

The following example shows an administrator receiving information about the testRealm.

$ curl --header "iplanetDirectoryPro: AQIC5w...2NzEz*"
 https://openam.example.com:8443/openam/json/realms/testRealm
{
    "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.

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.

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

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.

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

The following example deletes a realm. 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/testRealm
 {"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.

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, Procedure 9.3, "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, Procedure 9.4, "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.

Build the module using Apache Maven.

$ cd /path/to/openam-auth-sample
$ mvn install
[INFO] Scanning for projects...
[INFO]
[INFO] ------------------------------------------------------------------------
[INFO] Building openam-auth-sample 1.0.0-SNAPSHOT
[INFO] ------------------------------------------------------------------------
...

[INFO]
[INFO] --- maven-jar-plugin:2.3.1:jar (default-jar) @ openam-auth-sample ---
[INFO] Building jar: ...target/openam-auth-sample-1.0.0-SNAPSHOT.jar
...
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 3.651s
[INFO] Finished at: Thu Oct 03 11:19:07 CEST 2013
[INFO] Final Memory: 20M/226M
[INFO] ------------------------------------------------------------------------

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

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.