Configure a SAML-compliant identity provider with your portal

Security Assertion Markup Language (SAML) is an open standard to securely exchange authentication and authorization data between an enterprise identity provider and a service provider (in this case, Portal for ArcGIS). The approach used to achieve this is known as SAML Web Single Sign On. The portal is compliant with SAML 2.0 and integrates with identity providers that support SAML 2 Web Single Sign On. The advantage of setting up SAML is that you do not need to create additional logins for users to access your ArcGIS Enterprise portal; instead, they use the login that is already set up in an enterprise identity store. This process is described throughout the documentation as "setting up enterprise logins."

Optionally, you can provide metadata to the portal about the enterprise groups in your identity store. This allows you to create groups in the portal that leverage the existing enterprise groups in your identity store. When members log in to the portal, access to content, items, and data is controlled by the membership rules defined in the enterprise group. If you do not provide the necessary enterprise group metadata, you can still create groups. However, membership rules will be controlled by your ArcGIS Enterprise portal, not your identity store.

Match ArcGIS Online user names in the ArcGIS Enterprise portal

If the same SAML-compliant identity provider is used in your ArcGIS Online organization and your portal, the enterprise user names can be configured to match. All enterprise user names in ArcGIS Online have the organization short name appended to the end. The same enterprise user names can be used in your portal by defining the defaultIDPUsernameSuffix property in the ArcGIS Enterprise portal's security configuration and setting it to match the organization's short name. This is needed if editor tracking is enabled on a feature service that is edited by enterprise users from both ArcGIS Online and your portal.

SAML sign in experience

Portal for ArcGIS supports service provider (SP) initiated enterprise logins and identity provider (IDP) initiated enterprise logins. The log in experience differs between each.

Service provider initiated logins

With service provider initiated logins, users access the portal directly and are presented with options to sign in with built-in accounts (managed by the portal) or accounts managed in a SAML-compliant identity provider. If the user chooses the SAML identity provider option, they are redirected to a web page (known as the enterprise's login manager) where they are prompted to enter their enterprise user name and password. Upon verification of the user’s login, the enterprise identity provider informs Portal for ArcGIS of the verified identity for the user who is logging in, and the user is redirected back to the portal website.

If the user chooses the built-in account option, the sign in page for the ArcGIS Enterprise portal website opens. The user can then enter their built-in user name and password to access the website. This option cannot be disabled. The built-in account option can be used as a fail-safe in case your SAML-compliant identity provider is unavailable.

Identity provider initiated logins

With identity provider initiated logins, users directly access the enterprise's login manager and sign in with their account. When the user submits their account information, the identity provider sends the SAML response directly to Portal for ArcGIS. The user is then logged in and redirected to the portal website where they can immediately access resources without having to sign in to the organization again.

The option to sign in using built-in accounts is not available from the enterprise's login manager. To sign in to the organization with built-in accounts, members need to access the portal website directly.

Note:

If SAML logins fail to work due to issues with your SAML identity provider, and you have disabled the built-in accounts option, you will be unable to access your ArcGIS Enterprise portal until you re-enable this option. For instructions on how to do this, see this question in Common problems and solutions.

SAML identity providers

Portal for ArcGIS supports all SAML-compliant identity providers. You can find detailed instructions on configuring certain common SAML-compliant identity providers in the ArcGIS/idp GitHub repository.

The process of configuring identity providers with ArcGIS Enterprise is described below. Before proceeding, it is recommended that you contact the administrator of your SAML identity provider to obtain the parameters needed for configuration.

Required information

Portal for ArcGIS requires certain attribute information to be received from the identity provider when a user logs in using enterprise logins. The NameID attribute is mandatory and must be sent by your identity provider in the SAML response to make the federation with Portal for ArcGIS work. When a user from the IDP logs in, a new user with the user name NameID will be created by Portal for ArcGIS in its user store. The allowed characters for the value sent by the NameID attribute are alphanumeric, _ (underscore), . (dot), and @ (at sign). Any other characters will be escaped to contain underscores in the user name created by Portal for ArcGIS.

Portal for ArcGIS supports inflow of the givenName and email address attributes of the enterprise login from the identity provider. When a user signs in using an enterprise login, and if Portal for ArcGIS receives attributes with the names givenname and email or mail (in any case), Portal for ArcGIS populates the full name and the email address of the user account with the values received from the identity provider. It's recommended that you pass in the email address from the enterprise identity provider so the user can receive notifications.

Configure a portal with a SAML identity provider

You can configure your portal so that users can sign in using the same user name and password that they use with your existing on-premises systems. Before setting up Enterprise Logins, you must configure a default user type for your organization.

1. Sign in to the portal website as an administrator of your organization and click Organization > Settings > Security.
2. In the Enterprise Logins via SAML section, select the One Identity Provider option, click the Set Enterprise Login button, and enter your organization's name in the window that appears (for example, City of Redlands). When users access the portal website, this text displays as part of the SAML sign-in option (for example, Using your City of Redlands account).
3. Choose whether your users will be able to join the organization Automatically or After you add the accounts to the portal. Choosing the first option enables users to sign in to the organization with their enterprise login without any intervention from an administrator. Their account is registered with the organization automatically the first time they sign in. The second option requires the administrator to register the necessary accounts with the organization using a command line utility or sample Python script. Once the accounts have been registered, users will be able to sign in to the organization.

   Tip:

   It's recommended that you designate at least one enterprise account as an administrator of your portal and demote or delete the initial administrator account. It's also recommended that you disable the Create an account button and sign up page (signup.html) in the portal website so people cannot create their own accounts. For full instructions, see the Designate an enterprise account as an administrator section below.

4. Provide the necessary metadata information about your SAML-compliant enterprise identity provider. You'll do this by specifying the source that the portal will access to obtain metadata information. You can find instructions for obtaining metadata from certified providers in the ArcGIS/idp GitHub repository. There are three possible sources of metadata information:
   • A URL—Provide a URL that returns metadata information about the identity provider.

     Note:

     If your enterprise identity provider includes a self-signed certificate, you may encounter an error when attempting to specify the HTTPS URL of the metadata. This error occurs because Portal for ArcGIS cannot verify the identity provider's self-signed certificate. Alternatively, use HTTP in the URL, one of the other options below, or configure your identity provider with a trusted certificate.

   • A file—Upload a file that contains metadata information about the identity provider.
   • Parameters specified here—Directly enter the metadata information about the identity provider by supplying the following parameters:
     • Login URL (Redirect)—Enter the identity provider's URL (that supports HTTP redirect binding) that Portal for ArcGIS should use to allow a member to sign in.
     • Login URL (POST)—Enter the identity provider's URL (that supports HTTP POST binding) that Portal for ArcGIS should use to allow a member to sign in.
     • Certificate—Provide the certificate, encoded in the BASE 64 format, for the enterprise identity provider. This is the certificate that allows Portal for ArcGIS to verify the digital signature in the SAML responses sent to it from the enterprise identity provider.

   Note:

   Contact the administrator of the identity provider if you need help determining which source of metadata information you need to provide.

5. To complete the configuration process and establish trust with the identity provider, register the portal's service provider metadata with your enterprise identity provider. There are two ways to obtain the metadata from your portal:
   • In the Security section of the Settings tab for your organization, click the Get Service Provider button. This shows the metadata for your organization, which you can save as an .xml file on your computer.
   • Open the URL of the metadata and save as an .xml file on your computer. The URL is https://webadaptorhost.domain.com/webadaptorname/sharing/rest/portals/self/sp/metadata?token=<token>, for example, https://samltest.domain.com/arcgis/sharing/rest/portals/self/sp/metadata?token=G6943LMReKj_kqdAVrAiPbpRloAfE1fqp0eVAJ-IChQcV-kv3gW-gBAzWztBEdFY. You can generate a token using https://webadaptorhost.domain.com/webadaptorname/sharing/rest/generateToken. When entering the URL in the Generate Token page, specify the fully qualified domain name of the identity provider server in the Webapp URL field. Choosing any other option, such as IP Address or IP Address of this request's origin, is not supported and may generate an invalid token.

   You can find instructions for registering the portal's service provider metadata with certified providers in the ArcGIS/idp GitHub repository.

6. Configure advanced settings as applicable:
   • Encrypt Assertion—Select this option to indicate to the SAML identity provider that Portal for ArcGIS supports encrypted SAML assertion responses. When this option is selected, the identity provider will encrypt the assertion section of the SAML responses. All SAML traffic to and from Portal for ArcGIS is already encrypted by the use of HTTPS, but this option adds another layer of encryption.
   • Enable Signed Request—Select this option to have Portal for ArcGIS sign the SAML authentication request sent to the identity provider. Signing the initial login request sent by Portal for ArcGIS allows the identity provider to verify that all login requests originate from a trusted service provider.
   • Propagate logout to Identity Provider—Select this option to have Portal for ArcGIS use a logout URL to sign out the user from the identity provider. Enter the URL to use in the Logout URL setting. If the identity provider requires the logout URL to be signed, the Enable Signed Request option also needs to be checked. When this option is not checked, clicking Sign Out in Portal for ArcGIS will sign out the user from Portal for ArcGIS but not from the identity provider. If the user's web browser cache is not cleared, attempting to immediately sign back in to Portal for ArcGIS using the enterprise login option will result in an immediate login without needing to provide user credentials to the SAML identity provider. This is a security vulnerability that can be exploited when using a computer that is easily accessible to unauthorized users or to the public.
   • Update profiles on sign in—Select this option to have Portal for ArcGIS update users' givenName and email address attributes if they have changed since their last login. This is selected by default.
   • Enable SAML based group membership—Select this option to allow portal administrators to link groups in your SAML identity provider to groups created in your ArcGIS Enterprise portal. When this is selected, Portal for ArcGIS will parse the SAML assertion response to determine which groups a member belongs to. You can then specify one or more enterprise groups supplied by your identity provider for Who can join this group? when you create a group in your portal. This feature is not selected by default.
   • Logout URL—Enter the identity provider URL to use to sign out the currently signed-in user. If this property is specified in the identity provider's metadata file, it is automatically set.
   • Entity ID—Update this value to use a new entity ID to uniquely identify your Portal for ArcGIS organization to the SAML identity provider.

Configure a SAML-compliant IDP for a highly available portal

Portal for ArcGIS uses a certificate with the alias samlcert when sending signed requests (for logins and logouts) to the IDP, and when decrypting encrypted responses from the IDP. If you are configuring a highly available ArcGIS Enterprise portal and are using a SAML-compliant IDP, you must ensure each instance of Portal for ArcGIS is using the same certificate when communicating with the IDP.

The best way to ensure all instances are using an identical certificate for SAML is to generate a new certificate with the alias samlcert and import it into each instance of Portal for ArcGIS in your highly available deployment.

1. Sign in to the Portal Administrator Directory at https://example.domain.com:7443/arcgis/portaladmin.
2. Browse to Security > sslcertificates, then click the existing samlcert certificate.
3. Click delete.
4. Repeat steps 1 through 3 to delete the existing samlcert certificates in all instances of your highly available portal.
5. Generate a new self-signed certificate from the ArcGIS Portal Administrator Directory.
6. When configuring the certificate, specify samlcert as the alias, and the host name of your deployment's load balancer as both the Common Name and the DNS alias in the Subject Alternative Name.
7. Once the certificate has been generated, export it to a .pfx file:
   1. Start a terminal session and authenticate as the user who installed Portal for ArcGIS.
   2. From the command line, browse to the <Portal installation location>/etc/ssl directory.
   3. Enter the following command to export the samlcert in the .pfx file format:
      ..../framework/runtime/jre/bin/keytool.exe -importkeystore -srckeystore portal.ks -destkeystore samlcert.pfx -srcstoretype JKS -deststoretype PKCS12 -srcstorepass portal.secret -deststorepass password -srcalias samlcert -destalias samlcert -destkeypass password

8. Import the new certificate into each instance of Portal for ArcGIS from the Security > sslcertificates > Import Existing Server Certificate page.
9. Restart Portal for ArcGIS on each instance in your highly available portal.

You can use the service provider metadata file in your ArcGIS Enterprise portal to verify that the certificates being used to communicate with the SAML IDP are the same across your highly available deployment.

1. From the Organization tab, browse to Edit Settings > Security.
2. In the Enterprise Logins via SAML item on the Security page, click Edit Identity Provider. Open the Show advanced settings menu, and ensure the Encrypt Assertion option is selected. If not, select it and click Update Identity Provider to save the change.
3. Return to the Enterprise Logins via SAML items, and select Get Service Provider. This will export the service provider metadata as an .xml file to your machine.
4. Open the downloaded .xml file. Ensure the following phrase is present: <md:KeyDescriptor use="encryption">. This indicates the certificate for encryption is present.
5. Note the values in the subsection<ds:KeyInfo>.
6. Repeat these steps for each instance of Portal for ArcGIS in your deployment to obtain the service provider metadata file from each.

The exported metadata files should all have the same information in the <ds:KeyInfo> subsection, indicating the same certificate is used by each instance of Portal for ArcGIS when communicating with your SAML-compliant IDP.

Designate an enterprise account as an administrator

How you designate an enterprise account as an administrator of the portal will depend on whether users will be able to join the organization Automatically or After you add the accounts to the portal.

Join the organization automatically

If you chose the option to allow users to join the organization Automatically, open the portal website home page while logged in with the enterprise account you want to use as the portal administrator.

When an account is first added to the portal automatically, it is assigned the User role. Only an administrator of the organization can change the role on an account; therefore, you must sign in to the portal using the initial administrator account and assign an enterprise account to the administrator role.

1. Open the portal website, click the option to sign in using a SAML identity provider, and provide the credentials of the enterprise account you want to use as an administrator. If this account belongs to someone else, have that user sign in to the portal so the account is registered with the portal.
2. Verify that the account has been added to the portal and click Sign Out. Clear your browser's cache and cookies.
3. While in the browser, open the portal website, click the option to sign in using a built-in portal account, and provide the credentials of the initial administrator account you created when you set up Portal for ArcGIS.
4. Find the enterprise account you'll use to administer your portal, and change the role to Administrator. Click Sign Out.

The enterprise account you chose is now an administrator of the portal.

Manually add enterprise accounts to the portal

If you chose the option to only allow users to join the organization After you add the accounts to the portal, you'll need to register the necessary accounts with the organization using a command line utility or sample Python script. Be sure to choose the Administrator role for an enterprise account that will be used to administer the portal.

Demote or delete the initial administrator account

Now that you have an alternate portal administrator account, you can assign the initial administrator account to the User role or delete the account. See About the initial administrator account for more information.

Prevent users from creating their own accounts

After you've secured access to your portal, it is recommended that you disable the Create an account button and sign up page (signup.html) in the portal website so people cannot create their own accounts. This means all members sign in to the portal with their enterprise account and credentials, and unnecessary built-in accounts cannot be created. See Disabling users ability to create built-in portal accounts for full instructions.

Disable signing in with ArcGIS accounts

If you want to prevent users from signing in to the portal using an ArcGIS account, you can disable the Using Your ArcGIS Account button on the sign in page. To do this, follow the steps below.

1. Sign in to the portal website as an administrator of your organization and click Organization > Edit Settings > Security.
2. In the Sign In Options section, choose the radio button for Their SAML IDP account only, where the IDP will vary depending on what you have configured for your portal.
3. Click Save.

The sign in page will display the button to log in to the portal using an identity provider account and the button to log in Using Your ArcGIS Account will not be available. You can re-enable member logins with ArcGIS accounts by choosing the Their SAML IDP account or Portal for ArcGIS account under Sign In Options , where the IDP and name of your portal will vary depending on what you have configured.

Modify the SAML identity provider

You can edit or remove the currently registered identity provider by using the Edit Enterprise Login and Remove Enterprise Login buttons. These buttons will be enabled only when you've set up a SAML-compliant identity provider. Once you remove the identity provider, you can set up a new one if desired.