Auth scripting
You can use authentication and authorization (auth) scripting to modify default Advanced Identity Cloud behavior in many situations: client-side authentication, policy conditions, handling OpenID Connect claims, and others.
Use JavaScript for auth scripting in Advanced Identity Cloud. Groovy scripts are deprecated and will eventually be completely replaced with JavaScript scripts.
For JavaScript examples of all auth script types, review the sample scripts. Each sample script includes a list of available variables.
Scripts can potentially emit the personally identifiable information (PII) of your end users into Advanced Identity Cloud logs, and then into external services that consume Advanced Identity Cloud logs. Ping Identity recommends that you establish a review and testing process for all scripts to prevent PII leaking out of your Advanced Identity Cloud tenant environments. |
Auth script types
The auth script types available in Advanced Identity Cloud include the following:
Journeys
Script type | Description | Information |
---|---|---|
Configuration Provider Node |
Runs in a Configuration Provider node as a step in an authentication journey. |
|
Journey Decision Node |
Runs in a Scripted Decision node as a step in an authentication journey. |
OAuth2 / OIDC
Script type | Description | Information |
---|---|---|
OAuth2 Access Token Modification |
Modifies the key-value pairs contained within access tokens before they’re issued to a client. |
|
OAuth2 Evaluate Scope |
Retrieves and modifies scopes for OAuth 2.0 access token introspection. |
|
OAuth2 May Act |
Adds the |
|
OAuth2 Trusted JWT Issuer |
Dynamically retrieves the details of an issuer during the JWT profile for authorization grant. |
|
OAuth2 Validate Scope |
Modifies how Advanced Identity Cloud validates requested OAuth 2.0 scopes. |
|
OIDC Claims |
Modifies or overrides OIDC claims when issuing an ID token
or in the response from the |
SAML
Script type | Description | Information |
---|---|---|
SAML2 SP Adapter |
Modifies the processing of the authentication request on the SP. |
|
SAML2 IDP Adapter |
Modifies the processing of the authentication request on the IDP. |
|
SAML2 IDP Attribute Mapper |
Maps user-configured attributes to SAML attributes in the assertion returned by the IDP. |
Other
Script type | Description | Information |
---|---|---|
Client-side Authentication |
Runs on the client during authentication. |
|
Library |
Contains reusable functionality that can be imported into journey decision node scripts or other library scripts. |
|
Policy Condition |
Modifies authorization policy decisions. |
|
Social Identity Provider Profile Transformation |
Adapts the fields received from a social identity provider to align with the fields expected by Advanced Identity Cloud. |
Manage auth scripts
To manage your auth scripts, go to Realm > Scripts > Auth Scripts.
On the Scripts page, you can view a list of existing scripts. To edit, duplicate, or delete a script, click its More () menu.
The edit option in the More menu opens the script in a lightweight editor that features syntax highlighting and validation checking. You can maximize the editor to full screen to edit larger scripts:
① JavaScript editor
② Fullscreen option
③ Syntax highlighting
④ Syntax error highlighting and validation checking
Create a new auth script
-
Go to Realm > Scripts > Auth Scripts, then click + New Script.
-
Choose an auth script type.
After you select a script type, the editor opens. The editor is prepopulated with a default script for that type, which is intended as a starting point for your custom script.
If you selected the wrong script type, click Previous to select a different script type.
For journey decision node scripts, refer to the specific steps for this script type. -
Enter a unique Name and optional Description for the script, then click Save.
After you save a script, you can’t change its type.
Journey decision node scripts
Learn more about journeys in Journeys.
You can also create, edit, and validate journey decision node scripts directly from within a Scripted Decision node.
-
Go to Realm > Journeys.
-
Open a journey in the journey editor.
-
Find an existing scripted decision node or add a new one.
-
Select the scripted decision node to open the context pane on the right side.
-
The following screenshot shows where you can create a new journey decision node script ④ or edit an existing one ⑤:
① Scripted decision node
② Context pane
③ Journey decision node script drop-down
④ Add new journey decision node script
⑤ Edit existing journey decision node script
Create a new journey decision node script
Add a new journey decision node script in the journey editor or from Realm > Scripts > Auth Scripts.
-
Select Legacy or Next Generation on the Choose Script Engine page.
Learn more about the enhanced scripting engine in Next-generation scripts.
-
If you create or edit a Next Generation script, click the Libraries icon in the top right to display the following side panel:
① View and search library scripts to import in your script.
② Click to expand a library script and view its exported methods and constants.
The font colors indicate the exported types:-
Blue for functions
-
Red for numbers
-
Green for strings
-
Orange for boolean types
-
Purple for objects / properties
③ Click the Docs icon to view links to context-related documentation.
A red dot denotes documentation updates.
④ Edit your script and import library scripts as necessary. -
-
Enter a unique Name and optional Description for the script, then click Save.
Custom endpoints
You can use custom endpoints to run arbitrary JavaScript code through the REST API. Custom endpoint scripts are extremely flexible and can extend Advanced Identity Cloud behavior in many ways:
-
Validate user input fields before storing them in a user profile.
-
Create utility functions, such as getting today’s date.
-
Mandate user input fields during registration to support delegated administration decisions.
-
Query identities with a particular relationship, such as being a member of an organization, and page the results.
You can consume custom endpoints within Advanced Identity Cloud or integrate them into your external UIs or system applications.
Custom endpoints scripting introduction
For an introduction to custom endpoints scripting, read the following:
To understand how to create identity object query expressions to use in the request.queryExpression property, learn more in Define and call data queries.
|
Scripts can potentially emit the personally identifiable information (PII) of your end users into Advanced Identity Cloud logs, and then into external services that consume Advanced Identity Cloud logs. Ping Identity recommends that you establish a review and testing process for all scripts to prevent PII leaking out of your Advanced Identity Cloud tenant environments. |
Manage custom endpoints
To manage your custom endpoints, go to Realm > Scripts > Custom Endpoints.
On the Custom Endpoints page, you can view a list of existing custom endpoints. To edit, duplicate, or delete a custom endpoint, click its More () menu.
The edit option in the More menu opens the custom endpoint script in a lightweight editor. The editor features syntax highlighting and validation checking. Maximize the editor to full screen to edit larger scripts:
① Endpoint name
② JavaScript editor
③ Fullscreen option
④ Syntax highlighting
⑤ Validation checking
⑥ cURL request tab, learn more in Generate a cURL request for a custom endpoint
⑦ Test tab, learn more in Run a test request for a custom endpoint
Create a custom endpoint
-
Go to Realm > Scripts > Custom Endpoints, then click + New Script.
-
Enter a Name for your new endpoint; for example,
getDate
.-
Access the new custom endpoint over HTTP at:
https://<tenant-env-fqdn>/openidm/endpoint/<name>
-
Access the new custom endpoint in a script using:
openidm.read('endpoint/<name>')
-
-
(Optional) Enter a Description for your new endpoint; for example,
Get the current date
. -
Next, use the editor to create your script. The editor is prepopulated with a default script, which is intended as a starting point for your custom script.
-
To test your script, click Save, then either:
-
When your testing is complete, click Save and Close.
Generate a cURL request for a custom endpoint
In the script editor:
-
Click the angled brackets icon (<>) to open the cURL Request tab.
-
In the Method field, choose an HTTP request method for the cURL request. Learn more about how HTTP request methods relate to the script
request.method
property values in this mapping table. -
(Optional) In the Body field, enter a JSON-formatted body for the cURL request (except when using the
GET
HTTP request method). For example:{ "param1": "foo", "param2": "bar" }
In the script, you can access the body using the request.content
property. The example above maps torequest.content.param1
andrequest.content.param2
. -
Click Generate to output the cURL request, which appears below your script. The cURL request is complete with an access bearer token and ready to run.
-
Click the copy icon () to copy the cURL request from the editor, then paste and run it in a terminal window.
Run a test request for a custom endpoint
In the script editor:
-
Click the triangle icon () to open the Test tab.
-
In the form field, enter a JSON-formatted configuration object for the cURL request. The form field is prepopulated with a default configuration object:
{ "request": { "method": "create" } }
This default configuration object creates a request using the
POST
HTTP request method. Learn more about how HTTP request methods relate to the scriptrequest.method
variable parameter values in this mapping table. -
(Optional) To supply a body with the request, add a
request.content
property:{ "request": { "method": "create", "content": { "param1": "foo", "param2": "bar" } } }
In the script, you access the body using the request.content
property. The example above maps torequest.content.param1
andrequest.content.param2
. -
Click Run to run the cURL request. The result appears below the editor.
Event hooks
The topics on this page are for tenants created on or after January 12, 2023. Learn more in Event hooks migration FAQ. |
Event hooks let you trigger scripts during various stages of the lifecycle of users, roles, assignments, organizations, groups[1], and applications.
You can trigger scripts when one of these identity objects is created, updated, retrieved, deleted, validated, or stored in the repository. You can also trigger a script when a change to an identity object triggers an implicit synchronization operation.
Post-action scripts let you manipulate identity objects after they are created, updated, or deleted.
For some links to help with writing scripts for event hooks, and a few examples, learn more in Scripting tips.
Scripts can potentially emit the personally identifiable information (PII) of your end users into Advanced Identity Cloud logs, and then into external services that consume Advanced Identity Cloud logs. Ping Identity recommends that you establish a review and testing process for all scripts to prevent PII leaking out of your Advanced Identity Cloud tenant environments. |
Create a new event hook
-
In the Advanced Identity Cloud admin UI, go to Realm > Event Hooks.
-
On the Event Hooks page, click + New Event Hook.
-
On the New Event Hook page, enter event hook details:
-
Enter the Name for the event hook.
-
(Optional) Enter a Description for the event hook.
-
Identify a condition that will trigger a script to run. In the Condition field:
-
Select an identity object type—a user, role, assignment, organization, group, or application—from the Object Name drop-down list.
-
Select an event type from the Event drop-down list.
Note that event types that have already been configured in event hooks do not appear in the drop-down list. Advanced Identity Cloud lets you configure exactly one event hook per condition.
-
-
Specify a script to run when the event hook is triggered. Either:
-
Type JavaScript code into the Script field.
-
Or, click the Upload File toggle, and then click Browse. Then, select the file that contains the JavaScript code that will run when the event hook is triggered.
-
-
(Optional) Enter variables to be passed to the event hook’s script. Either:
-
Click + Add Variables, and then enter variable names and values in the Variables > Name and Variables > Value fields.
-
Or, click the JSON toggle, and then type JSON-formatted values into the Variables field.
-
-
-
Click Save.
Scripting tips
The following links contain general information to help you write scripts triggered by event hooks:
The sections that follow contain code snippets that might be helpful when you start developing your own event hook scripts.
Use a variable in an event hook script
This example adds a prefix to a user’s last name (sn
attribute) in the user creation event hook.
-
Add a variable named
myCompany
to the event hook, and set its value to the desired prefix. -
Specify a script similar to the following in the event hook:
object.sn = myCompany + "-" + object.sn;
Use an ESV in an event hook script
This example sets the value of a user’s Description
attribute to the value of an ESV in the user creation event hook.
-
Either specify the ESV in a variable:
-
Add a variable named
myDescriptionESVValue
to the event hook. -
Set the variable’s value to
&{esv.myDescription}
. -
Specify a script similar to the following in the event hook:
object.description = myDescriptionESVValue;
-
-
Or, use the
identityServer
object to get the ESV value:object.description = identityServer.getProperty("esv.myDescription")
Authenticate to Advanced Identity Cloud REST API
The Advanced Identity Cloud REST API has two different authentication methods, depending on what you are trying to achieve:
-
Use an API key and secret for read-only operations.
Examples: Advanced Identity Cloud monitoring and logging. -
Use an access token for access management operations or identity management operations.
Examples: Setting up authentication journeys or policies; configuring user profiles, roles, or assignments.
Summary of authentication methods
The following table summarizes the REST API endpoints and their different authentication methods:
REST endpoints | Authentication method |
---|---|
|
Not applicable (publicly accessible endpoint) |
|
API key and secret. |
|
Access token |
Authenticate to Advanced Identity Cloud REST API with API key and secret
You will need an API key and secret to authenticate to the following Advanced Identity Cloud REST API endpoints:
-
/monitoring
-
/logs
Summary of use:
-
Create an API key and secret in the Advanced Identity Cloud admin UI.
-
Set the API key and secret as
x-api-key
andx-api-secret
HTTP headers for each API request:x-api-key: <api-key> x-api-secret: <api-secret>
Get an API key and secret
-
In the Advanced Identity Cloud admin UI, click the user icon, and then click Tenant Settings.
Show me where
-
On the Global Settings tab, click Log API Keys.
-
Click New Log API Key, provide a name for the key, and then click Create Key.
A dialog box appears containing the new keys:
-
Store the
api_key_id
andapi_key_secret
values securely.You cannot view the api_key_secret
value again once you click Done. -
Click Done.
Use an API key and secret
To use the API credentials, set them as x-api-key
and x-api-secret
HTTP headers:
Show request
$ curl \
--request GET 'https://<tenant-env-fqdn>/monitoring/logs/sources?_prettyPrint=true' \
--header 'x-api-key: <api-key>' \
--header 'x-api-secret: <api-secret>'
Show response
{
"result": [
"am-access",
"am-activity",
"am-authentication",
"am-config",
"am-core",
"am-everything",
"idm-access",
"idm-activity",
"idm-authentication",
"idm-config",
"idm-core",
"idm-everything",
"idm-recon",
"idm-sync"
],
"resultCount": 14,
"pagedResultsCookie": null,
"totalPagedResultsPolicy": "NONE",
"totalPagedResults": 1,
"remainingPagedResults": 0
}
Authenticate to Advanced Identity Cloud REST API with access token
You need an access token to authenticate to the following Advanced Identity Cloud REST API endpoints:
-
/am/*
-
/openidm/*
-
/.well-known/*
-
/environment/certificates
,/environment/csrs
(self-managed certificate endpoints) -
/environment/content-security-policy/*
-
/environment/cookie-domains
(cookie domains endpoint) -
/environment/custom-domains
-
/environment/promotion/*
(self-service promotion endpoints) -
/environment/proxy-connect/*
(Proxy Connect endpoints) -
/environment/release
(release endpoint) -
/environment/restart
,/environment/secrets
,/environment/variables
(ESV endpoints) -
/environment/sso-cookie
Summary of use:
-
Create a service account in the Advanced Identity Cloud admin UI and download a private key.
-
Create a JSON Web Token (JWT) and sign it using the private key.
-
Create an access token using the JWT profile for OAuth 2.0 authorization grant flow.
-
Set the access token as a bearer token in the
Authorization
HTTP header for each API request:Authorization: Bearer <access-token>
Get an access token
Prerequisites
You need the jose command-line tool to run some of the commands. You can find installation instructions for your particular package manager in https://command-not-found.com/jose.
Step 1: Create a service account and download its private key
-
Follow the steps in Create a new service account.
-
In step 9, save the private key as a local file called
key.jwk
. -
Note the ID for the service account you created. An example of an ID is
449d7e27-7889-47af-a736-83b6bbf97ec5
.
-
Step 2: Create and sign a JWT
-
Set the following variables in your terminal, to be used as claims in a JWT payload:
-
Set
SERVICE_ACCOUNT_ID
to hold the ID of the service account. For use in theiss
(issuer) andsub
(subject) claims.$ SERVICE_ACCOUNT_ID="<service-account-id>"(1)
1 Replace <service-account-id>
with the service account ID; for example,449d7e27-7889-47af-a736-83b6bbf97ec5
. -
Set
AUD
to hold the URL (including port number) where the JWT will be used to request the access token. For use in theaud
(audience) claim.$ AUD='https://<tenant-env-fqdn>:443/am/oauth2/access_token'
-
Set
EXP
to hold a 15-minute expiration time for the JWT, expressed as a Unix timestamp. For use in theexp
(expiration time) claim.$ EXP=$(($(date -u +%s) + 899))
Service account access tokens have a non-configurable, fixed expiry of 899 seconds (15 minutes), so the previous example sets a timestamp value that matches the fixed expiry. Despite the expiry being non-configurable, you must supply the exp
claim, set with a nominal future timestamp, to create an access token successfully. -
Set
JTI
to hold a unique ID for the JWT. For use in thejti
(JWT ID) claim.$ JTI=$(openssl rand -base64 16)
-
-
Combine the claims to create a payload for the JWT:
$ echo -n "{ \"iss\":\"${SERVICE_ACCOUNT_ID}\", \"sub\":\"${SERVICE_ACCOUNT_ID}\", \"aud\":\"${AUD}\", \"exp\":${EXP}, \"jti\":\"${JTI}\" }" > payload.json
-
Sign the JWT using the private key you downloaded and saved as
key.jwk
in step 1a:$ jose jws sig -I payload.json -k key.jwk -s '{"alg":"RS256"}' -c -o jwt.txt
Step 3: Get an access token using the JWT profile authorization grant
-
Request an access token from the
/oauth2/access_token
endpoint using the JWT:$ curl \ --request POST ${AUD} \ --data "client_id=service-account" \(1) --data "grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer" \(2) --data "assertion=$(< jwt.txt)" \(3) --data "scope=<scope>"(4)
1 The client ID service-account
targets the built-in OAuth 2.0 public client for service accounts. The client only allows the JWT profile for OAuth 2.0 authorization grant flow.
+ NOTE: Access the built-in OAuth 2.0 public client using the tenant FQDN. You cannot access it using an Alpha or Bravo realm alias URL or a custom domain URL.
2 The grant type urn:ietf:params:oauth:grant-type:jwt-bearer
represents the JWT profile for OAuth 2.0 authorization grant flow.3 The assertion
parameter is populated with the output of the signed JWT from step 2c.4 Replace <scope>
with a scope or a space delimited set of scopes; for example,fr:idc:esv:*
orfr:am:* fr:idm:*
. Learn more in Service account scopes. The specified scopes must be the same as (or a subset of) the scopes that you assigned to the service account. -
Examine the response to find the access token, represented as
access_token
:{ "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9... ...8ECmkyDJKow8Qp_Tnp_lGNRJzLWi18iUGQrCTtxyTXw", "scope": "fr:am:* fr:idm:*", "token_type": "Bearer", "expires_in": 899 }
Use an access token
To use the access token with the REST API, set it as a bearer token in the Authorization
HTTP header for each API request.
The following example uses the access token to get a list of identities:
Show request
$ curl \
--request GET 'https://<tenant-env-fqdn>/openidm/managed/<realm>_user?_fields=userName,givenName,sn,mail,accountStatus&_prettyPrint=true&_queryFilter=true' \(1)
--header 'Authorization: Bearer <access-token>'(2)
1 | Replace <realm> with the realm where you created the access token. |
2 | Replace <access-token> with the access_token in the authentication response (learn more in Get an access token). |
Show response
{
"result": [
{
"_id": "f413db4c-cebd-4950-81e6-57bdb47921a4",
"_rev": "0000000016e6754b",
"userName": "exampleuser",
"accountStatus": "active",
"givenName": "Example",
"sn": "User",
"mail": "exampleuser@example.com"
},
{
"_id": "15249a65-8f9a-4063-9586-a2465963cee4",
"_rev": "0000000016e6754b",
"userName": "exampleuser2",
"accountStatus": "active",
"givenName": "Example",
"sn": "User",
"mail": "exampleuser2@example.com"
},
{
"_id": "30485bc4-fdbb-4946-8ce4-1a53c6824d92",
"_rev": "0000000016e6754b",
"userName": "exampleuser3",
"accountStatus": "active",
"givenName": "Example",
"sn": "User",
"mail": "exampleuser3@example.com"
}
],
"resultCount": 3,
"pagedResultsCookie": null,
"totalPagedResultsPolicy": "NONE",
"totalPagedResults": -1,
"remainingPagedResults": -1
}
Advanced Identity Cloud Postman collection
Advanced Identity Cloud provides REST APIs to help you manage identities, authenticate to the system, monitor Advanced Identity Cloud, and more.
You can also use the AM and IDM APIs with Advanced Identity Cloud.
To help you quickly use and understand these REST APIs, Advanced Identity Cloud provides a Postman collection, containing example requests grouped into features.
Features include:
・Intelligent Access
・User Self-Service
・Session Management
・Identity Profiles
・Managed Identities
・Auditing/Monitoring
・OAuth 2.0 Flows
Download Postman and import the Advanced Identity Cloud collection
-
Download and install the Postman application.
-
Download the Advanced Identity Cloud Postman collection.
-
In Postman:
-
Go to File > Import... > Upload Files.
-
Browse to the collection JSON file you downloaded in the previous step, and then click Open.
-
Click Import to bring the collection into your workspace.
-
Create a service account and download its private key
To use the Advanced Identity Cloud Postman collection, you must create a service account that the requests in the collection can use to connect to your Advanced Identity Cloud instance.
Follow the steps in Create a new service account.
-
In step 9, save the private key as a local file called
key.jwk
. -
Make a note of the ID for the service account you created.
An example of an ID is
449d7e27-7889-47af-a736-83b6bbf97ec5
.
Proceed to the next section to learn how to enter these values into the collection, plus other settings necessary to use Postman with Advanced Identity Cloud.
Configure collection variables
The Advanced Identity Cloud Postman collection uses a number of configurable variables to populate the requests.
These variables are stored at the collection level. To view them, click on the top level of the collection menu labeled PingOne Advanced Identity Cloud Collection, and then select the Variables tab.
The variables are initially set with placeholder values that you must modify or replace. For example, the collection needs to know the Advanced Identity Cloud URL, as well as your admin access credentials.
To edit the variables, enter new values in the INITIAL VALUE column. Then click Save to make the edits permanent.
To understand which variables you need to edit before you can use the collection, learn more in Required variable values. To understand which variables you can optionally edit to customize the collection to suit your environment, learn more in Optional variable values.
You can then start using the collection.
You can also override the default collection-level variables by creating a Postman Environment. Use the same variable names as the Required variable values. This is useful if you have more than one Advanced Identity Cloud tenant, as you can configure the connection and username values as separate environments in Postman. You can also enter potentially sensitive values in an environment to keep them separate from the collection. This means you can share the collection without sharing your credentials. For information on creating a Postman Environment, learn more in Managing environments in the "Postman Learning Center". |
Required variable values
Before using the collection, you must provide the correct values for the following variables. You can provide the value at the collection level or add them at the environment level.
Ensure you use strong passwords for access credentials. |
Server URLs
platformUrl
-
- Default
-
https://<tenant-env-fqdn>
- Description
-
Specifies the root URL of your Advanced Identity Cloud.
amUrl
-
- Default
-
https://<tenant-env-fqdn>/am
- Description
-
Specifies the URL of the Access Management (AM) component of your Advanced Identity Cloud.
idmUrl
-
- Default
-
https://<tenant-env-fqdn>/openidm
- Description
-
Specifies the URL of the Identity Management (IDM) component of your Advanced Identity Cloud.
User credentials
postmanServiceAccountID
-
- Default
-
Not set
- Description
-
Specifies the ID of the service account you created to allow the Postman collection access to your tenant.
The collection uses this ID when creating a JWT to sign, which it then uses to obtain an access token.
The JWT is generated when you run the Prerequisite requests.
- Example
-
c41515a8e-9c7d-4c37-4b2a-58c0fdea2080
postmanServiceAccountJWK
-
- Default
-
Not set
- Description
-
Specifies the private key you downloaded as
key.jwk
when you created the service account.Open the downloaded
key.jwk
in a text editor, and then enter the entire JSON web key into the field in Postman, including the curly braces.The collection uses this key to sign a JWT token, which it then uses to obtain an access token.
The JWK is used to sign the JWT when you run the Prerequisite requests.
- Example
-
{ "d": "MsVF...dmvw", "dp": "0iic...jdrw", "dq": "BXja...4epQ", "e": "AQAB", "kty": "RSA", "n": "stO0...qNyU", "p": "3VoI-ZPcw", "q": "ztGg...EJBw", "qi": "NHkA...NV_Gw" }
postmanClientSecret
-
- Default
-
Not set
- Description
-
Specifies the secret used by the OAuth 2.0 clients the collection creates.
You create these clients when you run the Prerequisite requests.
postmanDemoPassword
-
- Default
-
Not set
- Description
-
Specifies the password used by the managed realm user the collection creates for demonstration purposes.
You create the realm user when you run the Prerequisite requests.
Logging API
logApiKey
-
- Default
-
Not set
- Description
-
Specifies the API key used to access the monitoring endpoints.
Add this key to run the auditing and monitoring requests.
Learn more in Obtaining API Credentials.
- Example
-
0405de08ea73f1d84f
logApiSecret
-
- Default
-
Not set
- Description
-
Specifies the API secret used to access the monitoring endpoints.
Add this key to run the auditing and monitoring requests.
Learn more in Obtaining API Credentials.
- Example
-
58932ad661ccf7ea5eda0b...a8d310e1676c9cac7f
Optional variable values
The collection uses the following additional variables that work using their default values; however, you can modify them.
List of optional variable values
postmanDemoUsername
-
- Default
-
postmanDemoUser
- Description
-
Specifies the username of the managed realm user the collection creates for demonstration purposes.
postmanDemoEmail
-
- Default
-
demo.user@postman.example.com
- Description
-
Specifies the email of the managed realm user the collection creates for demonstration purposes.
Enter an email address you have access to if you want to test the forgotten username or password flows in the user self-service section of the collection.
realm
-
- Default
-
/realms/root/realms/alpha
- Description
-
Specifies the realm that the majority of the requests in the collection use.
You must specify the entire hierarchy of the realm, starting at the root realm.
Prefix each realm in the hierarchy with the
realms
keyword. - Example
-
/realms/root/realms/customers/realms/europe
.
cookieName
-
- Default
-
Not set
- Description
-
Specifies the name of the session cookie the tenant uses to store session tokens.
The collection sets this value automatically when you run the first request in the Prerequisites folder.
loginJourney
-
- Default
-
Login
- Description
-
Specifies the authorization journey name to use.
For information on the default journeys that Advanced Identity Cloud provides, learn more in Login.
redirect_uri
-
- Default
-
https://httpbin.org/anything
- Description
-
Specifies the URI to which the OAuth 2.0 client will redirect the user upon a successful authentication request.
postmanConfidentialClientId
-
- Default
-
postmanConfidentialClient
- Description
-
Specifies the ID of the OAuth 2.0 private client.
postmanPublicClientId
-
- Default
-
postmanPublicClient
- Description
-
Specifies the ID of the OAuth 2.0 public client.
Hard-coded variable values
The collection uses the following additional variables that must not be modified.
List of hard-coded variable values
postmanUtilLib
-
- Description
-
Contains the
postman-util-lib
utility library that the collection uses to sign requests and generate certain keys.Learn more in postman-util-lib on GitHub.
Use the collection
Before using the Advanced Identity Cloud Postman collection, you should run the Prerequisite requests. The requests configure your Advanced Identity Cloud with the necessary elements, such as OAuth 2.0 clients and managed users
Running the prerequisite requests
Ensure you have configured the required collection variables as described in Configure collection variables before running the prerequisite requests. |
-
In Postman, with the Advanced Identity Cloud collection loaded, open the Prerequisites section.
-
Select the first request in the list, examine the details, and when you’re satisfied the request is properly formed, click Send.
Many of the requests have associated tests; for example, that the response code was
200
. Postman displays the test results alongside the response to the request.Many of the requests set a global variable containing a value returned in the response for use in subsequent requests.
View the details of these in the Tests tab of a request. You can also view the values of these global variables by clicking Environment Quick Look ().
-
Repeat the previous step for each request in the Prerequisites folder.
When completed, Advanced Identity Cloud contains the following:
-
An alpha_user identity, named
postmanDemoUser
by default, which demonstrates a number of user-related endpoints, such as identity profiles, and user self-service. -
Two OAuth 2.0 clients:
-
A client named
postmanConfidentialClient
, which is used by the OAuth 2.0 requests to demonstrate a number of grant flows. -
A client named
postmanPublicClient
, which is used by the OAuth 2.0 requests to demonstrate a number of grant flows.
-
If you need to recreate any of the above, or decide to alter the default values, run each of the steps in the Prerequisite folder again.
Running the requests
The requests in the collection are split into different features. To run the calls for a feature, open the relevant folder, and run each request in sequence.
The value in square brackets in the name shows what type of authentication the request requires:
[User]
-
The request acts on a user’s data or profile.
These requests often authenticate as
postmanDemoUser
in the collection. [fr:am:*]
-
The request requires an access token that has the
fr:am:*
scope so that it can perform access management related actions.These requests authenticate as the service account you created earlier.
[fr:idm:*]
-
The request requires an access token that has the
fr:am:*
scope so that it can perform identity management related actions.These requests authenticate as the service account you created earlier.
Note that intelligent access and identity profiles have additional functionality. Refer to each section for details.
Intelligent access
There are scripts in the Intelligent Access requests that attempt to detect the callbacks that the first step returns, and sets the next request to handle it.
To view the details of this script:
-
Click on the top level of the collection menu (labelled PingOne Advanced Identity Cloud Collection), then select the Pre-request Scripts tab.
-
Within the tab, examine the
detectCallbacks
script.
When manually running through the steps, examine the response returned in the first call, and run the relevant next step. The collection is able to handle the following ready-to-use callbacks:
Step | Callback |
---|---|
Step 2a |
Username and password callbacks, together in a page node. |
Step 2b |
Validated create username and password callbacks, together in a page node. |
Step 2c |
Choice callbacks. |
Step 2d |
Text input callbacks. |
Step 2e |
Device profile callbacks. Learn more in Configure Device Profiling. |
Step 2f |
Progressive profile callbacks. |
Identity profiles
Some endpoints require the ID of an identity, rather than the username.
An example of this is when getting the OAuth 2.0 profiles a user has provided consent to.
When running the Identity Profiles requests, ensure you have also executed the request named Step 3: [User] Read session info and store ID in the Authenticate as "Postman Demo User" folder.
The result is stored in the demoUserId
global variable.
Advanced Identity Cloud REST
Advanced Identity Cloud REST is a REST API framework defining common APIs to access web resources and collections of resources.
Resources
Endpoints generally return JSON-format resources, though resource formats can depend on the implementation.
Resources in collections can be found by their unique identifiers (IDs).
IDs are exposed in the resource URIs.
For example, if a service has a user collection under /users
, you can access a user at /users/user-id
.
The ID is also the value of the _id
field of the resource.
Resources are versioned using revision numbers.
A revision is specified in the resource’s _rev
field.
Revisions make it possible to figure out whether to apply changes
without resource locking and without distributed transactions.
Verbs
The Advanced Identity Cloud REST APIs use the following verbs, sometimes referred to collectively as CRUDPAQ. For details and HTTP-based examples of each, follow the links to the sections for each verb.
Verb | Description |
---|---|
Add a new resource with HTTP PUT or HTTP POST. |
|
Retrieve a single resource with HTTP GET. |
|
Replace an existing resource with HTTP PUT. |
|
Remove an existing resource with HTTP DELETE. |
|
Modify part of an existing resource with HTTP PATCH. |
|
Perform a predefined action with HTTP POST. |
|
Search a collection of resources with HTTP GET. |
Query parameters
Advanced Identity Cloud REST reserved query string parameter names start with an underscore (_
).
Reserved query string parameters include, but are not limited to, the following names:
_action
_api
_countOnly
_crestapi
_fields
_mimeType
_pageSize
_pagedResultsCookie
_pagedResultsOffset
_prettyPrint
_queryExpression
_queryFilter
_queryId
_sortKeys
_totalPagedResultsPolicy
Some parameter values are not safe for URLs; URL-encode parameter values as necessary. |
Extension points
The action verb is the main vehicle for extensions.
For example, to create a new user with HTTP POST rather than HTTP PUT, you might use /users?_action=create
.
An endpoint can define additional actions.
For example, /tasks/1?_action=cancel
.
A service can define stored queries to call by ID.
For example, /groups?_queryId=hasDeletedMembers
.
Stored queries can call for additional parameters.
The parameters are also passed in the query string.
Which parameters are valid depends on the stored query.
Create
There are two ways to create a resource: HTTP POST or HTTP PUT.
To create a resource using POST,
perform an HTTP POST with the query string parameter _action=create
and the JSON resource as a payload.
The service creates the identifier if not specified:
POST /users?_action=create HTTP/1.1
Host: example.com
Accept: application/json
Content-Length: ...
Content-Type: application/json
{ JSON resource }
To create a resource using PUT, perform an HTTP PUT
with the case-sensitive identifier for the resource in the URL path and the JSON resource as a payload.
Optionally, include the If-None-Match: *
header to prevent overwriting an existing object:
PUT /users/some-id HTTP/1.1
Host: example.com
Accept: application/json
Content-Length: ...
Content-Type: application/json
If-None-Match: *
{ JSON resource }
The _id
and the content of the resource depend on the endpoint.
The service is not required to use the _id
the client provides.
The response to the create request indicates the resource location as the value of the Location
header.
-
If you do include the
If-None-Match: *
header, the request creates the object if it does not exist or fails if the object does exist. -
If you do not include the
If-None-Match: *
header, the request creates the object if it does not exist or updates the object if it does exist. -
If you include the
If-None-Match
header with any value other than*
, the response is an HTTP 400 Bad Request error. For example, creating an object withIf-None-Match: revision
returns a bad request error.
Parameters
You can use the following query string parameters:
Parameter | Description |
---|---|
|
Return only the specified fields in the body of the response. The If the |
|
Format the body of the response. |
Read
To retrieve a single resource, perform an HTTP GET on the resource by its case-sensitive identifier (_id
)
and accept a JSON response:
GET /users/some-id HTTP/1.1
Host: example.com
Accept: application/json
Parameters
You can use the following query string parameters:
Parameter | Description |
---|---|
|
Return only the specified fields in the body of the response. The If the |
|
Some resources have fields containing multimedia resources, such as a profile photo. If the feature is enabled for the endpoint, read a single multimedia resource field by specifying the field and mime-type. The content type of the field value returned matches the mime-type. The body of the response is the multimedia resource Do not use the |
|
Format the body of the response. |
Update
To update a resource, perform an HTTP PUT
including the case-sensitive identifier (_id
) as the final element of the path to the resource
and the JSON resource as the payload.
Use the If-Match: _rev
header to verify the version you modify.
Use If-Match: *
if the version does not matter.
PUT /users/some-id HTTP/1.1
Host: example.com
Accept: application/json
Content-Length: ...
Content-Type: application/json
If-Match: _rev
{ JSON resource }
When updating a resource, include all the attributes to retain. Omitting an attribute in the resource amounts to deleting it unless it is not under the control of your application. Attributes not under the control of your application include private and read-only attributes. Virtual attributes and relationship references might not be under the control of your application.
Parameter | Description |
---|---|
|
Return only the specified fields in the body of the response. The If the |
|
Format the body of the response. |
Delete
To delete a single resource, perform an HTTP DELETE by its case-sensitive identifier (_id
) and accept a JSON response:
DELETE /users/some-id HTTP/1.1
Host: example.com
Accept: application/json
Parameters
You can use the following query string parameters:
Parameter | Description |
---|---|
|
Return only the specified fields in the body of the response. The If the |
|
Format the body of the response. |
Patch
To patch a resource, send an HTTP PATCH request with an array of operation objects in the payload. Each operation object uses some combination of these fields:
operation
-
The type of operation.
field
-
The target field.
value
-
The value to apply.
from
-
The source field.
The service applies the PATCH operations in order.
PATCH /users/some-id HTTP/1.1
Host: example.com
Accept: application/json
Content-Length: ...
Content-Type: application/json
If-Match: _rev
{ JSON array of patch operations }
PATCH operations work differently depending on the field types:
- Single-value
-
An object, string, boolean, or number.
- List semantics array
-
The elements are ordered, and duplicates are allowed.
- Set semantics array
-
The elements are not ordered, and duplicates are not allowed.
Whether an endpoint supports a specific operation
depends on the implementation.
Add operation
The add
operation ensures the target field contains the value provided, creating parent fields as necessary.
If the target field is single-valued, the value replaces the value of the target.
If the value is an array, the outcome depends on the type:
- List semantics arrays
-
If you
add
an array of values, the operation appends the array to the existing list of values.If you
add
a single value, specify an ordinal element in the target array, or use the{-}
special index to add the value to the end of the list. - Set semantics arrays
-
The operation merges the value(s) in the patch with the existing set of values. Any duplicates in the array are removed.
As an example, start with the following list semantic array resource:
{
"fruits": ["orange", "apple"]
}
The following add
operation appends pineapple
at the end of the array:
{
"operation": "add",
"field": "/fruits/-",
"value": "pineapple"
}
The resulting resource is:
{
"fruits": ["orange", "apple", "pineapple"]
}
Copy operation
The copy
operation replaces the value(s) of the target field with the value(s) from the source field.
The following example replaces the value of another_mail
with the value of mail
:
[{
"operation": "copy",
"from": "mail",
"field": "another_mail"
}]
If the source field value and the target field value are arrays, the result depends on whether the array has list semantics or set semantics. Learn more in Add operation.
Increment operation
The increment
operation changes the value or values of the target field by the amount you specify.
The value must be a positive or negative number.
The target must be a single-valued number.
The following example adds 1000
to /user/payment
:
[{
"operation": "increment",
"field": "/user/payment",
"value": "1000"
}]
Move operation
The move
operation removes existing values from the source and adds them to the target field.
The operation creates the target field if it does not exist.
The following example moves surname
values to lastName
:
[{
"operation": "move",
"from": "surname",
"field": "lastName"
}]
To apply a move
to an array, the source and target must have compatible semantics.
Learn more in Add operation.
Remove operation
The remove
operation deletes values in the target field.
When no value is specified, the operation removes the field:
[{
"operation": "remove",
"field": "phoneNumber"
}]
For arrays, the result depends on the semantics:
- List semantic arrays
-
Delete the specified element in the array.
The following example removes the first phone number (zero-based array index):
[{ "operation": "remove", "field": "/phoneNumber/0" }]
- Set semantic arrays
-
Delete the specified values from the array.
The following example removes the specified phone number:
[{ "operation": "remove", "field": "/phoneNumber", "value": "+1 408 555 9999" }]
Replace operation
The replace
operation removes existing values in the target, replacing them with the provided value(s).
The following example replaces existing telephoneNumber
values with +1 408 555 9999
:
[{
"operation": "replace",
"field": "/telephoneNumber",
"value": "+1 408 555 9999"
}]
For list semantic arrays, you can target items by their indexes. As an example, start with the following resource:
{
"fruits": ["apple", "orange", "kiwi", "lime"]
}
Apply the following operation:
[{
"operation": "replace",
"field": "/fruits/1",
"value": "pineapple"
}]
The result is:
{
"fruits": ["apple", "pineapple", "kiwi", "lime"]
}
Transform operation
The transform
operation changes the field value based on a script or a data transformation command.
The following example applies the something.js
script to the /objects
value:
[{
"operation": "transform",
"field": "/objects",
"value": {
"script": {
"type": "text/javascript",
"file": "something.js"
}
}
}]
Limitations
Some HTTP client libraries do not support the HTTP PATCH operation.
Make sure the library you use supports HTTP PATCH before using this REST operation.
For example, the Java method HttpURLConnection.setRequestMethod("PATCH")
throws ProtocolException
.
Parameters
You can use the following query string parameters:
Parameter | Description |
---|---|
|
Return only the specified fields in the body of the response. The If the |
|
Format the body of the response. |
Action
Actions are a means of extending Advanced Identity Cloud REST APIs and are defined by the resource provider. The actions you can use depend on the implementation.
The standard action indicated by _action=create
is described in Create.
Parameters
You can use the following query string parameters. Other parameters depend on the specific action implementation:
Parameter | Description |
---|---|
|
Return only the specified fields in the body of the response. The If the |
|
Format the body of the response. |
Query
To query a resource collection, which you can think of as a resource container,
perform an HTTP GET and accept a JSON response including at least a _queryFilter
or _queryId
parameter.
These parameters cannot be used together.
GET /users?_queryFilter=true HTTP/1.1
Host: example.com
Accept: application/json
The endpoint returns the result as a JSON object including a results
array
and other fields related to the query string parameters.
Parameters
You can use the following query string parameters:
Parameter | Description |
---|---|
|
Return only the specified fields in each element of the The If the |
|
The string is an opaque cookie to keep track of the position in the search results.
The service returns the cookie in the JSON response as the value of In the request Use this parameter with the The |
|
When The |
|
Return query results in pages of this size. After the initial request, use |
|
Format the body of the response. |
|
Query filters request entries matching the filter expression. You must URL-escape the filter expression. Learn more in Filter expressions. |
|
Specify a query by its identifier. Specific queries can take their own query string parameter arguments depending on the implementation. |
|
Sort the resources returned based on the specified field(s) in As ascending order is the default, including the
The |
|
When a non-zero The
If no count policy is specified in the query, or if |
Filter expressions
Query filters request entries matching the filter expression. You must URL-escape the filter expression.
The string representation is summarized as follows:
Expr = OrExpr
OrExpr = AndExpr ( 'or' AndExpr ) *
AndExpr = NotExpr ( 'and' NotExpr ) *
NotExpr = '!' PrimaryExpr | PrimaryExpr
PrimaryExpr = '(' Expr ')' | ComparisonExpr | PresenceExpr | LiteralExpr
ComparisonExpr = Pointer OpName JsonValue
PresenceExpr = Pointer 'pr'
LiteralExpr = 'true' | 'false'
Pointer = JSON pointer
OpName = 'eq' | # equal to
'co' | # contains
'sw' | # starts with
'lt' | # less than
'le' | # less than or equal to
'gt' | # greater than
'ge' | # greater than or equal to
STRING # extended operator
JsonValue = NUMBER | BOOLEAN | '"' UTF8STRING '"'
STRING = ASCII string not containing white-space
UTF8STRING = UTF-8 string possibly containing white-space
JsonValue components of filter expressions follow
RFC 7159: The JavaScript Object Notation (JSON) Data Interchange Format.
In particular, as described in section 7 of the RFC, the escape character in strings is the backslash character.
For example, to match the identifier test\
, use _id eq 'test\\'
.
In the JSON resource, the \
is escaped the same way: "_id":"test\\"
.
When using a query filter in a URL, notice the filter expression is part of a query string parameter.
URL-encoded the filter expression.
Learn more in
RFC 3986: Uniform Resource Identifier (URI): Generic Syntax.
For example, whitespace, double quotes ("
), parentheses, and exclamation characters need URL encoding.
The following rules apply to URL query components:
query = *( pchar / "/" / "?" )
pchar = unreserved / pct-encoded / sub-delims / ":" / "@"
unreserved = ALPHA / DIGIT / "-" / "." / "_" / "~"
pct-encoded = "%" HEXDIG HEXDIG
sub-delims = "!" / "$" / "&" / "'" / "(" / ")"
/ "*" / "+" / "," / ";" / "="
ALPHA
, DIGIT
, and HEXDIG
are core rules of
RFC 5234: Augmented BNF for Syntax Specifications:
ALPHA = %x41-5A / %x61-7A ; A-Z / a-z
DIGIT = %x30-39 ; 0-9
HEXDIG = DIGIT / "A" / "B" / "C" / "D" / "E" / "F"
As a result, a backslash escape character in a JsonValue component
is percent-encoded in the URL query string parameter as %5C
.
To encode the query filter expression _id eq 'test\\'
, use _id+eq'test%5C%5C'+
, for example.
A simple filter expression can represent a comparison, presence, or a literal value.
For comparison expressions use json-pointer comparator json-value, where the comparator is one of the following:
eq
(equals)
co
(contains)
sw
(starts with)
lt
(less than)
le
(less than or equal to)
gt
(greater than)
ge
(greater than or equal to)
For presence, use json-pointer pr to match resources where:
-
The JSON pointer is present.
-
The value it points to is not
null
.
Literal values include true (match anything) and false (match nothing).
Complex expressions employ and
, or
, and !
(not), with parentheses, (expression)
, to group expressions.
HTTP status codes
When working with a Advanced Identity Cloud REST API, client applications should expect at least the following HTTP status codes. Not all services necessarily return all status codes identified here:
- 200 OK
-
The request succeeded and a resource returned, depending on the request.
- 201 Created
-
The request succeeded and the resource was created.
- 204 No Content
-
The action request succeeded, and there was no content to return.
- 304 Not Modified
-
The read request included an
If-None-Match
header, and the value of the header matched the revision value of the resource. - 400 Bad Request
-
The request was malformed.
- 401 Unauthorized
-
The request requires user authentication.
- 403 Forbidden
-
Access was forbidden during an operation on a resource.
- 404 Not Found
-
The specified resource could not be found, perhaps because it does not exist.
- 405 Method Not Allowed
-
The HTTP method is not allowed for the requested resource.
- 406 Not Acceptable
-
The request contains parameters that are not acceptable, such as a resource or protocol version that is not available.
- 409 Conflict
-
The request would have resulted in a conflict with the current state of the resource.
- 410 Gone
-
The requested resource is no longer available, and will not become available again. This can happen when resources expire.
- 412 Precondition Failed
-
The resource’s current version does not match the version provided.
- 415 Unsupported Media Type
-
The request is in a format not supported by the requested resource for the requested method.
- 428 Precondition Required
-
The resource requires a version, but no version was supplied in the request.
- 500 Internal Server Error
-
The service encountered an unexpected condition that prevented it from fulfilling the request.
- 501 Not Implemented
-
The resource does not support the functionality required to fulfill the request.
- 503 Service Unavailable
-
The requested resource was temporarily unavailable. The service may be disabled, for example.