Configure Shibboleth

You can configure Shibboleth 2.x as your identity provider for enterprise logins in Portal for ArcGIS. The configuration process involves two main steps: registering your enterprise identity provider with Portal for ArcGIS and registering Portal for ArcGIS with the enterprise identity provider.

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 are controlled by the membership rules defined in the enterprise group. If you do not provide the necessary enterprise group metadata, you'll still be able to create groups. However, membership rules will be controlled by Portal for ArcGIS, not the identity store.

Required information

Portal for ArcGIS requires certain attribute information to be received from the identity provider when a user logs in using enterprise logins. NameID is a mandatory attribute that 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 flow-in of the givenName and the email address attributes of the enterprise login from the enterprise 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.

Register Shibboleth as the enterprise identity provider with Portal for ArcGIS

1. Sign in to the portal website as an Administrator of your organization and click My Organization > Edit Settings > Security.
2. Within the Enterprise Logins section, click the Set Identity Provider button and enter your organization's name in the window that opens (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 if your users will be able to join the organization Automatically or After you add the accounts to the portal. Selecting 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 is also recommended 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 Configuring a SAML-compliant identity provider with your portal.

4. Configure the advanced settings as applicable:
   • Encrypt Assertion—Select this option if Shibboleth will be configured to encrypt SAML assertion responses.
   • Enable Signed Request—Select this option to have Portal for ArcGIS sign the SAML authentication request sent to Shibboleth.
   • Logout URL—Update this value if you have configured Shibboleth to use a custom log out URL.
   • Entity ID—Update this value to use a new entity ID to uniquely identify your portal to Shibboleth.

   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 new certificate with the same alias (samlcert) following the steps in Import a certificate into the portal, and restart the portal.

5. Provide metadata information for the identity provider 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 enterprise identity provider and browse to the file SHIBBOLETH_HOME/metadata/idp-metadata.xml.
   • Parameters—Choose this option if the file is not accessible. Enter the values manually and supply the requested parameters: login URL and certificate. Contact your Shibboleth administrator to obtain these.
6. Optionally provide metadata to the portal about the enterprise groups in the identity store:
   1. Sign in to the ArcGIS Portal Directory as an Administrator of your organization. The URL is in the format https://webadaptor.domain.com/arcgis/portaladmin.
   2. Click Security > Config > Update Identity Store.
   3. Place the group configuration JSON in the Group store configuration (in JSON format) text box.

      • If your identity store is Windows Active Directory, copy the following text, and alter it to contain the information specific to your site:

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

      • If your identity store is LDAP, copy the following text, and alter it to contain the information specific to your site:

        {
          "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/dc=example,dc=com",
            "usernameAttribute": "cn",
            "caseSensitive": "false",
            "userSearchAttribute": "cn",
            "memberAttributeInRoles": "member",
            "rolenameAttribute":"cn"
          }
        }

        In most cases, you'll only need to alter values for the user, userPassword, ldapURLForUsers, and ldapURLForUsers parameters. The URL to your LDAP will need to be provided by your LDAP administrator. 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".
   4. When you finish entering the JSON for the user store configuration, click Update Configuration to save your changes and restart the portal.

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 Edit Settings button and the Security tab, and within the Enterprise Logins section, click the Get Service Provider button.

   2. Add Portal for ArcGIS as the trusted service provider in Shibboleth by defining a new RelyingParty element in the SHIBBOLETH_HOME/conf/relying-party.xml file.

      Add the snippet below within the metadata:MetadataProvider. Provide the path to your organization’s metadata XML file (saved in step 1.a).

      Note:

      (Replace webadaptor.domain.com.arcgis with the entityid from the SAML metadata of your portal.)

      <!-- Load metadata -->
      	    <MetadataProvider xsi:type="FilesystemMetadataProvider"
      	                      xmlns="urn:mace:shibboleth:2.0:metadata"
      	                      id="webadaptor.domain.com.arcgis"
      	                      metadataFile="<PATH_TO_THE_SAVED_METADATA>/citygismetadata.xml">
      	    </MetadataProvider>

2. Configure attribute resolver.

   Portal for ArcGIS expects a SAML name identifier to be passed from the IdP for the user trying to sign in to Portal for ArcGIS. To make this data available, you need to configure the Shibboleth attribute resolver by modifying the SHIBBOLETH_HOME/conf/attribute-resolver.xml file.

   The following attribute definition sends the principal name of the user who was authenticated by the Shibboleth IdP in the name identifier to Portal for ArcGIS.

   <!-- Name identifier for passing principal name to Portal for ArcGIS -->
       <resolver:AttributeDefinition id="principal" xsi:type="PrincipalName" xmlns="urn:mace:shibboleth:2.0:resolver:ad">
           <resolver:AttributeEncoder xsi:type="SAML2StringNameID" xmlns="urn:mace:shibboleth:2.0:attribute:encoder"
               nameFormat="urn:oasis:names:tc:SAML:2.0:nameid-format:unspecified" />
       </resolver:AttributeDefinition>

3. Configure attribute filter.

   Configure the Shibboleth attribute filter to release the user’s principal name encoded as a NameID to Portal for ArcGIS after authenticating the user. The value of the NameID parameter will be used as the user name in the organization.

   To add this filter, open the SHIBBOLETH_HOME/conf/attribute-filter.xml file and add the following attribute filter policy within the AttributeFilterPolicyGroup XML element.

   Note:

   (Replace webadaptor.domain.com.arcgis with the entityid from the SAML metadata of your portal.)

   <!-- release the NameID to webadaptor.domain.com.arcgis -->
       <afp:AttributeFilterPolicy>
               <afp:PolicyRequirementRule xsi:type="basic:AttributeRequesterString" value="webadaptor.domain.com.arcgis" />
       
               <afp:AttributeRule attributeID="principal">
                   <afp:PermitValueRule xsi:type="basic:ANY" />
               </afp:AttributeRule>
       </afp:AttributeFilterPolicy>

   Portal for ArcGIS supports flow-in of the givenName and the email address attributes of the enterprise login from the enterprise 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 is recommended that you pass in the email address from the enterprise identity provider to Portal for ArcGIS. This helps if the user later becomes an administrator. Having an email address in the account entitles the user to receive notifications regarding any administrative activity and send invitations to other users to join the organization.

4. Configure authentication source.

   Configure authentication source used by the Shibboleth IdP. The following example shows how to configure Apache Directory Server as a user store with Shibboleth in the SHIBBOLETH_HOME/conf/login.config file.

   ShibUserPassAuth {   
   edu.vt.middleware.ldap.jaas.LdapLoginModule required
         ldapUrl="ldap://host:port"
         baseDn="ou=users,ou=system"
         ssl="true"
         serviceUser="uid=admin,ou=system"
         serviceCredential="secret"
         subtreeSearch="true"
         userField="uid"
         userFilter="uid={0}";
   };

5. Configure login handler.

   Enable UsernamePassword login handler in Shibboleth. With the login handler, users can sign in using a user name and password from the authentication source configured in the previous step.

   To configure the login handler, open the SHIBBOLETH_HOME/conf/handler.xml file and uncomment the user name and password login handler. (Replace <SHIBBOLETH_HOME> with your Shibboleth installation path.)

   <!--  Username/password login handler -->
        
       <ph:LoginHandler xsi:type="ph:UsernamePassword" 
                     jaasConfigurationLocation="file://<SHIBBOLETH_HOME>/conf/login.config">
           <ph:AuthenticationMethod>urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport</ph:AuthenticationMethod>
       </ph:LoginHandler>

6. Turn off assertion encryption in the Shibboleth IdP. Open the SHIBBOLETH_HOME/conf/relying-party.xml file and search for the saml: SAML2SSOProfile section within the element. In this section, change the value of encryptAssertions to never.

   Note:

   Skip this step if you chose the advanced setting Encrypt Assertion when registering Shibboleth as the enterprise identity provider.

   <rp:DefaultRelyingParty provider="https://grid3.esri.com/idp/shibboleth"
   defaultSigningCredentialRef="IdPCredential">
   ...
        <rp:ProfileConfiguration xsi:type="saml:SAML2SSOProfile" includeAttributeStatement="true"
             assertionLifetime="PT5M" assertionProxyCount="0"
             signResponses="never" signAssertions="always"
             encryptAssertions="never" encryptNameIds="never"
             includeConditionsNotBefore="true"/>
   ...
   </rp:DefaultRelyingParty>

7. Restart the web server that hosts the Shibboleth web application.