Configure a SAML-compliant identity provider with a portal

Security Assertion Markup Language (SAML) is an open standard that is used to securely exchange authentication and authorization data between an organization-specific identity provider and a service provider (in this case, your ArcGIS Enterprise organization). This approach is known as SAML Web Single Sign On.

The organization 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 organization; instead, they use the login that is already set up in an identity store. This process is described throughout the documentation as setting up organization-specific logins.

Optionally, you can provide metadata to the portal about the SAML groups in your identity store. This allows you to create groups in the portal that use the existing SAML groups in your identity store.

When members sign in to the portal, access to content, items, and data is controlled by the membership rules defined in the SAML group. If you do not provide the necessary SAML group metadata, you can still create groups. However, membership rules are controlled by the ArcGIS Enterprise portal, not the 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 organization-specific user names can be configured to match. All organization-specific user names in ArcGIS Online have the organization short name appended to the end. The same organization-specific 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 organization-specific users from both ArcGIS Online and your portal.

SAML sign in

ArcGIS Enterprise supports service provider (SP) initiated organization-specific logins and identity provider (IdP) initiated organization-specific logins. The sign 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 login manager) where they are prompted to provide their SAML user name and password. Upon verification of the user’s login credentials, the SAML-compliant identity provider informs ArcGIS Enterprise of the verified identity of the user who is signing 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 then enters their built-in user name and password to access the website. You can use the built-in account option as a fail-safe in case the SAML-compliant identity provider is unavailable, provided the option to sign in with an ArcGIS account has not been disabled.

Identity provider initiated logins

With identity provider initiated logins, users directly access the login manager and sign in with their account. When the user submits their account information, the identity provider sends the SAML response directly to ArcGIS Enterprise. The user is then signed 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 login manager. To sign in to the organization with built-in accounts, members must access the portal website directly.

Note:

If SAML logins fail to work due to issues with the identity provider and the built-in accounts option is disabled, you cannot access your ArcGIS Enterprise portal until you re-enable this option. See this question in Common problems and solutions for instructions.

SAML identity providers

ArcGIS Enterprise 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

ArcGIS Enterprise requires certain attribute information to be received from the IdP when a user signs in using SAML logins. The NameID attribute is mandatory and must be sent by your IdP in the SAML response to make federation work. Since ArcGIS Enterprise uses the value of NameID to uniquely identify a named user, it is recommended that you use a constant value that uniquely identifies the user. When a user from the IdP signs in, a new user with the username NameID will be created by the ArcGIS Enterprise organization in its user store. The allowed characters for the value sent by NameID are alphanumeric, _ (underscore), . (dot), and @ (at sign). Any other characters will be escaped to contain underscores in the username created by ArcGIS Enterprise.

ArcGIS Enterprise supports the inflow of a user's email address, group memberships, given name, and surname from the SAML identity provider.

User profile mappings

The following table lists which SAML assertion values map to which Portal user properties:

ArcGIS user property	IdP-defined claim attribute
Email address	Email emailaddress mail urn:oid:0.9.2342.19200300.100.1.3 http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
First name	givenName urn:oid:2.5.4.42 http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname
Last name	surname urn:oid:2.5.4.4 http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname
Groups	Group Groups Role Roles MemberOf member-of http://wso2.com/claims/role http://schemas.xmlsoap.org/claims/Group urn:oid:1.3.6.1.4.1.5923.1.5.1.1 urn:oid:2.16.840.1.113719.1.1.4.1.25 Note: Only a single attribute name should be specified for multiple group claims.

Configure the 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 organization-specific 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 Logins section, click the New SAML login button, and select the One identity provider option. On the Specify properties page, type your organization's name (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 Automatically or Upon invitation from an administrator to specify whetherusers can join the organization automatically or upon invitation.
   The first option allows users to sign in to the organization with their organization-specific login without intervention from an administrator. Their account is registered with the organization automatically the first time they sign in. The second option necessitates the administrator to register the necessary accounts with the organization using a command line utility. Once the accounts have been registered, users can sign in to the organization.

   Tip:

   It's recommended that you designate at least one SAML 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 in the portal website so users cannot create their own accounts. For instructions, see the Designate an organization-specific account as an administrator section below.

4. Specify the source that the portal will access to obtain metadata information This provides the necessary metadata information about your SAML-compliant identity provider. 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 identity provider includes a self-signed certificate, you may encounter an error when specifying the HTTPS URL of the metadata. This error occurs because ArcGIS Enterprise cannot verify the identity provider's self-signed certificate. Alternatively, use HTTP in the URL or 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:
     • Login URL (Redirect)—Provide the identity provider's URL (that supports HTTP redirect binding) that ArcGIS Enterprise will use to allow a member to sign in.
     • Login URL (POST)—Provide the identity provider's URL (that supports HTTP POST binding) that ArcGIS Enterprise will use to allow a member to sign in.
     • Certificate—Provide the certificate, encoded in the BASE 64 format, for the identity provider. This is the certificate that enables ArcGIS Enterprise to verify the digital signature in the SAML responses sent to it from the 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. Register the portal's service provider metadata with your identity provider to complete the configuration process and establish trust with the identity provider. To obtain the metadata from your portal, do one of the following:
   • In the Security section on the Settings tab for your organization, click the Download service provider metadata button to download the metadata file for your organization.
   • Open the URL of the metadata and save it 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 on the Generate Token page, specify the fully qualified domain name of the identity provider server in the Webapp URL text box. No other option, such as IP Address or IP Address of this request's origin, is 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:
   • Allow Encrypted Assertion—Indicate to the SAML identity provider that ArcGIS Enterprise 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 ArcGIS Enterprise is already encrypted by the use of HTTPS, but this option adds another layer of encryption.

     Tip:

     Some IdPs do not encrypt assertions by default. It is recommended that you ask your IdP administrator to ensure that encrypted assertions are enabled.

   • Enable signed request—Have ArcGIS Enterprise sign the SAML authentication request sent to the identity provider. Signing the initial login request sent by ArcGIS Enterprise allows the identity provider to verify that all login requests originate from a trusted service provider.
   • Propagate logout to Identity Provider—Have ArcGIS Enterprise 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 setting also needs to be enabled. When this setting is not checked, clicking Sign Out in ArcGIS Enterprise will sign out the user from ArcGIS Enterprise but not from the identity provider. If the user's web browser cache is not cleared, immediately signing back in to ArcGIS Enterprise using the organization-specific login option will result in a login without providing user credentials to the SAML identity provider. This is a security vulnerability that can be exploited when using a computer that is accessible to unauthorized users or to the general public.
   • Update profiles on sign in—Have ArcGIS Enterprise update users' givenName and email address attributes if they have changed since their last sign in. This is enabled by default.
   • Enable SAML based group membership—Allow portal administrators to link groups in the SAML identity provider to groups created in your ArcGIS Enterprise portal. When this setting is enabled, ArcGIS Enterprise parses the SAML assertion response to identify the groups a member belongs to. You can then specify one or more SAML groups supplied by the identity provider for Who can join this group? when you create a new group in your portal.

     Note:

     When creating a new group in the ArcGIS Enterprise portal, the group name you enter must match the exact value of the external SAML group as it is returned in the attribute value of the SAML assertion. If you aren't sure of the correct value, contact the administrator who configured your organization's SAML system.

     This feature is disabled 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 ArcGIS Enterprise organization to the SAML identity provider.

Designate an organization-specific account as an administrator

How you designate an organization-specific account as an administrator of the portal depends on whether users can join the organization automatically or upon invitation from an administrator.

Join the organization automatically

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

When an account is first added to the portal automatically, it is assigned the default role configured for new members. Only an administrator of the organization can change the role on an account; you must sign in to the portal using the initial administrator account and assign an organization-specific 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 SAML 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. 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 ArcGIS Enterprise.
4. Find the SAML account you want to use to administer the portal, and change the role to Administrator. Click Sign Out.

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

Manually add organization-specific accounts to the portal

If you chose the Upon invitation from an administrator option to only allow users to join the organization with an invitation, you must register the necessary accounts with the organization using a command line utility. Choose the Administrator role for a SAML 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 another role or delete the account. See About the initial administrator account for more information.

Prevent users from creating their own accounts

You can prevent users from creating their own built-in accounts by disabling the ability for users to create built-in accounts in the organization settings.

Prevent users from signing in with an ArcGIS account

To prevent users from signing in to the portal using an ArcGIS account, turn off the ArcGIS login toggle button on the sign in page.

1. Sign in to the portal website as an administrator of the organization and click Organization > Settings > Security.
2. In the Logins section, turn off the ArcGIS login toggle button.

The sign in page displays the button to log in to the portal using an identity provider account and the ArcGIS login button is not available. To re-enable member logins with ArcGIS accounts, turn on the ArcGIS login toggle button in the Logins section.

Modify or remove the SAML IdP

When you've set up a SAML IdP, you can update the settings for it by clicking the Edit button next to the currently registered SAML IdP. Update the settings in the Edit SAML login window.

To remove the currently registered IdP, click the Edit button next to the IdP and click Delete login in the Edit SAML login window. Once you've removed an IdP, you can optionally set up a new IdP or a federation of IdPs.

Best practices for SAML security

To enable SAML logins, you can configure ArcGIS Enterprise as an SP for your SAML IdP. To ensure robust security, consider the best practices described below.

Digitally sign the SAML login and logout requests and sign the SAML assertion response

Signatures are used to ensure the integrity of SAML messages and act as a safeguard against man-in-the-middle (MITM) attacks. Digitally signing the SAML request also ensures that the request is sent by a trusted SP, allowing the IdP to better deal with denial-of-service (DOS) attacks. Turn on the Enable signed request option in advanced settings when configuring SAML logins.

Note:

Enabling signed requests requires that the IdP be updated whenever the signing certificate used by the SP is renewed or replaced.

Configure the SAML IdP to sign the SAML response to prevent in-transit altering of the SAML assertion response.

Note:

Enabling signed requests requires that the SP (ArcGIS Enterprise) be updated whenever the signing certificate used by the IdP is renewed or replaced.

Use the HTTPS endpoint of the IdP

Any communication between the SP, the IdP, and the user's browser that is sent over either an internal network or the internet in an unencrypted format can be intercepted by a malicious actor. If your SAML IdP supports HTTPS, it is recommended that you use the HTTPS endpoint to ensure the confidentiality of data transmitted during SAML logins.

Encrypt the SAML assertion response

Using HTTPS for SAML communication secures the SAML messages sent between the IdP and SP. However, signed-in users can still decode and view the SAML messages through the web browser. Enabling the encryption of the assertion response prevents users from viewing confidential or sensitive information communicated between the IdP and SP.

Note:

Enabling encrypted assertions requires that the IdP be updated whenever the encryption certificate used by the SP (ArcGIS Enterprise) is renewed or replaced.

Securely manage the signing and encryption certificates

Use certificates with strong cryptographic keys for digitally signing or encrypting SAML messages, and renew or replace the certificates every three to five years.