Update Identity Store

URL:
https://<root>/security/config/updateIdentityStore
Methods:
POST
Required Capability:
Access allowed with the "Security and Infrastructure" privilege
Version Introduced:
10.2.1

Description

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

Request parameters

ParametersDetails

userStoreConfig

JSON that specifies the properties being changed for the identity provider.

groupStoreConfig

JSON that specifies the properties being changed for the group store.

f

The response format. The default is html.

Values: html | json | pjson

Identity and group store properties

PropertiesDetails

type

Specifies the authentication mechanisms for the identity store and group store.

Values: BUILTIN | WINDOWS | LDAP

userPassword

The password for the domain account.

Example
Use dark colors for code blocksCopy
1
"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

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.

Example
Use dark colors for code blocksCopy
1
2
3
4
5
//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
Use dark colors for code blocksCopy
1
"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
Use dark colors for code blocksCopy
1
"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 ArcGIS Enterprise 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
Use dark colors for code blocksCopy
1
"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
Use dark colors for code blocksCopy
1
"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
Use dark colors for code blocksCopy
1
"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 this property to false.

Values: true | false

followReferrals

This property controls whether LDAP referrals are followed when ArcGIS Enterprise queries domain controllers for user or group information. By default, this is set to true.

Values: true | false

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. Multiple IP addresses can be listed and IPv6 addresses are supported.

domainControllerMapping

The IP address of the domain controller for specific domains. Multiple domains can be listed along with multiple IP addresses for each domain. The IP addresses can be either IPv4 or IPv6.

Example
Use dark colors for code blocksCopy
1
"domainControllerMapping": "domain_name=ip_address, ip_address; domain_name=ip_address, ip_address"

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 property to false. The default value of this property is true.

Values: true | false

membershipRefreshIntervalHours

This property is only applicable when configuring the group store. ArcGIS Enterprise periodically refreshes all user memberships. This property determines the interval at which the refresh repeats. The default value is 24 hours.

membershipRefreshStartTime

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. This property is only applicable when configuring the group store.

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 the organization will need to use the following username formats: DOMAIN\username or username@DOMAIN. If checkForMultipleUsernameFormats is true, ArcGIS Enterprise will attempt to use different username formats if the initial attempt fails (includes username and username@DOMAIN.com).

Values: true | false

useSSLOnly

This property applies to the Windows Active Directory only. It enforces encrypted communication between ArcGIS Enterprise and Active Directory. When the property is set to true, if encrypted communication fails, ArcGIS Enterprise does not attempt to communicate without encryption. This property is set to false by default.

Values: true | 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
Use dark colors for code blocksCopy
1
"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
Use dark colors for code blocksCopy
1
2
3
4
5
//Example one
"krb5ConfigFilePath": "C:\\arcgisportal\\krb5.conf"

//Example two
"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:

Example
Use dark colors for code blocksCopy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
[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

The following is a sample POST request for the updateIdentityStore operation:

Use dark colors for code blocksCopy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
POST /webadaptor/portaladmin/security/config/updateIdentityStore HTTP/1.1
Host: machine.domain.com
Content-Type: application/x-www-form-urlencoded
Content-Length: []

userStoreConfig={
  "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",
  }
}&groupStoreConfig={}&f=pjson

Configuration examples

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

Configure enterprise users and built-in groups

Windows Active Directory example

The codeblock below specifies the input JSON object for the userStoreConfig parameter:

Use dark colors for code blocksCopy
1
2
3
4
5
6
7
8
9
10
11
12
13
{
  "type": "WINDOWS",
  "properties": {
    "userPassword": "secret",
    "isPasswordEncrypted": "false",
    "user": "mydomain\\winaccount",
    "userFullnameAttribute": "displayName",
    "userEmailAttribute": "mail",
    "userGivenNameAttribute": "givenName",
    "userSurnameAttribute": "cn",
    "caseSensitive": "false"
  }
}

In most cases, you will only need to alter values for the user and userPassword properties. In the rare case where Windows Active Directory is configured to be case sensitive, set the caseSensitive property to true.

Update the groupStoreConfig parameter to include an empty JSON object. This will force ArcGIS Enterprise to use built-in groups.

The codeblock below specifies the input JSON object for the userStoreConfig parameter:

Use dark colors for code blocksCopy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
{
  "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",
  }
}

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.

Update the groupStoreConfig parameter to include an empty JSON object. This will force ArcGIS Enterprise to use built-in groups.

LDAP example

The codeblock below specifies the input JSON object for the userStoreConfig parameter:

Use dark colors for code blocksCopy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
{
  "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 most cases, you will only need to alter values for the user, userPassword, and ldapURLForUsers properties. 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 property to false. The account you use for the user property needs permissions to look up the email address and user names of users in your organization.

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:

Use dark colors for code blocksCopy
1
"ldapURLForUsers": "ldaps://ldapserver:10636/dc=example,dc=com

Update the groupStoreConfig parameter to include an empty JSON object. This will force ArcGIS Enterprise to use built-in groups.

Configure enterprise users and enterprise groups

Windows Active Directory example

The codeblock below specifies the input JSON object for the userStoreConfig parameter:

Use dark colors for code blocksCopy
1
2
3
4
5
6
7
8
9
10
11
12
13
{
  "type": "WINDOWS",
  "properties": {
    "userPassword": "secret",
    "isPasswordEncrypted": "false",
    "user": "mydomain\\winaccount",
    "userFullnameAttribute": "displayName",
    "userEmailAttribute": "mail",
    "userGivenNameAttribute": "givenName",
    "userSurnameAttribute": "cn",
    "caseSensitive": "false"
  }
}

In most cases, you will only need to alter values for the user and userPassword properties. The account you use for the user property 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 property to true.

Update the groupStoreConfig parameter with the group information from your organization's enterprise identity store:

Use dark colors for code blocksCopy
1
2
3
4
5
6
7
8
{
  "type": "WINDOWS",
  "properties": {
    "isPasswordEncrypted": "false",
    "userPassword": "secret",
    "user": "mydomain\\winaccount"
  }
}

In most cases, you will only need to alter values for the user and userPassword property. The account you use for the user property only needs permissions to look up the names of Windows groups on the network. If possible, use an account whose password does not expire.

The codeblock below specifies the input JSON object for the userStoreConfig parameter:

Use dark colors for code blocksCopy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
{
  "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",
  }
}

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.

Update the groupStoreConfig parameter with the group information from your organization's enterprise identity store:

Use dark colors for code blocksCopy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{
  "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

The codeblock below specifies the input JSON object for the userStoreConfig parameter:

Use dark colors for code blocksCopy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
{
  "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 most cases, you will only need to alter values for the user, userPassword, and ldapURLForUsers properties. The URL to your LDAP will need to be provided by your LDAP administrator. The account you use for the user property needs permissions to look up the email address and user names of users in your organization. If your LDAP is configured to be case insensitive, set the caseSensitive property to false.

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:

Use dark colors for code blocksCopy
1
"ldapURLForUsers": "ldaps://bar2:10636/dc=example,dc=com"

Update the groupStoreConfig parameter with the group information from your organization's enterprise identity store:

Use dark colors for code blocksCopy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{
  "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

Pass in empty JSON objects for the userStoreConfig and groupStoreConfig parameters to force ArcGIs Enterprise to use built-in groups and the built-in identity store.

Your browser is no longer supported. Please upgrade your browser for the best experience. See our browser deprecation post for more details.