Identity Cloud

Manage configuration placeholders using the API

For background on configuration placeholders, refer to Introduction to configuration placeholders.

Examples

Configure tenant email provider

This example shows how to configure placeholders in your tenant email provider configuration. Refer to Email provider.

  1. Get an access token. Refer to Get an access token.

  2. Get the email provider configuration:

    Show request
    $ curl \
    --request GET 'https://<tenant-env-fqdn>/openidm/config/external.email
    --header 'Authorization: Bearer <access_token>' \(1)
    --header 'Content-Type: application/json'
    1 Replace <access-token> with the access token created in step 1.
    Show response
    {
        "_id": "external.email",
        "auth": {
            "enable": true,
            "password": "changeit",
            "username": "example.user"
        },
        "connectiontimeout": 30000,
        "debug": false,
        "from": "\"Example User\" <example.user@example.com>",
        "host": "localhost",
        "port": 465,
        "smtpProperties": [],
        "ssl": {
            "enable": true
        },
        "starttls": {
            "enable": false
        },
        "threadPoolSize": 21,
        "timeout": 30000,
        "writetimeout": 30000
    }
  3. Create a local copy of the email provider configuration from step 2, then substitute in ESV placeholders:

    {
        "auth": {
            "enable": true,
            "password": "&{esv.email.provider.password}", (1)
            "username": "&{esv.email.provider.username}" (2)
        },
        "connectiontimeout": 30000,
        "debug": false,
        "from": "\"Example User\" <&{esv.email.provider.from.email}>", (3)
        "host": "localhost",
        "port": {
            "$int": "&{esv.email.provider.port}" (4)
        },
        "smtpProperties": [],
        "ssl": {
            "enable": {
                "$bool": "&{esv.email.provider.use.ssl}" (5)
            }
        },
        "starttls": {
            "enable": false
        },
        "threadPoolSize": 21,
        "timeout": 30000,
        "writetimeout": 30000
    }
    1 Substitution for ESV placeholder &{esv.email.provider.password}.
    2 Substitution for ESV placeholder &{esv.email.provider.username}.
    3 Substitution for ESV placeholder &{esv.email.provider.from.email}.
    4 Substitution for ESV placeholder &{esv.email.provider.port}.
    5 Substitution for ESV placeholder &{esv.email.provider.use.ssl}.

    The following table summarizes the ESVs that correspond with the above placeholders:

    ESV name ESV type Example value

    esv-email-provider-password

    Secret

    n/a

    esv-email-provider-username

    Variable

    String

    example.user

    esv-email-provider-from-email

    Variable

    String

    example.user@example.com

    esv-email-provider-port

    Variable

    Integer

    465

    esv-email-provider-use-ssl

    Variable

    Boolean

    true

  4. Update the email provider configuration:

    Show request
    $ curl \
    --request PUT 'https://<tenant-env-fqdn>/openidm/config/external.email
    --header 'Authorization: Bearer <access_token>' \(1)
    --header 'Content-Type: application/json' \
    --data-raw '<email-provider-configuration>'(2)
    1 Replace <access-token> with the access token created in step 1.
    2 Replace <email-provider-configuration> with the local copy of the email-provider configuration modified in step 3.
    Show response
    {
        "_id": "external.email",
        "auth": {
            "enable": true,
            "password": "&{esv.email.provider.password}",
            "username": "&{esv.email.provider.username}"
        },
        "connectiontimeout": 30000,
        "debug": false,
        "from": "\"Example User\" <&{esv.email.provider.from.email}>",
        "host": "localhost",
        "port": {
            "$int": "&{esv.email.provider.port}"
        },
        "smtpProperties": [],
        "ssl": {
            "enable": {
                "$bool": "&{esv.email.provider.use.ssl}"
            }
        },
        "starttls": {
            "enable": false
        },
        "threadPoolSize": 20,
        "timeout": 30000,
        "writetimeout": 30000
    }

Configure CORS

This example shows how to configure placeholders in your tenant CORS configuration. Refer to Configure CORS.

  1. Create a session token by authenticating an Identity Cloud tenant administrator username and password. Refer to Get a tenant administrator session token.

  2. Get the CORS configuration:

    Show request
    $ curl \
    --request POST 'https://<tenant-env-fqdn>/am/json/global-config/services/CorsService/?_action=nextdescendents
    --header '<session-cookie-name>: <session-token>' \(1) (2)
    --header 'Accept: application/json' \
    --header 'Accept-API-Version: protocol=2.1,resource=1.0'
    1 Replace <session-cookie-name> with the alphanumeric session cookie name configured for the tenant; for example, 461f95967e609c9.
    2 Replace <session-token> with the session token created in step 1.
    Show response
    {
        "result": [
            {
                "maxAge": 600,
                "exposedHeaders": [],
                "acceptedHeaders": [
                    "accept-api-version",
                    "x-requested-with"
                ],
                "allowCredentials": true,
                "acceptedMethods": [
                    "GET",
                    "POST",
                    "PUT",
                    "DELETE"
                ],
                "acceptedOrigins": [
                    "https://example.org",
                    "https://example.com",
                    "https://openam-example.forgeblocks.com"
                ],
                "enabled": true,
                "_id": "example-cors-config", (1)
                "_type": {
                    "_id": "configuration",
                    "name": "Cors Configuration",
                    "collection": true
                }
            }
        ]
    }
    1 The ID of the CORS configuration; in this example it is example-cors-config.
  3. Create a local copy of the CORS configuration from step 2, then substitute in ESV placeholders:

    {
        "maxAge": 600,
        "exposedHeaders": [],
        "acceptedHeaders": [
            "accept-api-version",
            "x-requested-with"
        ],
        "allowCredentials": true,
        "acceptedMethods": [
            "GET",
            "POST",
            "PUT",
            "DELETE"
        ],
        "acceptedOrigins": {
            "$list": "&{esv.cors.accepted.origins}" (1)
        },
        "enabled": true,
        "_id": "example-cors-config",
        "_type": {
            "_id": "configuration",
            "name": "Cors Configuration",
            "collection": true
        }
    }
    1 Substitution for ESV placeholder &{esv.cors.accepted.origins}.

    The following table summarizes the ESV that corresponds with the above placeholder:

    ESV name ESV type Example value

    esv-cors-accepted-origins

    Variable

    List

    "https://example.org","https://example.com","https://openam-example.forgeblocks.com"

  4. Update the CORS configuration:

    Show request
    curl \
    --request PUT 'https://<tenant-env-fqdn>/am/json/global-config/services/CorsService/configuration/<cors-id>' \(1)
    --header '<session-cookie-name>: <session-token>' \(2) (3)
    --header 'Accept: application/json' \
    --header 'Accept-API-Version: protocol=2.1,resource=1.0' \
    --data-raw '<cors-configuration>'(4)
    1 Replace <cors-id> with the CORS configuration ID you found in step 2; for example, example-cors-config.
    2 Replace <session-cookie-name> with the alphanumeric session cookie name configured for the tenant; for example, 461f95967e609c9.
    3 Replace <session-token> with the session token created in step 1.
    4 Replace <cors-configuration> with the local copy of the CORS configuration modified in step 4.
    Show response
    {
        "_id": "example-cors-settings",
        "_rev": "1594160724",
        "maxAge": 600,
        "exposedHeaders": [],
        "acceptedHeaders": [
            "accept-api-version",
            "x-requested-with"
        ],
        "allowCredentials": true,
        "acceptedMethods": [
            "GET",
            "POST",
            "PUT",
            "DELETE"
        ],
        "acceptedOrigins": {
            "$list": "&{esv.cors.accepted.origins}"
        },
        "enabled": true,
        "_type": {
            "_id": "configuration",
            "name": "Cors Configuration",
            "collection": true
        }
    }

Configure a journey node

This example shows how to configure placeholders in an LDAP decision node, but the approach can be adapted to configure placeholders in any journey node.

  1. Create a session token by authenticating an Identity Cloud tenant administrator username and password. Refer to Get a tenant administrator session token.

  2. Get the configuration of the journey that contains the LDAP decision node so you can extract the ID of the node:

    Show request
    $ curl \
    --request GET 'https://<tenant-env-fqdn>/am/json/realms/root/realms/<realm>/realm-config/authentication/authenticationtrees/trees/<journey-name>' \(1) (2)
    --header '<session-cookie-name>: <session-token>' \(3) (4)
    --header 'Accept: application/json' \
    --header 'Accept-API-Version: protocol=2.1,resource=1.0'
    1 Replace <realm> with the realm that contains the journey that contains the LDAP decision node; for example, alpha.
    2 Replace <journey-name> with the name of the journey that contains the LDAP decision node; for example, UpdatePassword.
    3 Replace <session-cookie-name> with the alphanumeric session cookie name configured for the tenant; for example, 461f95967e609c9.
    4 Replace <session-token> with the session token created in step 1.
    Show response
    {
        "_id": "ldapJourney",
        "_rev": "1341035508",
        "identityResource": "managed/alpha_user",
        "uiConfig": {
            "categories": "[]"
        },
        "entryNodeId": "76e74888-73e1-46e2-aa33-5e4c8b07ccec",
        "nodes": {
            "76e74888-73e1-46e2-aa33-5e4c8b07ccec": {
                "x": 249,
                "y": 171.015625,
                "connections": {
                    "outcome": "c12abfe7-ae71-42e6-a6b3-e8f4d4d05549"
                },
                "nodeType": "PageNode",
                "displayName": "Page Node"
            },
            "2082c1ad-f5ad-4b6d-aada-dd4fff4dc6f3": { (1)
                "x": 510,
                "y": 181.015625,
                "connections": {
                    "CANCELLED": "e301438c-0bd0-429c-ab0c-66126501069a",
                    "EXPIRED": "e301438c-0bd0-429c-ab0c-66126501069a",
                    "FALSE": "e301438c-0bd0-429c-ab0c-66126501069a",
                    "LOCKED": "e301438c-0bd0-429c-ab0c-66126501069a",
                    "TRUE": "70e691a5-1e33-4ac3-a356-e7b6d60d92e0"
                },
                "nodeType": "LdapDecisionNode",
                "displayName": "LDAP Decision"
            }
        },
        "staticNodes": {
            "startNode": {
                "x": 50,
                "y": 250
            },
            "70e691a5-1e33-4ac3-a356-e7b6d60d92e0": {
                "x": 792,
                "y": 181
            },
            "e301438c-0bd0-429c-ab0c-66126501069a": {
                "x": 795,
                "y": 307
            }
        },
        "enabled": true
    }
    1 The ID of the LdapDecisionNode node; in this example, it is 2082c1ad-f5ad-4b6d-aada-dd4fff4dc6f3.
  3. Get the configuration of the LDAP decision node:

    Show request
    $ curl \
    --request GET 'https://<tenant-env-fqdn>/am/json/realms/root/realms/<realm>/realm-config/authentication/authenticationtrees/nodes/LdapDecisionNode/<node-id>' \(1) (2) (3)
    --header '<session-cookie-name>: <session-token>' \(4) (5)
    --header 'Accept: application/json' \
    --header 'Accept-API-Version: protocol=2.1,resource=1.0'
    1 Replace <realm> with the realm that contains the journey that contains the LDAP decision node; for example, alpha.
    2 The node name specified is LdapDecisionNode.
    3 Replace <node-id> with the node ID you found in step 2; for example, 2082c1ad-f5ad-4b6d-aada-dd4fff4dc6f3.
    4 Replace <session-cookie-name> with the alphanumeric session cookie name configured for the tenant; for example, 461f95967e609c9.
    5 Replace <session-token> with the session token created in step 1.
    Show response
    {
        "_id": "2082c1ad-f5ad-4b6d-aada-dd4fff4dc6f3",
        "_rev": "-752122233",
        "searchFilterAttributes": [
            "mail"
        ],
        "userProfileAttribute": "uid",
        "primaryServers": [
            "userstore-0.userstore:1389",
            "userstore-1.userstore:1389",
            "userstore-2.userstore:1389"
        ],
        "ldapConnectionMode": "LDAP",
        "trustAllServerCertificates": false,
        "heartbeatInterval": 10,
        "returnUserDn": true,
        "searchScope": "SUBTREE",
        "heartbeatTimeUnit": "SECONDS",
        "secondaryServers": [],
        "ldapOperationsTimeout": 0,
        "userCreationAttrs": [],
        "minimumPasswordLength": 8,
        "accountSearchBaseDn": [
            "o=example"
        ],
        "adminPassword": null,
        "adminDn": "uid=admin",
        "beheraEnabled": true,
        "_type": {
            "_id": "LdapDecisionNode",
            "name": "LDAP Decision",
            "collection": true
        },
        "_outcomes": [
            {
                "id": "TRUE",
                "displayName": "True"
            },
            {
                "id": "FALSE",
                "displayName": "False"
            },
            {
                "id": "LOCKED",
                "displayName": "Locked"
            },
            {
                "id": "CANCELLED",
                "displayName": "Cancelled"
            },
            {
                "id": "EXPIRED",
                "displayName": "Expired"
            }
        ]
    }
  4. Create a local copy of the node configuration from step 4, then substitute in ESV placeholders:

    {
        "searchFilterAttributes": [
            "mail"
        ],
        "userProfileAttribute": "uid",
        "primaryServers" : {
            "$list": "&{esv.journey.ldap.primary.servers}" (1)
        },
        "ldapConnectionMode": "LDAP",
        "trustAllServerCertificates": false,
        "heartbeatInterval": {
            "$int": "&{esv.journey.ldap.heartbeat.interval}"  (2)
        },
        "returnUserDn": true,
        "searchScope": "SUBTREE",
        "heartbeatTimeUnit": "&{esv.journey.ldap.heartbeat.unit}",  (3)
        "secondaryServers": [],
        "ldapOperationsTimeout": 0,
        "userCreationAttrs": [],
        "minimumPasswordLength": 8,
        "accountSearchBaseDn": [
            "o=example"
        ],
        "adminPassword": {
            "$string": "&{esv.journey.ldap.password}"  (4)
        },
        "adminDn": "&{esv.journey.ldap.username}",  (5)
        "beheraEnabled": {
            "$bool": "&{esv.journey.ldap.behera.enabled}"  (6)
        },
        "_type": {
            "_id": "LdapDecisionNode",
            "name": "LDAP Decision",
            "collection": true
        },
        "_outcomes": [
            {
                "id": "TRUE",
                "displayName": "True"
            },
            {
                "id": "FALSE",
                "displayName": "False"
            },
            {
                "id": "LOCKED",
                "displayName": "Locked"
            },
            {
                "id": "CANCELLED",
                "displayName": "Cancelled"
            },
            {
                "id": "EXPIRED",
                "displayName": "Expired"
            }
        ]
    }
    1 Substitution for ESV placeholder &{esv.journey.ldap.primary.servers}.
    2 Substitution for ESV placeholder &{esv.journey.ldap.heartbeat.interval}.
    3 Substitution for ESV placeholder &{esv.journey.ldap.heartbeat.unit}.
    4 Substitution for ESV placeholder &{esv.journey.ldap.password}.
    5 Substitution for ESV placeholder &{esv.journey.ldap.username}.
    6 Substitution for ESV placeholder &{esv.journey.ldap.behera.enabled}.

    The following table summarizes the ESVs that correspond with the above placeholders:

    ESV name ESV type Example value

    esv-journey-ldap-primary-servers

    Variable

    List

    userstore-0.userstore:1389,userstore-1.userstore:1389,userstore-2.userstore:1389

    esv-journey-ldap-heartbeat-interval

    Variable

    Integer

    10

    esv-journey-ldap-heartbeat-unit

    Variable

    String

    SECONDS

    esv-journey-ldap-password

    Secret

    n/a

    changeit

    esv-journey-ldap-username

    Variable

    String

    uid=myadmin

    esv-journey-ldap-behera-enabled

    Variable

    Boolean

    false

  5. Update the configuration of the LDAP decision node:

    Show request
    curl \
    --request PUT 'https://<tenant-env-fqdn>/am/json/realms/root/realms/<realm>/realm-config/authentication/authenticationtrees/nodes/LdapDecisionNode/<node-id>' \ (1) (2) (3)
    --header '<session-cookie-name>: <session-token>' \ (4) (5)
    --header 'Accept: application/json' \
    --header 'Accept-API-Version: protocol=2.1,resource=1.0' \
    --data-raw '<node-configuration>' (6)
    1 Replace <realm> with the realm that contains the journey that contains the LDAP decision node; for example, alpha.
    2 The node name specified is LdapDecisionNode.
    3 Replace <node-id> with the node ID you found in step 2; for example, 2082c1ad-f5ad-4b6d-aada-dd4fff4dc6f3.
    4 Replace <session-cookie-name> with the alphanumeric session cookie name configured for the tenant; for example, 461f95967e609c9.
    5 Replace <session-token> with the session token created in step 1.
    6 Replace <node-configuration> with the local copy of the node configuration modified in step 5.
    Show response
    {
        "_id": "2082c1ad-f5ad-4b6d-aada-dd4fff4dc6f3",
        "_rev": "1359037709",
        "searchFilterAttributes": [
            "mail"
        ],
        "userProfileAttribute": "uid",
        "primaryServers": {
            "$list": "&{esv.journey.ldap.servers}"
        },
        "ldapConnectionMode": "LDAP",
        "trustAllServerCertificates": false,
        "heartbeatInterval": {
            "$int": "&{esv.journey.ldap.heartbeat.interval}"
        },
        "returnUserDn": true,
        "searchScope": "SUBTREE",
        "heartbeatTimeUnit": "&{esv.journey.ldap.heartbeat.unit}",
        "secondaryServers": [],
        "ldapOperationsTimeout": 0,
        "userCreationAttrs": [],
        "minimumPasswordLength": 8,
        "accountSearchBaseDn": [
            "o=example"
        ],
        "adminPassword": {
            "$string": "&{esv.journey.ldap.password}"
        },
        "adminDn": "&{esv.journey.ldap.username}",
        "beheraEnabled": {
            "$bool": "&{esv.journey.ldap.behera.enabled}"
        },
        "_type": {
            "_id": "LdapDecisionNode",
            "name": "LDAP Decision",
            "collection": true
        },
        "_outcomes": [
            {
                "id": "TRUE",
                "displayName": "True"
            },
            {
                "id": "FALSE",
                "displayName": "False"
            },
            {
                "id": "LOCKED",
                "displayName": "Locked"
            },
            {
                "id": "CANCELLED",
                "displayName": "Cancelled"
            },
            {
                "id": "EXPIRED",
                "displayName": "Expired"
            }
        ]
    }
Copyright © 2010-2022 ForgeRock, all rights reserved.