Single sign-on is a method for authenticating users where a single set of credentials is used for logging into several different applications. This is especially convenient in a corporate environment, allowing your employees access to many third-party applications, like Worksuite, using their own company credentials.


TABLE OF CONTENTS


Worksuite's Support of SSO

SSO authentication is available to Worksuite 'Enterprise' account customers. Worksuite supports SSO using the SAML 2.0 standard and acts as a service provider (SP) for SSO. The customer must implement a federation service to act as an Identify Provider (IdP) - either via in-house or third-party provider.

Common third-party IdP (SSO) vendors include:

  • Microsoft Azure
  • Okta
  • Google Cloud
  • OneLogin


Setting up SSO


Prerequisites:
- Customers must have an Enterprise Worksuite account
- Request to enable SSO via Customer Success


Step-by-step

  1. Sign in to your Identify Provider's (IdP) portal.

  2. Create a 'Worksuite' enterprise app in your IdP account.

  3. Configure the app to use SAML 2.0 for SSO.

  4. In the SAML settings, ensure the field representing 'Entity ID' - also named Identifier or Audience URI - is set to 'https://your-worksuite-domain/api/sso/metadata/'

  5. Set the field SAML ACS field - also called 'Assertion Consumer Service' URL or Recipient/Reply URL - to 'https://your-worksuite-domain/api/sso/acs/'

    *Example domains include https://acme.workstuite.com, or https://myCompany.worksuitefms.com

  6. Ensure the following required User Attributes or Claims are configured:
    • the Unique User Identifier (or Name ID) should be set to email and the format set to 'unspecified'
    • an attribute named 'email' which maps to user.emailAddress
    • an attribute named 'first_name' which maps to user.givenName
    • an attribute named 'last_name' which maps to user.surName (or family name)
      Note: Each provider may have a different naming convention for the user fields above

  7. Via the provider portal, ensure your users are assigned to the Worksuite app you created in 'step 2'.

  8. metadataDownload the meta data file for the newly configured Worksuite app and forward it to the Worksuite Customer Success representative.


Azure SSO setup

  1. Log in to Azure

  2. Create a 'Worksuite' app

    • From the Azure Portal home page
    • Navigate to 'Azure Active Directory'
    • Click on 'Enterprise applications'
    • Click 'New Application'
    • Click 'Create your own application'
    • Name your app 'Worksuite'
    • Ensure the option 'Integrate any other application you don't find in the gallery' is selected
    • Click the 'Create' button



  3. Configure the app

    • Find the newly created 'Worksuite app in the Enterprise applications > All applications page
    • Click on the 'Worksuite' app
    • Click on 'Get started' on the '2. Set up single sign on' card
    • Click to 'Edit' the 'Basic SAML Configuration'
    • Enter https://your-worksuite-domain/api/sso/metadata/ in the 'Identity (Entity ID) field
    • Enter https://your-worksuite-domain/api/sso/acs/ in the Reply URL (Assertion Consumer Service URL) field
    • Click 'Save'
    • Click 'Edit' in the User Attribute & Claims section
    • Edit the 'Unique User Identifier (Name ID) attribute so that the value is user.mail [nameid-format:unspecified]
    • Edit the 'Additional claims' so that there is claim named 'email' with value 'user.mail'
    • Edit the claims so that there is a claim named 'first_name' of value 'user.givenname'
    • Edit the claims so that there is a claim named 'last_name' of value 'user.surname'
    • No other claims are necessary and may be deleted
    • Click 'Save'



  4. Send the metadata file

    • In this step you will download and send the metadata file to Worksuite
    • Find the Worksuite app within Active Directory > Enterprise applications > All applications
    • Click on Worksuite
    • Click on 'Get started' in the '2. Set up single sign on' section
    • In section '3' click on the 'Download' link next to 'Federation Metadata XML'
    • The Metadata file will download to your computer
    • Take the metadata file and email or Slack it to your Worksuite customer success representative



  5. Assign users

    • Users to need to be assigned for Worksuite access
    • Return to the Worksuite app you create in previous steps
    • Click on 'Assign users and groups'
    • Click 'Add user/group'
    • Click on 'None Selected'
    • Search for your user or group
    • Click on the user and click the 'Select' button
    • Click the 'Assign' button

Okta SSO setup

  1. Log into Okta

  2. Create a 'Worksuite' app

    • Navigate to 'Applications' page
    • Click 'Add Application' button
    • Click 'Create New App' button
    • On the next screen, name the app 'Worksuite' and click 'Next'


  3. Configure the app
    • Configure the Worksuite app with the required SAML fields and attributes
    • Enter https://your-worksuite-domain/api/sso/acs/ in the field labeled 'Sign sign on URL'
    • Check the box 'User this for Recipient URL and Destination URL
    • Enter https://your-worksuite-domain/api/sso/metadata/ in the field labeled 'Audience URI (SP Entity ID)
    • In the 'Default RelayState' field enter a forward-slash ' / '
    • Select 'Unspecified' for 'Name ID format'
    • For 'Application username' select 'Email'
    • Next add required attribute fields
    • Enter 'email' for the attribute name, select 'Name format' as 'Basic', select the value as 'user.email'
    • Click to 'Add Another' - name it 'first_name', select 'Basic' and select the value 'user.firstName'
    • One more time, click to 'Add Another' - name it 'last_name', select 'Basic', and this time select the value 'user.lastName'
    • You are done with this step - click 'Next'
    • On the final screen select "I'm an Okta customer adding an internal app" and click 'Finish'



  4. Send the metadata file

    • In this step you will download and send the metadata file to Worksuite
    • Now that your app is created and configured, visit the 'applications' tab within Okta and click on the 'Worksuite' app
    • Next, click on the 'Sign on' tab
    • Click on the link 'Identity Provider metadata'
    • Cut and paste the XML into an email or Slack channel and send to your Worksuite customer success person




  5. Assign users

    • Users need to be assigned to the Worksuite app
    • Return to the Worksuite app you created in the previous steps
    • This time click on the 'Assignments' tab
    • Click the 'Assign' button
    • Search for the 'people' or 'groups' you want to assign for Worksuite access



If you have any additional questions, please reach out to your account manager or us at [email protected].