Last updated on May 09, 2017

Single Sign On (SSO) for single and multiple-tenant deployments

The Single Sign On (SSO) integration feature for on-premises deployments allows users to seamlessly and securely connect to Appspace using a single set of credentials, simplifying username and password management.

This article provides the instructions to configure SSO with ADFS as the Identity Provider, and Appspace as the Service Provider.

• Requirements
• How SSO Works
• Install Active Directory Federation Services
• Configure SSO
• Configure ADFS Relying Party Trust
• Log in with SSO

Requirements

Active Directory Server

• Microsoft Windows Server 2012 R2.
• SSL configured.
• Windows Server Administrator credentials.

Active Directory Federation Services (ADFS)

• Can be installed on the Active Directory Server.
• SSL configured.
• Windows Server Administrator credentials.

Network

• All servers must belong to the same domain or sub domain.

Appspace Server

• Version 5.2 and above.
• SSL configured.
• Windows Server Administrator credentials.
• Appspace Portal Administrator, Account Administrator or Account Owner role
• All users created on the Appspace server must have an email.

How SSO Works

A user starts by trying to log in to Appspace. Upon accessing the login page, the user will be redirected to an SSO login page. The user will then have to authenticate his/her login credentials against the Identity Provider. Upon successful authentication, the Identity Provider will send a SAML assertion to Appspace via the web browser to allow the user to log into Appspace.

Install Active Directory Federation Services

Install the Active Directory Federation Services as per instructions from the Microsoft website: https://msdn.microsoft.com/en-us/library/azure/dn528857.aspx

Note

This can be performed on the AD server or on a separate server.

Configure SSO

1. Download the Identity Provider (ADFS) metadata. Open a browser and key in the URL https://<ADFS FQDN or IP>/FederationMetadata/2007-06/FederationMetadata.xml.

   Note

   This metadata is used by the Identity Provider (ADFS) to recognize the Service Provider (Appspace). This process involves downloading the metadata file in XML format, uploading to and re-downloading from Appspace, and finally uploading it to the Identity Provider (ADFS).

2. In the Appspace menu, select System > Configuration, and click the Authentication tab.

   Note

   You’ll have to be a Portal Administrator to access the Appspace system settings.

3. Upon enabling SSO globally, the SSO configuration menu will be visible.

   
   
   

4. If the Appspace server has a valid SSL certificate installed, the SSL Certificate section will be populated automatically.

   
   
   

5. In the Appspace Tenancy section, do the following:

   • Single Tenancy

     1. Select the Single option, and configure the SSO authentication option.
     
     

   • Multi Tenancy

     1. Select the Multiple option, and click Save.
     2. Click Yes at the confirmation, and click the Apply Configuration tab.
     3. Enter in your Windows Server Administrator credentials, and click Apply. Click Yes to confirm restarting the Appspace server.
     4. For each tenanted account, navigate to Account > SSO, and configure the SSO authentication option.
   
   

6. You will be given three SSO authentication options: OFF, Optional, or Required. We’ll be selecting Optional in this example.

   

   Note

   • Optional – Users can select between using their Appspace login credentials or via SSO (AD credentials).
   • Required – Users can only login via SSO (AD credentials).

7. You will be given two SSO binding options; Redirect or POST. We’ll be using POST in this example.

   
   
   

   Note

   • Redirect – Users will be redirected to the Identity Provider. SSO details will be passed in a query string with “?SAMLRequest=……” as part of the URL.
   • Post – SSO details will not be passed through a query string but will be passed using the POST method. For this method to work, you must ensure that the Identity Provider has direct access to the Appspace server.

8. You will be given two Identity Provider (IdP) configuration methods; Use IdP Metadata or Manual.

   
   
   

   • Use IdP Metadata (automatic)

     1. Upon selecting the Use IdP Metadata option, upload the metadata XML file downloaded in Step 1 above. Browse and upload the metadata file to the Appspace server.

        
        
        

     2. The upload path will be displayed. Proceed to Step 9 below.

        
        
        

   • Use manual configuration

     1. To use the Manual configuration method, you will need to fill in the SSO URL as and the X.509 certificate details.

        
        
        

     2. Fill in the URL of the ADFS server with https://<ADFS server’s FQDN/IP>/adfs/ls/

        
        
        

     3. To fill in the X.509 certificate, locate the downloaded FederatedMetadata.xml in Step 1 and open it in a browser.

        
        
        

     4. Locate the line <X509Certificate> and copy its associated text.

        
        
        

     5. Paste the text in the X509 Certificate textbox.

        
   
   

9. In the Metadata Signing field, click the Change link to show the options.

   

   Note

   • Enabled – The SP metadata file will be generated in an ‘Encrypted’ format.
   • Disabled – The SP metadata file will be generated in a ‘Plain text’ format.

10. Optionally, you may enable Pass-through Authentication, by checking the Enable option, and entering the e-mail domain.

    

    Note

    Pass-through authentication enables you to utilize an external IdP so that your users can access channels through the Appspace App without using Premium User IDs.

11. Click Save once done.

12. Click Yes in the Confirmation window to save settings.

13. The ‘Appspace changes detected. Click Here to apply your settings’ status message will be displayed at the top of the page. Click the ‘Click Here’ link.

14. In the Apply Configuration page, enter the Appspace installation server credentials, and click Apply.

    
    
    

15. Click Yes in the Confirmation window to restart Appspace.

16. From the Authentication tab, click Download to download the Service Provider’s metadata file.

    
    
    

17. Copy and paste the file to a desired location on your Identity Provider (ADFS) server.

Configure ADFS Relying Party Trust

Note

This section is performed on the Identity Provider (ADFS) server.

1. Configure the ADFS Relying Party Trust as per instructions on the “To create a claims aware Relying Party Trust using federation metadata” section on the Microsoft website: https://docs.microsoft.com/en-gb/windows-server/identity/ad-fs/operations/create-a-relying-party-trust#to-create-a-claims-aware-relying-party-trust-using-federation-metadata

   1. In Step 4 of the instructions, on the Select Data Source page, select the ‘Import data about the relying party from file’ option,

   2. Select the Service Provider’s metadata file that was downloaded from the Appspace server earlier.

   3. Click Next and continue with Step 5 to specify Display Name.

      
      

2. In the Edit Claims Rules dialog box, create a rule as per instructions on the “To create a rule to send LDAP attributes as claims for Windows Server 2012 R2” section on the Microsoft website: https://docs.microsoft.com/en-gb/windows-server/identity/ad-fs/operations/create-a-rule-to-send-ldap-attributes-as-claims#to-create-a-rule-to-send-ldap-attributes-as-claims-for-windows-server-2012-r2

   1. In Step 4, in the Edit Claim Rules dialog box, select the ‘Issuance Transform Rules’ tab, and click Add Rule.

   2. In Step 6, on the Configure Rule page, map the LDAP attributes to outgoing types value as below:

      LDAP Attribute	Outgoing Claim Type
      E-Mail-Addresses	E-Mail Address
      SAM-Account-Name	Windows account name

      Note

      All Appspace users authenticating via SSO are required to have email addresses (can be used as the usernames as well).

3. In the Edit Claims Rules dialog box, create a rule as per instructions on the “To create a rule to transform an incoming claim in Windows Server 2012 R2” section on the Microsoft website: https://docs.microsoft.com/en-gb/windows-server/identity/ad-fs/operations/create-a-rule-to-transform-an-incoming-claim#to-create-a-rule-to-transform-an-incoming-claim-in-windows-server-2012-r2

   1. In Step 4, in the Edit Claim Rules dialog box, select the ‘Issuance Transform Rules’ tab, and click Add Rule.

   2. In Step 6, on the Configure Rule page, configure the claim types as follows:

      Incoming claim type	E-Mail Address
      Outgoing claim type	Name ID
      Outgoing name ID format	Transient Identifier

4. In the menu tree, click Relying Party Trusts, and select your display name.

5. Click the Advanced tab, and select SHA-1 as the secure hash algorithm from the drop-down menu.

   
   
   

6. Click Apply, and OK once done.

Log in with SSO

1. At the Appspace login page, log in with your username (This should be an email), and you will be redirected to the SSO login page provided by your Identity Provider.

   Warning

   You must use HTTPS for SSO to work.

2. Enter your Appspace credentials. Upon successful authentication, you will be redirected back to your Appspace dashboard.