SAML single sign-on configuration overview

Chapter 46 Configurin uring Drupal Configure the Drupal Web-SAML application profile in Cloud Manager to set up single sign-on via SAML with a Drupal-based web application. Configuration also specifies how the application appears in the user portal, which users may access the application, if the application requires additional authorization, and how your internal user accounts are mapped to Drupal accounts. Other application profile controls record and report changes to settings. For general information about single sign-on (SSO) configuration, see Overview. Preparing for configuration Before starting configuration, it helps to understand the basic steps of configuration, to know Drupal s single sign-on (SSO) characteristics, and to have everything you need for configuration in place. SAML single sign-on configuration overview Drupal offers both IdP-initiated SAML SSO (for SSO access through the user portal or Centrify mobile apps) and SP-initiated SAML SSO (for SSO access directly through Drupal). You can configure Drupal for both types of SSO. To configure Drupal for single sign-on: 1 In Cloud Manager, add the Drupal application profile if it s not already added and set the security certificate. You ll need information in the application profile to set up SSO. For detailed information, see "Adding Drupal and setting a security certificate" on page 46-38. 2 Ensure that your web application s server has the necessary components to support SAML SSO for Drupal: Install the components if they re not present. For detailed information, see "Preparing the server" on page 46-41. Configure the components. For detailed information, see "Configuring simplesamlphp" on page 46-41. 3 On your application s web site, configure the application for SSO via SAML. For detailed information, see "Configuring the web application" on page 46-43. 36

Preparing for configuration 4 In Cloud Manager, configure the Drupal application profile to control how access for your Drupal-based application works through the user portal or Centrify mobile apps. For detailed information, see "Configuring a Drupal-based web application in Cloud Manager" on page 46-45. Requirements ements for SSO configuration Before you can configure a Drupal-based web application for SSO, you need the following: An active account with administrator rights for the web application s server. An active account with administrator rights for the web application. A signed security certificate that is recognized by both Cloud Manager and Drupal. Security certificates for SSO A secure connection for SSO between the web application and the cloud service requires a security certificate and a public and private key pair. The web application must have a security certificate containing a public key. The cloud service must have the same certificate and a private key that matches the public key in the certificate. You can use either a standard certificate provided by the cloud service or a certificate provided by your organization. If you use your own certificate, you must provide the certificate to the web application and then provide the same certificate along with your private key to Cloud Manager (both processes described later). Cloud Manager requires your private key to sign SAML responses or messages for the web application using your certificate. If you use the cloud service signing certificate (the default setting), you don t need to provide a private key simply download the standard certificate from Cloud Manager and provide it to the web application as described later. The cloud service already has the matching private key needed to sign messages using the certificate. Drupal SSO characteristics When you configure a Drupal-based web application for SSO and then administer it for your organization, it s useful to know its SSO characteristics. Feature Available versions and clients SP-initiated SSO support IdP-initiated SSO support Description SAML web application only. Yes. Users may sign directly into a Drupal-based web application and then use cloud service SSO to authenticate. Yes. Users may use SSO to sign into a Drupal-based web application through the user portal or Centrify mobile apps. Cloud Manager user s guide 37

Adding Drupal and setting a security certificate Feature User name/password sign-in still available after SSO set up Separate sign-in for administrators after SSO is enabled Lockout possibility and lockout recovery User provisioning through SAML User types Users may reset their own passwords Administrators may reset other users passwords Description Configurable under SimpleSAMLphp Auth Settings. DRUPAL AUTHENTICATION > Allow authentication with local Drupal accounts. If so configured. User name/password sign-in is always available, so lockout after enabling SSO is not a problem. Supported. You can set the web application to create a new user account for every user who authenticates the first time through SSO. Anonymous user, authenticated user, administrator, and any other roles defined by an administrator. Yes. Yes. Adding Drupal and setting a security certificate Before you can configure your Drupal-based web application for SSO and configure the Drupal application profile, you must add a Drupal application in Cloud Manager. You must then decide which security certificate to use. If you re going to use your organization s certificate for connections to Drupal, you must supply that certificate along with its matching private key in a PKCS #12 archive file. (PKCS #12 files end in a.pfx or.p12 filename extension.) Make sure the file is accessible from your computer before working through these steps. To add a Drupal-based application and set its security certificate: 1 In Cloud Manager, click Apps. 2 Click Add Web Apps. The Add Web Apps screen appears. 3 On the Search tab, enter the partial or full application name in the Search field and click the search icon. 4 Next to the application, click Add. 5 In the Add Web App screen, click Yes to confirm. Cloud Manager adds the application. 6 Click Close to exit the Application Catalog. The application that you just added opens to the Application Settings page. Chapter 46 Configuring Drupal 38

Adding Drupal and setting a security certificate The bottom of the page displays current security certificate settings. It s set by default to use the standard cloud service certificate. If you want to use this standard certificate, skip to Step 11. 7 If you want to use your own security certificate, select Use a certificate with a private key (pfx file) from your local storage then click Browse to open a file browser. 8 Locate the archive file containing your certificate and private key, then click Open. 9 If prompted for a certificate password for the archive file, enter the password then click OK. The archive file uploads to the cloud service and the Application Settings page shows an uploaded private certificate under Use existing certificate. 10 Click Save to save your certificate setting to the application profile. 11 Download a copy of the security certificate specified by the application profile: click Download. The certificate downloads through your web browser to a location set by the browser. Remember the location. 12 Configuration steps later require the fingerprint of the certificate you just downloaded, which you can obtain through different tools. In Windows, open the certificate file with Crypto File Extensions (the default application for certificates). Cloud Manager user s guide 39

Configuring a Drupal-based web application for SSO 13 Click the Details tab, scroll to the bottom of the fields to see the thumbprint field (Microsoft s term for fingerprint), then click the field. The certificate s fingerprint appears in the text box below the fields. 14 Select and copy the fingerprint value, paste it into a text editor, and remove the spaces from the value. Save the fingerprint value to use later during configuration. You can change to a different certificate at any time by making a different choice under the Security Certificate settings as just described. To change from a private certificate to the cloud service standard certificate: 1 In the Applications Settings page select Use the default tenant signing certificate 2 Click Save. Remember that if you change the certificate in the application profile you must also upload your new certificate s fingerprint to the Drupal-based web application as described in the next section. Configuring ng a Drupal-based web application for SSO Before you can configure a Drupal-based web application for SSO, you must enable its server to handle SAML. Chapter 46 Configuring Drupal 40

Configuring a Drupal-based web application for SSO Preparing the server A Drupal-based web application can t provide SAML-based SSO unless its server has the necessary authentication applications and modules installed. These instructions describe how to install the applications and modules if they re not already installed. To prepare a Drupal-based web application for SAML SSO: 1 Download and install simplesamlphp on your application server and set it up as a service provider (SP). https://simplesamlphp.org/docs/1.11/simplesamlphp-install provides links to download the extension and instructions for installing and setting up the application. 2 Download and install Memcache. Memcache is required to store sessions for the simplesamlphp Authentication module installed in the next step. https:// www.digitalocean.com/community/articles/how-to-install-and-use-memcache-onubuntu-12-04 provides instructions for installing and setting up the application. 3 Download and install the simplesaml php Authentication module for Drupal. This module integrates simplesamlphp with your Drupal-based web application. https:// drupal.org/project/simplesamlphp_auth provides links to download the module and instructions for installing and setting up the module. Configuring ing simplesamlphp Once your server is prepared with all the components necessary for SAML authentication through Drupal, you must configure simplesamlphp through an SSH connection to the server. The instructions at http://simplesamlphp.org/docs/1.8/simplesamlphp-sp give overall instructions for SAML configuration that sets up your Drupal-based application as a SAML service provider (SP). The following instructions provide specific configuration values to set up the cloud service as an identity provider (IdP). Some of the values come from the Drupal application profile in Cloud Manager, so if it s not already open, open it and view its Application Settings page. To configure simplesamlphp for cloud service SSO: 1 Log into the web application s server via SSH. 2 Open the configuration file /var/simplesamlphp/config/config.php with a text editor. 3 Set simplesamlphp to store sessions using Memcache: 'store.type' => 'memcache' 4 Save the configuration file. 5 Open the configuration file /var/simplesamlphp/config/authsources.php with a text editor. Cloud Manager user s guide 41

Configuring a Drupal-based web application for SSO 6 Under the array 'default-sp' add this entry to specify your Drupal-based web application as the SAML service provider. (If you ve already set this entry, there s no need to change it.) 'entityid' => '<URL of your Drupal web application>' where <URL of your Drupal web application> is the URL that accesses your web application. 7 In Cloud Manager, set the field Your Drupal instance URL to match exactly the value you used to set entityid in authsources.php. If, for example, the entry in authsources.php reads entityid => https://portal.acme.com, set Your Drupal instance URL to https://portal.acme.com. 8 Add another entry to the array default-sp, this time to specify the cloud service as the SAML identity provider: 'idp' => '<Entity ID of the IdP>' where <Entity ID of the IdP> matches exactly the value in the Entity ID of the IdP field in the Drupal application profile. Note that because you can change the value of the field to whatever you want, you can use any value as long as it s exactly the same in both the configuration file and the application profile. Most people use the default value in the application profile. Here s an example of the two added entries to default-sp : 'default-sp' => array( 'saml:sp', 'privatekey' => 'saml.pem', 'certificate' => 'saml.crt', 'entityid' => 'https://portal.acme.com', 'idp' => 'https://cloud.centrify.com/saml/drupal', 'discourl' => NULL, ), 9 Save the configuration file. 10 Open the configuration file /var/simplesamlphp/metadata/saml20-idp-remote.php with a text editor. 11 Add this metadata array to the configuration file: $metadata['<entity ID of the IdP>'] = array( 'SingleSignOnService' => '<Single Sign-On Service>', 'SingleLogoutService' => '<Single Logout Service>', 'certfingerprint' => '<Centrify certificate fingerprint>', ); Chapter 46 Configuring Drupal 42

Configuring a Drupal-based web application for SSO Use these values to fill in the array: Variable <Entity ID of the IdP> <Single Sign-On Service> <Single Logout Service> <Centrify certificate fingerprint> Value The field of the same name in the Drupal application profile. The field of the same name in the Drupal application profile. The field of the same name in the Drupal application profile. The fingerprint of the certificate you downloaded earlier in Step 11 of a previous procedure. 12 Save the configuration file. 13 Log out of the server. Configuring the web application ation Once you ve set up and configured the server for your Drupal-based web application, you can configure the web application itself. You must be signed into the web application with administrator rights to perform these steps. To configure a Drupal-based web application for SSO: 1 In your web browser, go to the URL for your web application home page (this should be the same URL you supplied earlier for the entityid configuration parameter) and sign in with your administrator account. 2 Click Configuration at the top of the page to open the Configuration page. Cloud Manager user s guide 43

Configuring a Drupal-based web application for SSO 3 Click SimpleSAMLphp Auth Settings in the People section to open the SAML authentication page. 4 Specify the following for the SSO Settings: Option Activate authentication via SimpleSAMLphp Installation directory Authentication source for this SP Force https for login links Which attribute from simplesamlphp should be used as user s name Value Check this option. Leave set to the default value. Leave set to the default value. Leave checked. Set to username. Chapter 46 Configuring Drupal 44

Configuring a Drupal-based web application in Cloud Manager Option Which attribute from simplesamlphp should be used as unique identifier for the user All other options 5 Click Save configuration. 6 Sign out of your web application account. SP-Initiated SSO Value Set to id. Leave set to default values. When you set up SSO on a Drupal-based web application, SP-initiated SSO is automatically enabled. To use it, point a browser to https://<your application URL>/?q=saml_login where <your application URL> is the URL you use to sign into your application with user name and password. For example, https://portal.acme.com/?q=saml_login. The browser redirects to the cloud service for sign-in. SP-initiated SSO does not lock out sign-in with user name and password. All users may log in with user name and password at the standard web application URL. Configuring ng a Drupal-based web application in Cloud Manager Use Cloud Manager to configure the application profile for your Drupal-based web application. Configuring specifies how the application appears in the user portal and who has access to the application. Some configuration is required to deploy the web application; other configuration is optional. The steps following describe all configuration settings and mark those that are optional. Once you finish configuring the application profile and save your changes, your Drupalbased application is deployed and appears as a deployed application in Cloud Manager. To configure a Drupal application profile in Cloud Manager: 1 If the Drupal application profile isn t open in Cloud Manager, click the Apps tab to view all added applications, then click Drupal Web-SAML to open its application profile. 2 On the Description page, change the name, description, and logo to match your web application if you haven t done so already. Your users may have access to more than one Drupal-based web application, so customizing the name and icon for each is a good idea. Cloud Manager user s guide 45

Configuring a Drupal-based web application in Cloud Manager 3 On the Application Settings page, the following settings are unique to this application. Some of them are read-only so you don t need to set them: Option Your Drupal instance URL Entity ID of the IdP Single Sign-On Service Single Logout Service Value Change this value to the URL used to point to your web application s home page. This value must match the entityid parameter in the configuration file /var/simplesamlphp/ config/authsources.php as described earlier. This value must match the IdP parameter in the configuration file /var/simplesamlphp/config/authsources.php as described earlier. You can enter whatever string you wish here, but most people use the default string. Use this value for the SingleSignOnService metadata parameter in the configuration file /var/simplesamlphp/ metadata/saml20-idp-remote.php as described earlier. Use this value for the SingleLogoutService metadata parameter in the configuration file /var/simplesamlphp/ metadata/saml20-idp-remote.php as described earlier. 4 On the Application Settings page, expand the Additional Options section and specify the following settings: Option Application ID Description Configure this field if you are deploying a mobile application that uses the Centrify mobile SDK, for example mobile applications that are deployed into a Samsung KNOX version 1 container. The cloud service uses the Application ID to provide single sign-on to mobile applications. Note the following: The Application ID has to be the same as the text string that is specified as the target in the code of the mobile application written using the mobile SDK. If you change the name of the web application that corresponds to the mobile application, you need to enter the original application name in the Application ID field. There can only be one SAML application deployed with the name used by the mobile application. The Application ID is case-sensitive and can be any combination of letters, numbers, spaces, and special characters up to 256 characters. Chapter 46 Configuring Drupal 46

Configuring a Drupal-based web application in Cloud Manager Option Show in User app list Security Certificate Description Select Show in User app list so that this web application displays in the user portal. (By default, this option is selected.) If this web application is only needed in order to provide SAML for a corresponding mobile application, deselect this option. This web application won t display for users in the user portal. These settings specify the signing certificate used for secure SSO authentication between the cloud service and the web application. Just be sure to use a matching certificate both in the application settings in the Cloud Manager and in the application itself. Select an option to change the signing certificate. Use existing certificate When selected the certificate currently in use is displayed. It s not necessary to select this option it s present to display the current certificate in use. Use the default tenant signing certificate Select this option to use the cloud service standard certificate. This is the default setting. Use a certificate with a private key (pfx file) from your local storage Select this option to use your organization s own certificate. To use your own certificate, you must click Browse to upload an archive file (.p12 or.pfx extension) that contains the certificate along with its private key. If the file has a password, you must enter it when prompted. 5 (Optional) On the Description page, you can change the name, description, and logo for the application. For some applications, the name cannot be modified. The Category field specifies the default grouping for the application in the user portal. Users have the option to create a tag that overrides the default grouping in the user portal. 6 On the User Access page, select the role(s) that represent the users and groups that have access to the application. When assigning an application to a role, select either Automatic Install or Optional Install: Select Automatic Install for applications that you want to appear automatically for users. If you select Optional Install, the application doesn t automatically appear in the user portal and users have the option to add the application. 7 (Optional) On the Policy page, specify additional authentication control for this application.you can select one or both of the following settings: Restrict app to clients within the Corporate IP Range: Select this option to prevent users outside the company intranet from launching this application. To use this Cloud Manager user s guide 47

Configuring a Drupal-based web application in Cloud Manager option, you must also specify which IP addresses are considered as your intranet by specifying the Corporate IP range in Settings > Corporate IP Range. Require Strong Authentication: Select this option to force users to authenticate using additional, stronger authentication mechanisms when launching an application. Specify these mechanisms in Policy > Add Policy Set > Account Security Policies > Authentication. You can also include JavaScript code to identify specific circumstances when you want to block an application or you want to require additional authentication methods. For details, see Specifying application access policies with JavaScript. 8 On the Account Mapping page, configure how the login information is mapped to the application s user accounts. The options are as follows: Use the following Directory Service field to supply the user name: Use this option if the user accounts are based on user attributes. For example, specify an Active Directory field such as mail or userprincipalname or a similar field from the Centrify user service. Everybody shares a single user name: Use this option if you want to share access to an account but not share the user name and password. For example, some people share an application developer account. Use Account Mapping Script: You can customize the user account mapping here by supplying a custom JavaScript script. For example, you could use the following line as a script: LoginUser.Username = LoginUser.Get('mail')+'.ad'; The above script instructs the cloud service to set the login user name to the user s mail attribute value in Active Directory and add.ad to the end. So, if the user s mail attribute value is Adele.Darwin@acme.com then the cloud service uses Adele.Darwin@acme.com.ad. For more information about writing a script to map user accounts, see the SAML application scripting guide. On the App Gateway page, you can configure the application so that your users can access it whether they are logging in from an internal or external location. For applications configured for the App Gateway, users do not have to use a VPN connection to access the application remotely. Note The App Gateway feature is a premium feature and is available only in the Centrify Identity Service App+ Edition. Please contact your Centrify representative to have the feature enabled for your account. Note Some applications can be used with App Gateway; not all applications are set up to use this feature. At this time, Web applications may use HTTPS or HTTP, and either the standard port of 443 or a non-standard port. IP addresses are only supported for onpremise apps and are not supported for external-facing apps. Chapter 46 Configuring Drupal 48

Configuring a Drupal-based web application in Cloud Manager 9 (Optional) To enable App Gateway mode, select Make this application available via the internet. The Centrify identity platform verifies the application settings and displays the URL that you provided in application settings as the internal URL for the application. 10 Specify the external URL that users open to access the application from external locations. You can use an existing external URL or use one that the cloud service generates automatically for you. If you use an existing external URL, any links to the application URL do not need to change and will continue to work as is. However, you do need to upload an SSL certificate and modify your DNS settings. To use your existing external URL, select the first option and do the following: a b Enter the existing external URL. You can enter an internal or external URL here. Click Upload to browse to and upload your SSL certificate with the private key for the URL that you entered. The certificate file has either a.pfx or.p12 filename extension. To use the auto-generated external URL, select the second option. Later, you ll need to be sure to notify your users of the updated URL to use. 11 Select a cloud connector to use with the application at the Cloud connectors to use with this service section. Choose one of the following: Any available Select this option to allow the Centrify Identity Service to randomly select one of the available cloud connectors for your App Gateway configuration. Click Test Connection to make sure the connection between the cloud connector and the application is successful. Choose Select this option to specify one or more cloud connectors to use for your App Gateway configuration. If you select more than one cloud connector, the Centrify Identity Service randomly chooses one of the selected cloud connectors to use for the application. Once the configuration is saved, each future App Gateway request uses a random cloud connector from those selected, as long as the cloud connector is online. Once you select the cloud connectors you want to use, click Test Connection to make sure the connection between the selected cloud connectors and the application is successful. At least one cloud connector must succeed in order to save the configuration. Note If any of the cloud connectors are offline, they are not displayed in the list of available cloud connectors. 12 Click Save to save the App Gateway changes. Cloud Manager user s guide 49

Configuring a Drupal-based web application in Cloud Manager Note If you configured the application to use an external URL, next you edit your DNS settings to accommodate the App Gateway connection to this application. You ll enter a CNAME record to map this URL to the application s gateway connection URL. For more information about configuring App Gateway and troubleshooting App Gateway connection issues, see "Configuring an application to use the App Gateway" on page 3-25 and "Troubleshooting" on page 3-28. 13 (Optional) On the Advanced page, you can edit the script that generates the SAML assertion, if needed. In most cases, you don t need to edit this script. For more information, see the SAML application scripting guide. On the Changelog page, you can see recent changes that have been made to the application settings, by date, user, and the type of change that was made. Note 14 Click Workflow to set up a request and approval work flow for this application. The Workflow feature is a premium feature and is available only in the Centrify Identity Service App+ Edition. See Configuring Workflow for more information. 15 Click Save. After configuring the application settings (including the role assignment) and the application s web site, you re ready for users to launch the application from the user portal. Chapter 46 Configuring Drupal 50