Configure SimpleSAMLphp

You can configure SimpleSAMLphp 1.10 and later versions as your identity provider (IDP) 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 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 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 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 SimpleSAMLphp as the enterprise identity provider with Portal for ArcGIS

1. Configure an authentication source in the SimpleSAMLphp IdP.
   1. Create an authentication source.

      SimpleSAMLphp supports authenticating users from various authentication sources such as LDAP server, users in an SQL server, Active Directory domain, and so on. The example below shows how to configure an Apache Directory Server as an authentication source in SimpleSAMLphp IdP.

      Authentication sources can be configured in the <SimpleSAML_HOME>/config/authsources.php file. To configure the LDAP server, open the config/authsources.php file and add an LDAP-based authentication source in the following format.

      'example-ldapApacheDS' => array(
      		'ldap:LDAP',
      
      		/* The hostname of the LDAP server. */
      		'hostname' => 'host:port',
      
      		/* Whether SSL/TLS should be used when contacting the LDAP server. */
      		'enable_tls' => TRUE,
      
      		/*
      		 * Which attributes should be retrieved from the LDAP server.
      		 * This can be an array of attribute names, or NULL, in which case
      		 * all attributes are fetched.
      		 */
      		'attributes' => NULL,
      
      		/*
      		 * The pattern that should be used to create the users DN given the username.
      		 * %username% in this pattern will be replaced with the user's username.
      		 *
      		 * This option is not used if the search.enable option is set to TRUE.
      		 */
      		'dnpattern' => 'uid=%username%,ou=users,ou=system',
      
      		/*
      		 * As an alternative to specifying a pattern for the users DN, it is possible to
      		 * search for the username in a set of attributes. This is enabled by this option.
      		 */
      		'search.enable' => FALSE,
      
      		/*
      		 * The DN that will be used as a base for the search.
      		 * This can be a single string, in which case only that DN is searched, or an
      		 * array of strings, in which case they will be searched in the order given.
      		 */
      		'search.base' => 'ou=users,ou=system',
      
      		/*
      		 * The attribute(s) the username should match against.
      		 *
      		 * This is an array with one or more attribute names. Any of the attributes in
      		 * the array may match the value the username.
      		 */
      		'search.attributes' => array('uid', 'mail'),
      
      		/*
      		 * The username & password the simpleSAMLphp should bind to before searching. If
      		 * this is left as NULL, no bind will be performed before searching.
      		 */
      		'search.username' => 'uid=admin,ou=system',
      		'search.password' => 'password',
      	),

      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.

      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.

   2. Configure the authentication source you created above as an authentication module in the SimpleSAMLphp IdP. Open the metadata/ saml20-idp-hosted.php file and add the authentication source to use.

      /*
      	 * Authentication source to use. Must be one that is configured in
      	 * 'config/authsources.php'.
      	 */
      	'auth' => 'example-ldapApacheDS',

2. Configure the name identifier format supported by the SimpleSAMLphp IdP. Open the < SimpleSAML_HOME >/metadata/saml20-idp-hosted.php file and add the snippet below. In the following example, uid will be passed as NameID by the SimpleSAMLphp IdP to Portal for ArcGIS after authenticating the user.

   'NameIDFormat' => 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent',
   		'authproc' => array(
   
   			  3 => array(
   
   			  'class' => 'saml:AttributeNameID',
   			  'attribute' => 'uid',
   	              'Format' => 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent',
   				  ),
   			),

3. Register SimpleSAMLphp as the identity provider for your Portal for ArcGIS organization.
   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 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 three options below:

      URL—Choose this option if the URL of the SimpleSAMLphp federation metadata is accessible. This is usually https://<simpleSAML-server>/<saml-app-name>/saml2/idp/metadata.php.

      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, use 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. Save the metadata from the URL as an XML file and upload the file to Portal for ArcGIS using the File option.

      Parameters—Choose this option if the URL or file is not accessible. Enter the values manually and supply the requested parameters: login URL and certificate. Contact your SimpleSAMLphp administrator to obtain these.

4. Configure the advanced settings as applicable:
   • Encrypt Assertion—Select this option if SimpleSAMLphp 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 SimpleSAMLphp.
   • Entity ID—Update this value to use a new entity ID to uniquely identify your portal to SimpleSAMLphp.
   • Propagate logout to Identity Provider—Select this option to have Portal for ArcGIS use a Logout URL to sign out the user from SimpleSAMLphp. 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.
   • Logout URL—The identity provider URL to use to sign out the currently signed in user. The logout URL is usually https://idphost.domain.com/simplesaml/saml2/idp/SingleLogoutService.php. This URL is defined in the SingleLogoutService element in the IDP's metadata file. The metadata file URL is usually http://[simpleSAML-server]/simplesaml/saml2/idp/metadata.php.

   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. 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://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.

      • 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": "ldaps://bar2:10636/ou=users,ou=ags,dc=example,dc=com",
            "ldapURLForRoles": "ldaps://bar2:10636/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 ldapURLForRoles parameters. The URL to your LDAP will need to be provided by your LDAP administrator.

        In the above example, the LDAP URL refers to users within a specific OU (ou=users). If users exist in multiple OUs, the LDAP URL can point to a higher level OU or even the root level if needed. In that case, the URL would instead look like this:

        "ldapURLForUsers": "ldaps://bar2:10636/dc=example,dc=com",

        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 SimpleSAMLphp

1. Configure Portal for ArcGIS as a trusted service provider with SimpleSAMLphp by configuring the <SimpleSAMLphp_HOME>/metatadata/saml20-sp-remote.php file.
   1. Obtain the metadata XML file of your Portal for ArcGIS organization.

      To get the metadata file, sign in as an administrator of your organization and open your organization page. Click the Edit Settings button, click the Security tab, and in the Enterprise Logins section, click the Get Service Provider button.

   2. Convert the XML file you obtained in the previous substep to PHP format.

      SimpleSAMLphp expects the service provider’s metadata information to be provided in PHP format. SimpleSAMLphp provides a built-in XML-to-PHP metadata converter which, by default, is available as https://<simpleSAML-server>/<saml-app-name>/admin/metadata-converter.php in your simpleSAMLphp installation. Use the converter to convert the XML to PHP.

   3. Open the metatadata/saml20-sp-remote.php file and add the configuration of the service provider in PHP format created in step 1.b above.

      Below is an example of the added service provider's configuration in the metadata file.

      /* The following is a Portal for ArcGIS organization service provider */
      $metadata['webadaptorhost.domain.com.webadaptorname'] = array (
        'entityid' => ' webadaptorhost.domain.com.webadaptorname',
        'name' =>
        array (
          'en' => 'portal ',
        ),
        'description' =>
        array (
          'en' => 'portal ',
        ),
        'OrganizationName' =>
        array (
          'en' => 'portal ',
        ),
        'OrganizationDisplayName' =>
        array (
          'en' => 'portal ',
        ),
        'url' =>
        array (
          'en' => 'https://webadaptorhost.domain.com/webadaptorname',
        ),
        'OrganizationURL' =>
        array (
          'en' => 'https://webadaptorhost.domain.com/webadaptorname',
        ),
        'contacts' =>
        array (
        ),
        'metadata-set' => 'saml20-sp-remote',
        'AssertionConsumerService' =>
        array (
          0 =>
          array (
            'Binding' => 'urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST',
            'Location' => 'https://webadaptorhost.domain.com/webadaptorname/sharing/rest/oauth2/saml/signin',
            'index' => 1,
          ),
          1 =>
          array (
            'Binding' => 'urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect',
            'Location' => 'https://webadaptorhost.domain.com/webadaptorname/sharing/rest/oauth2/saml/signin',
            'index' => 2,
          ),
        ),
        'SingleLogoutService' =>
        array (
        ),
      );

2. Configure the attribute that gets passed as NameID to Portal for ArcGIS from the SimpleSAMLphp IdP after authenticating the user. To do this, add the attribute at the end of the service provider’s configuration you added in the previous step.

   In the following example, uid is passed as NameID by the SimpleSAMLphp IdP to Portal for ArcGIS after authenticating the user. (Replace webadaptorhost.domain.com.webadaptorname with the URL of your portal.)

   'NameIDFormat'               => 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent',
   'simplesaml.nameidattribute' => 'uid',
   
   /* The following indicates whether or not to send all the attributes received from the authentication source to the service provider.
     If true, it will send, otherwise it will not send all the attributes*/
   
     'simplesaml.attributes'      => true,
   );

3. If you chose the advanced setting Encrypt Assertion when registering SimpleSAMLphp as the enterprise identity provider, add the attribute below to the end of the service provider’s configuration you added in step 1.

   /*
     Whether assertions sent to this SP should be encrypted. The default value is FALSE.
     */
     'assertion.encryption' => true,
   );