Configure Shibboleth

You can configure Shibboleth 3.2x and 3.3.x as your IDP (IDP) for SAML logins in Portal for ArcGIS. The configuration process involves two main steps: registering your SAML IDP with Portal for ArcGIS and registering Portal for ArcGIS with the SAML IDP.

Note:

To ensure that your SAML logins are configured securely, review the best practices for SAML security.

Required information

Portal for ArcGIS 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 the federation with Portal for ArcGIS work. Since Portal for ArcGIS 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 user name NameID will be created by Portal for ArcGIS 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 user name created by Portal for ArcGIS.

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

Register Shibboleth as the SAML IDP with Portal for ArcGIS

1. Verify that you are signed in as an administrator of your organization.
2. At the top of the site, click Organization and click the Settings tab.
3. Click Security on the left side of the page.
4. In the Logins section, under SAML login, click the Set up 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).

   Note:

   You can only register one SAML IDP, or one federation of IDPs, for your portal.

5. Choose Automatically or Upon invitation from an administrator to specify how users can join the organization. Selecting the first option allows users to sign in to the organization with their SAML 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 can 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 is also recommended that you disable the Create an account button in the portal website so people cannot create their own accounts. For full instructions, see Configure a SAML-compliant identity provider with your portal.

6. Provide metadata information for the IDP using one of the two options below:
   • File—By default, Shibboleth provides the IdP metadata file in SHIBBOLETH_HOME/metadata. If the metadata file is accessible, choose the File option for the metadata of the SAML IDP and browse to the SHIBBOLETH_HOME/metadata/idp-metadata.xml file. Portal for ArcGIS validates the signature in SAML assertion responses from Shibboleth using the first signing certificate in the IDP metadata file. However, by default, the first signature listed in the Shibboleth IDP metadata file is for back channel TLS communication, while the second one is for signing assertion responses. You will need to either comment out the first signature or move it below the second one, and use the updated metadata file to register Shibboleth with Portal for ArcGIS. The signatures are defined using the <KeyDescriptor use="signing"> element in the metadata file.
   • Parameters specified here—Choose this option if the URL or federation metadata file is not accessible. Enter the values manually and supply the requested parameters: the login URL and the certificate, encoded in the BASE 64 format. Contact your Shibboleth administrator to obtain these.
7. Configure the advanced settings as applicable:
   • Encrypt Assertion—Enable this option if Shibboleth will be configured to encrypt SAML assertion responses.
   • Enable signed request—Enable this option to have Portal for ArcGIS sign the SAML authentication request sent to Shibboleth.
   • Entity ID—Update this value to use a new entity ID to uniquely identify your portal to Shibboleth.
   • Update profiles on sign in—Enable this option to have ArcGIS Enterprise update users' givenName and email address attributes if they have changed since they last signed in.
   • Enable SAML based group membership—Enable this option to allow organization members to link specified SAML-based enterprise groups to ArcGIS Enterprise groups during the group creation process.

   The Encrypt Assertion and Enable signed request settings use the certificate samlcert in the portal keystore. To use a new certificate, delete the samlcert certificate, create a certificate with the same alias (samlcert) following the steps in Import a certificate into the portal, and restart the portal.

   Note:

   Currently, Propagate logout to Identity Provider and Logout URL are not supported.

8. Click Save.

Register Portal for ArcGIS as the trusted service provider with Shibboleth

1. Configure Portal for ArcGIS as a relying party in Shibboleth.
   1. Obtain the metadata file of your portal and save it as an XML file.

      To get the metadata file, sign in as an administrator of your organization and open your organization page. Click the Settings tab and click Security on the left side of the page. In the Logins section, under SAML login, click the Download service provider metadata button.

   2. Configure Portal for ArcGIS as the trusted service provider in Shibboleth by defining a new MetadataProvider element in the SHIBBOLETH_HOME/conf/metadata-providers.xml file.

      Add the snippet below within the root MetadataProvider element. Provide the path to your organization's metadata XML file (saved in step 1.a above).

      <MetadataProvider id="EsriSP" xsi:type="FilesystemMetadataProvider"
      xmlns="urn:mace:shibboleth:2.0:metadata" 
      	xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance"
      	xsi:schemaLocation="urn:mace:shibboleth:2.0:metadata https://shibboleth.net/schema/idp/shibboleth-metadata.xsd"
      	failFastInitialization="true"
      	metadataFile=" <PATH_TO_THE_SAVED_METADATA>/esri-sp-metadata.xml" />

2. Configure user authentication. In the following example, an LDAP Directory Server is configured as the user store by updating the necessary properties in the SHIBBOLETH_HOME/conf/ldap.properties: file.

   idp.authn.LDAP.authenticator = bindSearchAuthenticator

   idp.authn.LDAP.ldapURL = ldaps://myldap.example.org:port

   idp.authn.LDAP.baseDN = ou=People,dc=example,dc=org

   idp.authn.LDAP.userFilter= (uid={user})

   idp.authn.LDAP.bindDN = cn=readonlyuser,dc=example,dc=org

   idp.authn.LDAP.bindDNCredential = userpassword

3. Configure the user attributes to be returned by Shibboleth.
   1. Edit SHIBBOLETH_HOME/conf/attribute-resolver.xml. Comment or delete all existing example attribute definitions and data connectors.
   2. Copy the definitions for mail, givenName, and surname from the SHIBBOLETH_HOME/conf/attribute-resolver-full.xml file to the SHIBBOLETH_HOME/conf/attribute-resolver.xml file.
   3. Copy the LDAP Data Connector section from SHIBBOLETH_HOME/conf/attribute-resolver-ldap.xml to SHIBBOLETH_HOME/conf/attribute-resolver.xml. Copy the definition for uid or any other attribute you want to return as the NAMEID attribute.
   4. Configure the attributes to release to the service provider. Edit the SHIBBOLETH_HOME/conf/attribute-filter.xml file and add the following:

   <AttributeFilterPolicy id="ArcGIS">
           <PolicyRequirementRule xsi:type="Requester" value="[The Entity ID of your Portal instance]" />
   			<AttributeRule attributeID="<NameID Attribute>">
   				<PermitValueRule xsi:type="ANY" />
   			</AttributeRule>
   
   			<AttributeRule attributeID="givenName">
   				<PermitValueRule xsi:type="ANY" />
   			</AttributeRule>
   
   			<AttributeRule attributeID="mail">
   				<PermitValueRule xsi:type="ANY" />
   			</AttributeRule>
   		</AttributeFilterPolicy>

4. Edit the SHIBBOLETH_HOME/conf/relying-party.xml file.
   1. Copy the XML code below and paste it inside the shibboleth.RelyingPartyOverrides elements to override the default configuration for the Shibboleth Identity Provider:

      <bean parent="RelyingPartyByName" c:relyingPartyIds="[The Entity ID of your Portal instance]">
      <property name="profileConfigurations">
       <list>
        <bean parent="SAML2.SSO" 
         p:nameIDFormatPrecedence="urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified" />
       </list>
      </property>
      </bean>

      The nameIDFormatPrecedence parameter instructs the IDP to send the SAML name ID attribute in the unspecified format, which is required by ArcGIS Online and Portal for ArcGIS.

   2. Turn off assertion encryption in the Shibboleth Identity Provider by setting the encryptAssertions parameter to false.

      <bean parent="RelyingPartyByName" c:relyingPartyIds="[The Entity ID of your Portal instance]">
      		<property name="profileConfigurations">
      			<list>
      				<bean parent="SAML2.SSO" 
      					p:nameIDFormatPrecedence="urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified" 
      					p:encryptAssertions="false" />
      			</list>
      		</property>
      		</bean>

5. Edit the SHIBBOLETH_HOME/conf/saml-nameid.xml file and replace this section:

   <!--
   <bean parent="shibboleth.SAML2AttributeSourcedGenerator"
      p:format="urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress"
      p:attributeSourceIds="#{ {'mail'} }" />
   -->

   with the following:

   <bean parent="shibboleth.SAML2AttributeSourcedGenerator"
               p:format="urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified"
               p:attributeSourceIds="#{ {'your-name-id-attribute'} }" />

6. Restart the Shibboleth daemon (Linux) or service (Windows).