Configure Active Directory Federation Services

You can configure Active Directory Federation Services (AD FS) 2.0 roll-up patch 3 and AD FS 3.0 in the Microsoft Windows Server operating system 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 Windows Active Directory. 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'll still be able to create groups. However, membership rules will be controlled by Portal for ArcGIS, not Windows Active Directory.

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 inflow 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 AD FS 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. In the Enterprise Logins section, click the Set Identity Provider 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).

   Note:

   You can only register one enterprise identity provider for your portal.

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 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 Configuring a SAML-compliant identity provider with your portal.

4. Provide metadata information for the identity provider using one of the options below:
   • URL—If the URL of AD FS federation metadata is accessible, select this option and enter the URL (for example, https://<adfs-server>/federationmetadata/2007-06/federationmetadata.xml).

     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.

   • File—Choose this option if the URL is not accessible. Download or obtain a copy of the federation metadata file from AD FS and upload the file to Portal for ArcGIS using the File option.
   • Parameters—Choose this option if the URL or federation metadata file is not accessible. Enter the values manually and supply the requested parameters: login URL and certificate. Contact your AD FS administrator to obtain these.
5. Configure the advanced settings as applicable:
   • Encrypt Assertion—Select this option to encrypt the AD FS SAML assertion responses.
   • Enable Signed Request—Select this option to have Portal for ArcGIS sign the SAML authentication request sent to AD FS.
   • Propagate logout to Identity Provider—Select this option to have Portal for ArcGIS use a logout URL to sign out the user from AD FS. Enter the URL to use in the Logout URL setting. If the identity provider requires the logout URL to be signed, Enable Signed Request needs to be checked.

     Note:

     By default, AD FS requires logout requests to be signed using SHA-256, so you need to check Enable Signed Request and Sign using SHA256.

   • Logout URL—The identity provider URL to use to sign out the currently signed in user.
   • Entity ID—Update this value to use a new entity ID to uniquely identify your portal to AD FS.

   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.

6. Optionally provide metadata to the portal about the enterprise groups in Windows Active Directory:
   1. Sign in to the ArcGIS Portal Directory as an administrator of your organization. The URL is in the format https://webadaptorhost.domain.com/webadaptorname/portaladmin.
   2. Click Security > Config > Update Identity Store.
   3. Place the group configuration JSON in the Group store configuration (in JSON format) text box.

      You can copy the following text and alter it to contain the information specific to your site:

      {
      "type": "LDAP",
      "properties": {
      "userPassword": "secret",
      "isPasswordEncrypted": "false",
      "user": "cn=aduser,ou=users,ou=ags,dc=example,dc=com",
      "ldapURLForUsers": "ldap://bar2:10389/ou=users\,ou=ags\,dc=example\,dc=com",
      "ldapURLForRoles": "ldap://bar2:10389/dc=example,dc=com",
      "usernameAttribute": "sAMAccountName",
      "caseSensitive": "false",
      "userSearchAttribute": "sAMAccountName",
      "memberAttributeInRoles": "member",
      "rolenameAttribute":"sAMAccountName"
      }
      }

      In most cases, you will only need to alter values for the user, userPassword, ldapURLForUsers, and ldapURLForRoles parameters. The LDAP URL will need to be provided by your AD 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.

   4. When you have finished 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 AD FS

1. Open the AD FS management console.
2. Choose Relying Party Trusts > Add Relying Party Trust.

   

3. In the Add Relying Party Trust Wizard, click the Start button.

   

4. For Select Data Source, choose one option for obtaining data about the relying party: import from a URL, import from a file, or enter manually. URL and file options require that you obtain the metadata from your organization. If you don't have access to the metadata URL or file, you can enter the information manually. In some cases, entering the data manually may be the easiest option.
   • Import data about the relying party published online or on a local network

     This option uses the URL metadata of your Portal for ArcGIS organization. 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 AD FS server in the Webapp URL field. Selecting any other option, such as IP Address or IP Address of this request's origin, is not supported and may generate an invalid token.

     Note:

     The arcgis portion of the above sample URL is the default name of the Web Adaptor application. If your Web Adaptor is named something other than arcgis, replace this portion of the URL with the name of your Web Adaptor.

   • Import data about the relying party from a file

     

     This option uses a metadata.xml file from your Portal for ArcGIS organization. There are two ways you can get a metadata XML file:

     • In the Security section of the Edit Settings page for your organization, click the Get Service Provider button. This gives the metadata for your organization, which you can save as an XML file on your computer.
     • Open the URL of the metadata of your Portal for ArcGIS organization 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 on the Generate Token page, specify the fully qualified domain name of the AD FS server in the Webapp URL field. Selecting any other option, such as IP Address or IP Address of this request's origin, is not supported and may generate an invalid token.

       Note:

       The arcgis portion of the above sample URLs is the default name of the Web Adaptor application. If your Web Adaptor is named something other than arcgis, replace this portion of the URL with the name of your Web Adaptor.

   • Enter data about the relying party manually

     

     With this option, the Add Relying Party Trust Wizard displays additional windows where you enter the data manually. These are explained in steps 6 through 8 below.

5. For Specify Display Name, enter the display name.

   

   The display name is used to identify the relying party in AD FS. Outside of this, it doesn’t have any meaning. This should be set to either ArcGIS or to the name of the organization within ArcGIS, for example, ArcGIS—SamlTest.

   Tip:

   The above image shows the Specify Display Name window with the steps for importing the data source from a URL or file. If you chose to manually enter the data source information, you see additional steps on the left side of the wizard, which are explained in steps 6 through 8 below. If you selected URL or file, you can skip to step 9.

6. (Manual data source only) For Choose Profile, choose AD FS 2.0 profile (or a later AD FS version if applicable in your environment).

   

7. (Manual data source only) For Configure URL, check the box next to Enable support for the SAML 2.0 WebSSO protocol and enter the URL for the relying party SAML 2.0 SSO service.

   The relying party URL should be the URL where AD FS sends the SAML response after authenticating the user. This should be an HTTPS URL: https://webadaptorhost.domain.com/webadaptorname/sharing/rest/oauth2/saml/signin.

   Note:

   The arcgis portion of the above sample URL is the default name of the Web Adaptor application. If your Web Adaptor is named something other than arcgis, replace this portion of the URL with the name of your Web Adaptor.

8. (Manual data source only) For Configure Identifiers, enter the URL for the relying party trust identifier.

   This should be portal.domain.com.arcgis.

9. For Choose Issuance Authorization Rules, choose Permit all users to access this relying party.

   

   Tip:

   The above image shows the Choose Issuance Authorization Rules window with the steps for importing the data source from a URL or file. If you chose to manually enter the data source information, you see additional steps on the left side of the wizard.

10. For Ready to Add Trust, review all the settings for the relying party. The metadata URL is only populated if you chose to import the data source from a URL. The image below shows the Ready to Add Trust window if you chose to manually enter data source information.

    

    Click Next.

    Tip:

    If the Monitor relying party option is enabled, AD FS will periodically check the federating metadata URL and compare it with the current state of the relying party trust. However, monitoring will fail once the token in the federating metadata URL expires. Failures are recorded in the AD FS event log. To suppress these messages, it is recommended that you disable monitoring or update the token.

11. For Finish, check the box to automatically open the Edit Claim Rules dialog box after you click the Close button.

    

    Tip:

    The above image shows the Finish window with the steps for importing the data source from a URL or file. If you chose to manually enter the data source information, you see additional steps on the left side of the wizard.

12. To set the claim rules, open the Edit Claim Rules wizard and click Add Rule.

    

13. From Select Rule Template, select the Send LDAP Attributes as Claims template for the claim rule you want to create and click Next.

    

14. From Configure Claim Rule, provide a name for the rule, for example, DefaultClaims.
    1. For Attribute store, select Active Directory.
    2. For Mapping of LDAP attributes to outgoing claim types, select the LDAP attribute that contains the user names (for example, SAM-Account-Name) for LDAP Attribute and NameID for Outgoing Claim Type.

       Note:

       NameID is the attribute that must be sent by AD FS in the SAML response to make the federation with 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.

15. Portal for ArcGIS supports flow-in of the givenName and 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.

    Follow the instructions below to edit the claims rules.

    

    • In the LDAP Attribute column, choose Display Name (or a different attribute from the list in the second row) and map it to Given Name in the Outgoing Claim Type column.
    • In the LDAP Attribute column, choose E·Mail-Addresses and map it to E·Mail Address in the Outgoing Claim Type column.

    With this claim, AD FS sends attributes with the names givenname and email to Portal for ArcGIS after authenticating the user. Portal for ArcGIS then uses the values received in the givenname and email attributes and populates the full name and the email address of the user account.

    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.

16. Click Finish to finish configuring the AD FS identity provider to include Portal for ArcGIS as a relying party.

IDP initiated logins

After configuring AD FS as the identity provider for your organization, you have the option to leverage IDP-initiated enterprise logins. You'll need to enable IDP logins in order to initiate IDP logins in AD FS and Portal for ArcGIS. If you haven't done so already, follow the steps below to enable IDP logins in AD FS. Portal for ArcGIS supports IDP logins by default, so there are no additional configuration steps necessary in Portal for ArcGIS; only configuration in AD FS is necessary.

1. Enable AD FS to send the RelayState parameter in the web.config file. The parameter is used to identify the specific resource the user will access after they are signed in.
   1. Open the web.config file. By default, the file is located at C:\inetpub\adfs\ls\.
   2. Add the following entry to the microsoft.identityServer.web section of the web.config file:

      <microsoft.identityServer.web>
          ...
          <useRelayStateForIdpInitiatedSignOn enabled="true" />
      </microsoft.identityServer.web>

2. Generate the RelayState parameter. AD FS requires two pieces of information to generate RelayState:
   1. Relying party identifier (RPID)—This indicates the relying party identifier of your Portal for ArcGIS organization configured in AD FS. To get this, open the properties of your Portal for ArcGIS relying party from the AD FS management console (for example webadaptorhost.domain.com).

      

   2. RelayState—This is the portal URL where the user is redirected after successfully logging in at the AD FS site (for example, https://webadaptorhost.domain.com/webadaptorname/).
3. Generate the RelayState parameter by defining the values for RPID and RelayState.
4. Encode the values for RPID and RelayState, for example:
   • RPID: webadaptorhost.domain.com.webadaptorname
   • RelayState: https%3A%2F%2Fwebadaptorhost.domain.com%2Fwebadaptorname%2F
5. Merge the encoded values you created in the previous step into a single string (for example, RPID=webadaptorhost.domain.com.webadaptorname&RelayState=https%3A%2F%2Fwebadaptor.domain.com%2Farcgis%2F).
6. Encode the merged string (for example, RPID%3Dwebadaptorhost.domain.com.webadaptorname%26RelayState%3D%20https%253A%252F%252Fwebadaptorhost.domain.com%252Fwebadaptorname%252F).
7. Add the RelayState parameter to the string and append to the IDP initiated SSO URL of AD FS (for example, https://idphost.test.com/adfs/ls/idpinitiatedsignon.aspx?RelayState=RPID%3Dwebadaptorhost.domain.com.webadaptorname%26RelayState%3D%20https%253A%252F%252Fwebadaptorhost.domain.com%252Fwebadaptorname%252F). This is the URL that will be used to initiate a login at your AD FS site.

When the user logs in and authenticates successfully, AD FS will generate a SAML response and pass the RelayState with the URL of your organization to Portal for ArcGIS. The portal validates the SAML response and redirects the user to the organization and its resources.