How do I create and update an Agent in AM (All versions) using the REST API?

Last updated Mar 30, 2023

The purpose of this article is to provide information on creating and updating an Agent in AM using the REST API. This information also applies to OAuth 2.0 clients, OIDC clients and the agent authenticator.

2 readers recommend this article

Overview

You can create the following different types of agents using the REST API:

WebAgent
J2EEAgent
OAuth2Client (for OAuth2 clients and OpenID Connect (OIDC) clients)
SharedAgent (Agent Authenticator)

The agent attributes you can set vary according to the agent type. To help you get started, you should use the API Explorer as detailed in the Online REST API reference or the Postman collections attached to this article. You can create a basic agent profile first, which will return the full agent profile in the response (in JSON format). You then know which attributes apply to that agent type and can update the agent profile accordingly.

A Postman collection (Create Agent AM5.postman_collection.json has been provided to make it easier to create agents. You will need to edit the Headers for the Authenticate request to provide your credentials, edit the Body for the Create and Update agent requests to provide details of the agent you want to create or update, and specify the name of the agent/client as a URL parameter. See How do I use the Postman collections that are provided for AM (All versions)? for further information on installing Postman and using a collection.

The following sections give examples for creating and updating different agent types:

Creating and updating a Web agent
Creating and updating an OAuth 2.0 client

Attribute values

Attributes that can be multi-valued are shown in the response as follows:

{ "com.sun.identity.agents.config.notenforced.ip": [ "[0]=" ], "com.sun.identity.agents.config.session.attribute.mapping": [ "[]=" ], }

and take the form [ "[0]=Value1","[1]=Value2" ] when including multiple values in your REST call.

Attributes that only permit a single value are in the form "Value".

Note

Please observe the following when constructing REST calls:

Make the REST call to the actual AM server URL (not lb).
Change the name of the iPlanetDirectoryPro header to the name of your actual session cookie.
Set this session cookie header to the token returned when you authenticated.
Ensure the Accept-API-Version header contains a valid resource version.

See How do I avoid common issues with REST calls in AM (All versions)? for further information.

Creating and updating a Web agent

Creating an agent

You can create a Web agent using the /json/realm-config/agents/WebAgent endpoint. The following example demonstrates creating a Web agent.

Authenticate as an admin user. For example: $ curl -X POST -H "X-OpenAM-Username: amadmin" -H "X-OpenAM-Password: cangetinam" -H "Content-Type: application/json" -H "Accept-API-Version: resource=2.1" https://am.example.com:8443/am/json/realms/root/authenticate?authIndexType=service&authIndexValue=adminconsoleserviceExample response: { "tokenId": "AQIC5wM2LY4SfcxsuvGEjcsppDSFR8H8DYBSouTtz3m64PI.*AAJTSQACMDIAAlNLABQtNTQwMTU3NzgxODI0NzE3OTIwNAEwNDU2NjE0*", "successUrl": "/am/console", "realm": "/" }
Create a basic Web agent using the following curl command ensuring you replace myAgent in the URL with the name of your agent: $ curl -X PUT -H "iPlanetDirectoryPro: AQIC5wM2LY4Sfcxs...EwNDU2NjE0*" -H "Content-Type: application/json" -H "Accept-API-Version: resource=1.0" -d '{ "userpassword":"password", "agentUrl":"http://www.example.com:80/", "serverUrl":"https://am.example.com:8443/am/" }' https://am.example.com:8443/am/json/realms/root/realm-config/agents/WebAgent/myAgentExample response for the new Web agent (this has been truncated due to the size of response): { "_id": "myAgent", "_rev": "-906884356", "miscWebAgentConfig": { "anonymousUserId": { "inherited": false, "value": "anonymous" }, "ignoreServerCheck": { "inherited": false, "value": false }, "profileAttributesCookieMaxAge": { "inherited": false, "value": 300 }, "agentLocale": { "inherited": false, "value": "en_US" }, ... "_type": { "_id": "WebAgent", "name": "Web Agents", "collection": true } }

Updating an agent

You use the same request for updating an agent as you do for creating an agent.
You must include all the attributes you wish to retain (omitting an attribute effectively deletes that attribute unless it is not under the control of your application).
You can do a GET on this endpoint to return the current configuration before you do an update.

Creating and updating an OAuth 2.0 client

You can create an OAuth 2.0 client using the /json/realm-config/agents/OAuth2Client endpoint per the documentation: rest-api-oauth2-client-admin-endpoint. This provides a worked example for creating an OAuth 2.0 client.

Updating a client

You use the same request for updating a client as you do for creating a client.
You must include all the attributes you wish to retain (omitting an attribute effectively deletes that attribute unless it is not under the control of your application).
You can do a GET on this endpoint to return the current configuration before you do an update.

Related Training

N/A

Related Issue Tracker IDs

OPENAM-11642 (CustomProperties do not work when creating J2EE/Web Agents via REST)