PingAM

Passive install over REST

Use the REST API to install AM with minimal user interaction. The AM server must be deployed and running but not yet configured.

Send a POST request to the /config/configurator endpoint with the configuration properties. You can find a list of valid properties in Configuration properties.

Examples

These examples assume you have a DS instance up and running, and that the instance has been installed as a configuration store, identity store, and CTS store.

You can find information on setting up an evaluation DS server that stores all three data types in Step 2. Prepare your datastore.

Install a standalone server

$ curl \
--request POST \
--header "Content-Type: application/x-www-form-urlencoded" \
--data-urlencode "SERVER_URL=https://am.example.com:8443" \
--data-urlencode "DEPLOYMENT_URI=/am" \
--data-urlencode "BASE_DIR=$HOME/am" \
--data-urlencode "locale=en_US" \
--data-urlencode "PLATFORM_LOCALE=en_US" \
--data-urlencode "ADMIN_PWD=Ch4ng31t" \
--data-urlencode "ADMIN_CONFIRM_PWD=Ch4ng31t" \
--data-urlencode "COOKIE_DOMAIN=am.example.com" \
--data-urlencode "acceptLicense=true" \
--data-urlencode "DATA_STORE=dirServer" \
--data-urlencode "DIRECTORY_SSL=SSL" \
--data-urlencode "DIRECTORY_SERVER=ds.example.com" \
--data-urlencode "DIRECTORY_PORT=1636" \
--data-urlencode "DIRECTORY_ADMIN_PORT=4444" \
--data-urlencode "ROOT_SUFFIX=ou=am-config" \
--data-urlencode "DS_DIRMGRDN=uid=am-config,ou=admins,ou=am-config" \
--data-urlencode "DS_DIRMGRPASSWD=Ch4ng31t" \
--data-urlencode "USERSTORE_TYPE=LDAPv3ForOpenDS" \
--data-urlencode "USERSTORE_SSL=SSL" \
--data-urlencode "USERSTORE_HOST=ds.example.com" \
--data-urlencode "USERSTORE_PORT=1636" \
--data-urlencode "USERSTORE_SUFFIX=ou=identities" \
--data-urlencode "USERSTORE_MGRDN=uid=am-identity-bind-account,ou=admins,ou=identities" \
--data-urlencode "USERSTORE_PASSWD=Ch4ng31t" \
"https://am.example.com:8443/am/config/configurator"

Configuration complete!

Install two servers in a site configuration

Install the first server. The REST call is the same as for a standalone server install, with the addition of the AM_ENC_KEY property and the site properties (LB_SITE_NAME and LB_PRIMARY_URL):

$ curl \
--request POST \
--header "Content-Type: application/x-www-form-urlencoded" \
--data-urlencode "SERVER_URL=https://am.example.com:8443" \
--data-urlencode "DEPLOYMENT_URI=/am" \
--data-urlencode "BASE_DIR=$HOME/am" \
--data-urlencode "locale=en_US" \
--data-urlencode "PLATFORM_LOCALE=en_US" \
--data-urlencode "AM_ENC_KEY=O6QWwHPO4os+zEz3Nqn/2daAYWyiFE32" \
--data-urlencode "ADMIN_PWD=Ch4ng31t" \
--data-urlencode "ADMIN_CONFIRM_PWD=Ch4ng31t" \
--data-urlencode "COOKIE_DOMAIN=am.example.com" \
--data-urlencode "acceptLicense=true" \
--data-urlencode "DATA_STORE=dirServer" \
--data-urlencode "DIRECTORY_SSL=SSL" \
--data-urlencode "DIRECTORY_SERVER=ds.example.com" \
--data-urlencode "DIRECTORY_PORT=1636" \
--data-urlencode "DIRECTORY_ADMIN_PORT=4444" \
--data-urlencode "ROOT_SUFFIX=ou=am-config" \
--data-urlencode "DS_DIRMGRDN=uid=am-config,ou=admins,ou=am-config" \
--data-urlencode "DS_DIRMGRPASSWD=Ch4ng31t" \
--data-urlencode "USERSTORE_TYPE=LDAPv3ForOpenDS" \
--data-urlencode "USERSTORE_SSL=SSL" \
--data-urlencode "USERSTORE_HOST=ds.example.com" \
--data-urlencode "USERSTORE_PORT=1636" \
--data-urlencode "USERSTORE_SUFFIX=ou=identities" \
--data-urlencode "USERSTORE_MGRDN=uid=am-identity-bind-account,ou=admins,ou=identities" \
--data-urlencode "USERSTORE_PASSWD=Ch4ng31t" \
--data-urlencode "LB_SITE_NAME=lb" \
--data-urlencode "LB_PRIMARY_URL=https://lb.example.com:8443/am" \
"https://am.example.com:8443/am/config/configurator"

Configuration complete!

Install the second server. Make sure the AM_ENC_KEY and site properties match those used for the first server:

$ curl \
--request POST \
--header "Content-Type: application/x-www-form-urlencoded" \
--data-urlencode "SERVER_URL=https://am2.example.com:8443" \
--data-urlencode "DEPLOYMENT_URI=/am" \
--data-urlencode "BASE_DIR=$HOME/am" \
--data-urlencode "locale=en_US" \
--data-urlencode "PLATFORM_LOCALE=en_US" \
--data-urlencode "AM_ENC_KEY=O6QWwHPO4os+zEz3Nqn/2daAYWyiFE32" \
--data-urlencode "ADMIN_PWD=Ch4ng31t" \
--data-urlencode "ADMIN_CONFIRM_PWD=Ch4ng31t" \
--data-urlencode "COOKIE_DOMAIN=am.example.com" \
--data-urlencode "acceptLicense=true" \
--data-urlencode "DATA_STORE=dirServer" \
--data-urlencode "DIRECTORY_SSL=SSL" \
--data-urlencode "DIRECTORY_SERVER=ds.example.com" \
--data-urlencode "DIRECTORY_PORT=1636" \
--data-urlencode "DIRECTORY_ADMIN_PORT=4444" \
--data-urlencode "ROOT_SUFFIX=ou=am-config" \
--data-urlencode "DS_DIRMGRDN=uid=am-config,ou=admins,ou=am-config" \
--data-urlencode "DS_DIRMGRPASSWD=Ch4ng31t" \
--data-urlencode "USERSTORE_TYPE=LDAPv3ForOpenDS" \
--data-urlencode "USERSTORE_SSL=SSL" \
--data-urlencode "USERSTORE_HOST=ds.example.com" \
--data-urlencode "USERSTORE_PORT=1636" \
--data-urlencode "USERSTORE_SUFFIX=ou=identities" \
--data-urlencode "USERSTORE_MGRDN=uid=am-identity-bind-account,ou=admins,ou=identities" \
--data-urlencode "USERSTORE_PASSWD=Ch4ng31t" \
--data-urlencode "LB_SITE_NAME=lb" \
--data-urlencode "LB_PRIMARY_URL=https://lb.example.com:8443/am" \
"https://am2.example.com:8443/am/config/configurator"

Configuration complete!

Configuration properties

The following table lists the configuration properties that you can set when installing AM over REST.

Property name Description Example values

SERVER_URL

The protocol, fully qualified domain name, and port to use for the AM server instance.

https://am.example.com:8443

DEPLOYMENT_URI

The deployment URI to use for the AM server instance.

/am

BASE_DIR

The configuration directory where AM stores files.

$HOME/am

locale

The user locale.

en_GB

PLATFORM_LOCALE

The locale of the AM server instance.

en_US

AM_ENC_KEY

The password encryption key, which must be the same on all servers in a site configuration.

If this property is excluded, AM generates a random password encryption key on install that you can view in the AM admin UI, under Deployment > Servers > server name > Security.

O6QWwHPO4os+zEz3Nqn/2daAYWyiFE32

ADMIN_PWD

The password of the AM administrator user amAdmin, which must be at least 8 characters in length and must be the same on all servers in a site configuration.

Ch4ng31t

ADMIN_CONFIRM_PWD

Confirmation of the amAdmin password.

Ch4ng31t

COOKIE_DOMAIN

The name of the trusted DNS domain AM returns to a browser when it grants a session ID to a user.

am.example.com

acceptLicense

Set this to true to auto-accept the software license agreement, which suppresses the display of the license acceptance page during the install.

true

DATA_STORE

Set this to dirServer to indicate an external PingDS directory server for the configuration store.

dirServer

DIRECTORY_SSL

Set this to SSL to use LDAP with SSL. DS is configured for LDAPS by default. To use LDAP without SSL, set this to SIMPLE.

SSL

DIRECTORY_SERVER

The fully qualified domain name of the configuration store directory server host.

ds.example.com

DIRECTORY_PORT

The LDAPS or LDAP port number for the configuration store directory server.

1636

DIRECTORY_ADMIN_PORT

The administration port number for the configuration store directory server.

4444

ROOT_SUFFIX

The root suffix distinguished name (DN) for the configuration store.

ou=am-config

DS_DIRMGRDN

The bind DN of the configuration store user account.

uid=am-config,ou=admins,ou=am-config

DS_DIRMGRPASSWD

The password for the bind DN.

Ch4ng31t

USERSTORE_TYPE

The type of directory server to use for the identity store.

Possible values are:

  • LDAPv3ForAD: Active Directory with host and port settings

  • LDAPv3ForADDC: Active Directory with domain name setting

    If you use this type, you must also set the USERSTORE_DOMAINNAME property.

  • LDAPv3ForADAM: Active Directory Lightweight Directory Services (AD LDS)

  • LDAPv3ForForgeRockIAM: PingDS

    Only use this type if DS is the shared identity store in a Ping Identity Platform deployment. Otherwise, use LDAPv3ForOpenDS.

  • LDAPv3ForOpenDS: PingDS

  • LDAPv3ForPingDirectory: PingDirectory

LDAPv3ForOpenDS

USERSTORE_DOMAINNAME

If USERSTORE_TYPE is LDAPv3ForADDC, set this to the Active Directory Domain Name. Then only set the USERSTORE_SSL, USERSTORE_MGRDN, and USERSTORE_PASSWD properties to let Active Directory use DNS to retrieve service locations. Otherwise, don’t set this property.

ad.example.com

USERSTORE_SSL

Set this to SSL to use LDAP with SSL. DS is configured for LDAPS by default. To use LDAP without SSL, set this to SIMPLE.

SSL

USERSTORE_HOST

The fully qualified domain name of the identity store directory server.

ds.example.com

USERSTORE_PORT

The LDAPS or LDAP port number for the identity store directory server.

1636

USERSTORE_SUFFIX

The root suffix DN for the identity store.

ou=identities

USERSTORE_MGRDN

The bind DN of the identity store user account.

uid=am-identity-bind-account,ou=admins,ou=identities

USERSTORE_PASSWD

The password for the bind DN.

Ch4ng31t

LB_SITE_NAME

The name of the AM site. Required when installing a server as part of a site configuration.

lb

LB_PRIMARY_URL

The load balancer URL for the site. Required when installing a server as part of a site configuration.

https://lb.example.com:8443/am