Update Identity Store

• URL:https://<config-url>/updateIdentityStore(POST only)
  
• Required Capability:Default administrator role | Security and infrastructure privilege
• Version Introduced:10.2.1

Description

This operation changes the identity provider and group store configuration for ArcGIS Enterprise portal. When Portal for ArcGIS is first installed, Enterprise portal is configured support token-based authentication and built-in groups using the built-in identity store. This configuration can be modified to enable Enterprise portal to connect to your enterprise authentication mechanism and group store by changing the type of provider and modifying the security configuration properties appropriately. For more information, see the Example usage section below.

Request parameters

Parameters	Details
securityConfig	JSON that specifies the properties being changed for the Enterprise portal identity provider and group store.
f	The response format. The default is html. Values: html | json | pjson

securityConfig properties

Properties	Details
userPassword	The password for the domain account. Example "userPassword": "secret"
isPasswordEncrypted	Indicates if the userPassword property is an encrypted password or plain text. If the property is false, the API will encrypt the password automatically. Values: true | false Example "isPasswordEncrypted": "false"
user	A user account with at least read permissions to look up the email addresses and user names of users in your organization. If possible, use an account whose password does not expire. Examples //Windows Active Directory "user": "mydomain\\winaccount" //LDAP example "user": "uid=admin,ou=system"
userFullnameAttribute	The attribute in Windows Active Directory or LDAP that contains the full name of the users. Example "userFullnameAttribute": "cn"
ldapURLForUsers	The URL to your LDAP that points to the user accounts. The URL to your LDAP will need to be provided by your LDAP administrator. Although both LDAP and LDAPS URLs are supported, LDAPS is highly recommended to ensure encrypted network traffic between Enterprise portal and LDAP servers. If LDAPS is not available, an LDAP URL can be used but traffic will be sent in clear-text. This property is not applicable when configuring Windows Active Directory. Example "ldapURLForUsers": "ldaps://bar2:10636/ou=users,ou=ags,dc=example,dc=com"
ldapURLForRoles	The URL to your LDAP that points to the roles. The URL to your LDAP will need to be provided by your LDAP administrator. Although both LDAP and LDAPS URLs are supported, LDAPS is highly recommended to ensure encrypted network traffic between Enterprise portal and LDAP servers. If LDAPS is not available, an LDAP URL can be used but traffic will be sent in clear-text. This property is not applicable when configuring Windows Active Directory. Example "ldapURLForRoles": "ldaps://bar2:10636/ou=roles,ou=ags,dc=example,dc=com"
userEmailAttribute	The attribute in Windows Active Directory or LDAP that contains the email addresses of the users. Example "userEmailAttribute": "mail"
usernameAttribute	The LDAP attribute of the user entry that is to be treated as the user name. This property is not applicable when configuring Windows Active Directory. Example "usernameAttribute": "cn"
userSearchAttribute	When using LDAP and PKI to secure access to Enterprise portal, you'll need to specify the value for userSearchAttribute. The userSearchAttribute is the value of the Subject parameter of the PKI certificate. If your organization uses another attribute in the PKI certificate, such as email, you must update the userSearchAttribute to match the Subject parameter in the PKI certificate.
caseSensitive	In the rare case where your Windows Active Directory is configured to be case sensitive, set this property to true. If your LDAP is configured to be case insensitive, set parameter to false. Example "caseSensitive": "true"
followReferrals	Introduced at 10.6. This property controls whether LDAP referrals are followed when Enterprise portal queries domain controllers for user or group information. By default, this is set to true. Example "followReferrals": "true"
domainControllerAddress	The IP address of the domain controller to be used by Enterprise portal. You'll need to specify the domain controller if your Active Directory deployment includes multiple domain controllers, but not all domain controllers are configured as global catalog servers. Starting in 10.6, multiple IP addresses can be listed, and IPv6 addresses are supported.
domainControllerMapping	Introduced at 10.6. The IP address of the domain controller for specific domains. Multiple domains can be listed along with multiple IP addresses for each domain. The syntax is as follows: domain_name=ip_address, ip_address; domain_name=ip_address, ip_address. The IP addresses can be either IPv4 or IPv6.
refreshUserMembershipDuringLoginEnabled	This property is only applicable when configuring the group store. By default, each time an enterprise user signs in to Enterprise portal, the groups are refreshed automatically. If this behavior adversely affects login performance, it can be disabled by setting the value of this parameter to false. The default value of this parameter is true. Example "refreshUserMembershipDuringLoginEnabled": "true"
membershipRefreshIntervalHours	This property is only applicable when configuring the group store. Enterprise portal periodically refreshes all user memberships. This parameter determines the interval at which the refresh repeats. The default value is 24 hours.
membershipRefreshStartTime	This property is only applicable when configuring the group store. This parameter determines the start time of the periodic refresh. The format is a 24 hour clock string. The default start time is midnight ("00:00"). The refresh operation may be computationally expensive, so it is recommended that the refresh time not be during business hours when Enterprise portal may be busy.
checkForMultipleUsernameFormats	This property is only applicable when configuring the user store with Windows Active Directory and using portal-tier authentication to sign in. By default, checkForMultipleUsernameFormats is false and any enterprise user that signs into Enterprise portal will need to use the following username formats: DOMAIN\username or username@DOMAIN. If checkForMultipleUsernameFormats is true, Enterprise portal will attempt to use different username formats if the initial attempt fails (includes username and [e-mail]). Example "checkForMultipleUsernameFormats": "true"
useSSLOnly	This property applies to the Windows Active Directory only. It enforces encrypted communication between Enterprise portal and Active Directory. When the property is set to true, if encrypted communication fails, Enterprise portal does not attempt to communicate without encryption. This property is set to false by default. Example "useSSLOnly": "false"
userGivenNameAttribute	Introduced at 10.8, this property applies to both Windows Active Directory and LDAP. This property can be used to return the actual first name value stored in the Windows Active Directory or LDAP identity store.
userSurnameAttribute	Introduced at 10.8, this property applies to both Windows Active Directory and LDAP. This property can be used to return the actual last name value stored in the Windows Active Directory or LDAP identity store.
saslAuthenticationScheme	Introduced at 10.9. Defines the SASL authentication scheme used by Portal for ArcGIS to connect to the domain controllers via LDAP. In 10.9, the only SASL authentication scheme that is supported is GSSAPI. Example "saslAuthenticationScheme": "GSSAPI"
krb5ConfigFilePath	Introduced at 10.9. Defines the path to the Kerberos configuration text file that is needed when utilizing the GSSAPI SASL authentication scheme. This file needs to reside in a location that the Portal for ArcGIS service account has read-access to. Example "krb5ConfigFilePath": "C:\\arcgisportal\\krb5.conf" Or "krb5ConfigFilePath": "/data/arcgis/krb5.conf" This configuration file is standard for Kerberos and should include default configuration settings and information on one or more Kerberos domain controllers for each Kerberos realm. An example is shown below: [libdefaults] dns_lookup_realm = false ticket_lifetime = 24h renew_lifetime = 7d forwardable = true rdns = false default_ccache_name = KEYRING:persistent:%{uid} dns_lookup_kdc = true default_realm = EXAMPLE.COM default_checksum = rsa-md5 [realms] EXAMPLE.COM = { kdc = domaincontroller.example.com admin_server = domaincontroller.example.com } [domain_realm] example.com = EXAMPLE.COM .example.com = EXAMPLE.COM

Example usage

Below is a sample request URL for updateIdentityStore:

POST /webadaptor/portaladmin/security/config/updateIdentityStore HTTP/1.1
Host: machine.domain.com
Content-Type: application/x-www-form-urlencoded
Content-Length: []

securityConfig={
  "type": "LDAP",
  "properties": {
    "userPassword": "secret",
    "isPasswordEncrypted": "false",
    "user": "uid=admin,ou=system",
    "userFullnameAttribute": "displayName",
    "userGivenNameAttribute": "givenName",
    "userSurnameAttribute": "cn",
    "ldapURLForUsers": "ldaps://ldapserver:10636/ou=users,ou=ags,dc=example,dc=com",
    "userEmailAttribute": "mail",
    "usernameAttribute": "uid",
    "caseSensitive": "false",
    "userSearchAttribute": "cn", 
  }
}&f=json

The following examples can be used to update Enterprise portal's identity and group store to:

• Configure enterprise users (Windows Active Directory or LDAP) and built-in groups
• Configure enterprise users and enterprise groups (Windows Active Directory or LDAP)
• Configure built-in Enterprise portal users and groups

Configure enterprise users and built-in groups

In the Update Identity Store page, update the User store configuration (in JSON format) text box with the following information from your organization's enterprise identity store for Windows Active Directory, LDAPS, or LDAP:

Windows Active Directory example

In most cases, you will only need to alter values for the user and userPassword parameters.

Although you type the password in clear text, it will be encrypted when stored in Enterprise portal's configuration directory or viewed. The account you use for the user parameter only needs permissions to look up the email address and full name of Windows accounts on the network. If possible, use an account whose password does not expire.

In the rare case where Active Directory is configured to be case sensitive, set the caseSensitive parameter to true.

{
  "type": "WINDOWS",
  "properties": {
    "userPassword": "secret",
    "isPasswordEncrypted": "false",
    "user": "mydomain\\winaccount",
    "userFullnameAttribute": "displayName",
    "userEmailAttribute": "mail",
    "userGivenNameAttribute": "givenName",
    "userSurnameAttribute": "cn",
    "caseSensitive": "false"
  }
}

After updating User store configuration (in JSON format), delete any information in the Group store configuration (in JSON format) text box. This will force Enterprise portal to use built-in groups.

{}

LDAPS example (highly recommended)

Although both LDAP and LDAPS URLs are supported, LDAPS is highly recommended to ensure encrypted network traffic between Enterprise portal and LDAP servers. If LDAPS is not available, an LDAP URL can be used but traffic will be sent in clear-text.

{
  "type": "LDAP",
  "properties": {
    "userPassword": "secret",
    "isPasswordEncrypted": "false",
    "user": "uid=admin,ou=system",
    "userFullnameAttribute": "displayName",
    "userGivenNameAttribute": "givenName",
    "userSurnameAttribute": "cn",
    "ldapURLForUsers": "ldaps://ldapserver:10636/ou=users,ou=ags,dc=example,dc=com",
    "userEmailAttribute": "mail",
    "usernameAttribute": "uid",
    "caseSensitive": "false",
    "userSearchAttribute": "cn", 
  }
}

After updating User store configuration (in JSON format), delete any information in the Group store configuration (in JSON format) text box. This will force Enterprise portal to use built-in groups.

{}

LDAP example

In most cases, you will only need to alter values for the user, userPassword, and ldapURLForUsers parameters. The URL to your LDAP will need to be provided by your LDAP administrator.

If your LDAP is configured to be case insensitive, set the caseSensitive parameter to false.

The account you use for the user parameter needs permissions to look up the email address and user names of users in your organization. Although you type the password in clear text, it will be encrypted when stored in Enterprise portal's configuration directory or viewed.

{
  "type": "LDAP",
  "properties": {
    "userPassword": "secret",
    "isPasswordEncrypted": "false",
    "user": "uid=admin,ou=system",
    "userFullnameAttribute": "displayName",
    "userGivenNameAttribute": "givenName",
    "userSurnameAttribute": "cn",
    "ldapURLForUsers": "ldap://ldapserver:10636/ou=users,ou=ags,dc=example,dc=com",
    "userEmailAttribute": "mail",
    "usernameAttribute": "uid",
    "caseSensitive": "false",
    "userSearchAttribute": "cn", 
  }
}

In the above example, the LDAP URL refers to users within a specific OU (ou=users). If users exist in multiple OUs, the LDAP URL can point to a higher level OU or even the root level if needed. In that case, the URL would instead look like this:

"ldapURLForUsers": "ldaps://ldapserver:10636/dc=example,dc=com

After updating User store configuration (in JSON format), delete any information in the Group store configuration (in JSON format) text box. This will force Enterprise portal to use built-in groups.

{}

Configure enterprise users and enterprise groups

In the Update Identity Store page, update the User store configuration (in JSON format) text box with the following user information from your organization's enterprise identity store for Windows Active Directory, LDAPS, or LDAP:

Windows Active Directory example

In most cases, you will only need to alter values for the user and userPassword parameters. Although you type the password in clear text, it will be encrypted when stored in Enterprise portal's configuration directory or viewed. The account you use for the userparameter only needs permissions to look up the email address and full name of Windows accounts on the network. If possible, use an account whose password does not expire.

In the rare case where Active Directory is configured to be case sensitive, set the caseSensitive parameter to true.

{
  "type": "WINDOWS",
  "properties": {
    "userPassword": "secret",
    "isPasswordEncrypted": "false",
    "user": "mydomain\\winaccount",
    "userFullnameAttribute": "displayName",
    "userEmailAttribute": "mail",
    "userGivenNameAttribute": "givenName",
    "userSurnameAttribute": "cn",
    "caseSensitive": "false"
  }
}

After updating User store configuration (in JSON format), update the Group store configuration (in JSON format) text box with the following group information from your organization's enterprise identity store.

In most cases, you will only need to alter values for the user and userPassword parameters. Although you type the password in clear text, it will be encrypted when stored in Enterprise portal's configuration directory or viewed. The account you use for the user parameter only needs permissions to look up the names of Windowsgroups on the network. If possible, use an account whose password does not expire.

{
  "type": "WINDOWS",
  "properties": {
    "isPasswordEncrypted": "false",
    "userPassword": "secret",
    "user": "mydomain\\winaccount"
  }
}

LDAPS example (highly recommended)

Although both LDAP and LDAPS URLs are supported, LDAPS is highly recommended to ensure encrypted network traffic between Enterprise portal and LDAP server. If LDAPS is not available, an LDAP URL can be used but traffic will be sent in clear-text.

{
  "type": "LDAP",
  "properties": {
    "userPassword": "secret",
    "isPasswordEncrypted": "false",
    "user": "uid=admin,ou=system",
    "userFullnameAttribute": "displayName",
    "userGivenNameAttribute": "givenName",
    "userSurnameAttribute": "cn",
    "ldapURLForUsers": "ldaps://ldapserver:10636/ou=users,ou=ags,dc=example,dc=com",
    "userEmailAttribute": "mail",
    "usernameAttribute": "uid",
    "caseSensitive": "false",
    "userSearchAttribute": "cn", 
  }
}

After updating User store configuration (in JSON format), update the Group store configuration (in JSON format) text box with the following group information from your organization's enterprise identity store.

Although both LDAP and LDAPS URLs are supported, LDAPS is highly recommended to ensure encrypted network traffic between Enterprise portal and LDAP servers. If LDAPS is not available, an LDAP URL can be used but traffic will be sent in clear-text.

{
  "type": "LDAP",
  "properties": {
    "userPassword": "secret",
    "isPasswordEncrypted": "false",
    "user": "uid=admin,ou=system",
    "ldapURLForUsers": "ldaps://ldapserver:10636/ou=users,ou=ags,dc=example,dc=com",
    "ldapURLForRoles": "ldaps://ldapserver:10636/ou=users,ou=ags,dc=example,dc=com",
    "userEmailAttribute": "mail",
    "usernameAttribute": "cn",
    "caseSensitive": "false",
    "meberAttributeInRoles": "member",
    "rolenameAttribute": "cn"
  }
}

LDAP example

In most cases, you will only need to alter values for the user, userPassword, and ldapURLForUsers parameters. The URL to your LDAP will need to be provided by your LDAP administrator. The account you use for the user parameter needs permissions to look up the email address and user names of users in your organization.

Although you type the password in clear text, it will be encrypted when stored in Enterprise portal's configuration directory or viewed.

If your LDAP is configured to be case insensitive, set the caseSensitive parameter to false.

{
  "type": "LDAP",
  "properties": {
    "userPassword": "secret",
    "isPasswordEncrypted": "false",
    "user": "uid=admin,ou=system",
    "userFullnameAttribute": "displayName",
    "userGivenNameAttribute": "givenName",
    "userSurnameAttribute": "sn",
    "ldapURLForUsers": "ldap://ldapserver:10636/ou=users,ou=ags,dc=example,dc=com",
    "userEmailAttribute": "mail",
    "usernameAttribute": "cn",
    "caseSensitive": "false",
    "userSearchAttribute": "cn" 
  }
}

In the above example, the LDAP URL refers to users within a specific OU (ou=users). If users exist in multiple OUs, the LDAP URL can point to a higher level OU or even the root level if needed. In that case, the URL would instead look like this:

"ldapURLForUsers": "ldaps://bar2:10636/dc=example,dc=com"

After updating User store configuration (in JSON format), update the Group store configuration (in JSON format) text box with the following group information from your organization's enterprise identity store.

{
  "type": "LDAP",
  "properties": {
    "userPassword": "secret",
    "isPasswordEncrypted": "false",
    "user": "uid=admin,ou=system",
    "ldapURLForUsers": "ldap://ldapserver:10636/ou=users,ou=ags,dc=example,dc=com",
    "ldapURLForRoles": "ldap://ldapserver:10636/ou=users,ou=ags,dc=example,dc=com",
    "userEmailAttribute": "mail",
    "usernameAttribute": "cn",
    "caseSensitive": "false",
    "memberAttributeInRoles": "member",
    "rolenameAttribute": "cn" 
  }
}

Configure built-in Enterprise portal users and groups

In the Update Identity Store page, delete any information in the User store configuration (in JSON format) and Group store configuration (in JSON format) text boxes:

User store configuration

{}

Group store configuration

{}