Update Identity Store

Description

You can use this operation to change the identity provider and group store configuration in your portal. When Portal for ArcGIS is first installed, it supports token-based authentication and built-in groups using the built-in identity store for accounts. To configure your portal to connect to your enterprise authentication mechanism and group store, it must be configured to use an enterprise identity store such as Windows Active Directory or LDAP.

Request parameters

The operation takes input as a JSON object with the following properties:

Properties

Details

userPassword

The password for the domain account, for example, 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.

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.

Windows Active Directory example: mydomain\\winaccount

LDAP example: uid=admin,ou=system

userFullnameAttribute

The attribute in Windows Active Directory or LDAP that contains the full name of the users, for example, cn.

ldapURLForUsers

The URL to your LDAP that points to the user accounts, for example, ldaps://bar2:10636/ou=users,ou=ags,dc=example,dc=com. 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 the portal and LDAP server. 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.

ldapURLForRoles

The URL to your LDAP that points to the roles, for example, ldaps://bar2:10636/dc=example,dc=com. 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 the portal and LDAP server. 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.

userEmailAttribute

The attribute in Windows Active Directory or LDAP that contains the email addresses of the users, for example, mail.

usernameAttribute

The LDAP attribute of the user entry that is to be treated as the user name, for example, cn.

This property is not applicable when configuring Windows Active Directory.

userSearchAttribute

When using LDAP and PKI to secure access to your 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.

domainControllerAddress

The IP address of the domain controller to be used by Portal for ArcGIS. 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. Does not support IPv6.

refreshUserMembershipDuringLoginEnabled

This property is only applicable when configuring the group store. By default, each time an enterprise user signs in to 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.

membershipRefreshIntervalHours

This property is only applicable when configuring the group store. 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 the 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 your portal will need to use the following username formats: DOMAIN\username or username@DOMAIN. If checkForMultipleUsernameFormats is true, your portal will attempt to use different username formats if the initial attempt fails (includes username and username@DOMAIN.com).

Example usage

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

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:

Windows Active Directory example

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

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 the 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".

LDAPS example (highly recommended)

NoteNote:

Although both LDAP and LDAPS URLs are supported, LDAPS is highly recommended to ensure encrypted network traffic between the 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": "cn",
    "ldapURLForUsers": "ldaps://bar2:10636/ou=users,ou=ags,dc=example,dc=com",
    "userEmailAttribute": "mail",
    "usernameAttribute": "cn",
    "caseSensitive": "true"
  }
}

LDAP example

{
  "type": "LDAP",
  "properties": {
    "userPassword": "secret",
    "isPasswordEncrypted": "false",
    "user": "uid=admin,ou=system",
    "userFullnameAttribute": "cn",
    "ldapURLForUsers": "ldap://bar2:10389/ou=users,ou=ags,dc=example,dc=com",
    "userEmailAttribute": "mail",
    "usernameAttribute": "cn",
    "caseSensitive": "true"
  }
}

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.

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",

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 the portal's configuration directory or viewed.

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

Next, delete any information in the Group store configuration (in JSON format) text box. This will force the 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:

Windows Active Directory example

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

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 the 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".

LDAPS example (highly recommended)

NoteNote:

Although both LDAP and LDAPS URLs are supported, LDAPS is highly recommended to ensure encrypted network traffic between the 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": "cn",
    "ldapURLForUsers": "ldaps://bar2:10636/ou=users,ou=ags,dc=example,dc=com",
    "userEmailAttribute": "mail",
    "usernameAttribute": "cn",
    "caseSensitive": "true"
  }
}

LDAP example

{
  "type": "LDAP",
  "properties": {
    "userPassword": "secret",
    "isPasswordEncrypted": "false",
    "user": "uid=admin,ou=system",
    "userFullnameAttribute": "cn",
    "ldapURLForUsers": "ldap://bar2:10389/ou=users,ou=ags,dc=example,dc=com",
    "userEmailAttribute": "mail",
    "usernameAttribute": "cn",
    "caseSensitive": "true"
  }
}

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.

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",

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 the portal's configuration directory or viewed.

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

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

Windows Active Directory example

{
  "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 parameters. Although you type the password in clear text, it will be encrypted when stored in the portal's configuration directory or viewed. The account you use for the user parameter only needs permissions to look up the names of Windows groups on the network. If possible, use an account whose password does not expire.

LDAPS example (highly recommended)

NoteNote:

Although both LDAP and LDAPS URLs are supported, LDAPS is highly recommended to ensure encrypted network traffic between the 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",
    "ldapURLForUsers": "ldaps://bar2:10636/ou=users,ou=ags,dc=example,dc=com",
    "ldapURLForRoles": "ldaps://bar2:10636/ou=roles,ou=ags,dc=example,dc=com",
    "userEmailAttribute": "mail",
    "usernameAttribute": "cn",
    "caseSensitive": "false",
    "memberAttributeInRoles": "member",
    "rolenameAttribute":"cn"
  }
}

LDAP example

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

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

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",

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

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

Configure built-in 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

{}

9/13/2017