Enterprise Single Sign-On Setup Guide

SAML-based Single Sign-On (SSO) gives enterprise and enterprise compliance users access to Upwork through any SAML 2.0 Identity Provider (IdP). For Upwork enterprise SSO, Upwork is the Service Provider (SP) that grants users access without requiring the user to register. It also denies access if the user cannot be found in the IdP. Upwork leverages the user details shared by the IdP to grant access. To learn more, see SAML Overview.

Prerequisite Requirements

  • SAML-based Single Sign-On is only available for Enterprise and Compliance accounts. The feature is not available for Business, Plus, or Basic accounts.
  • To use Upwork’s Single Sign-On feature, your IdP must be compatible with SAML 2.0 protocol. Some compatible IdPs are Microsoft Azure, Okta, Onelogin, PingIdentity and VMware Workspace One.
  • To enable or configure Single Sign-On with Upwork, you must be an administrator user on the Upwork account with full privileges. Find out more about setting admin permissions here.

Set up SSO

Set up Upwork’s Single Sign-On service for your organization with the following steps.

 

NOTE

If you get any errors during setup, refer to the SAML Troubleshooting guide. 

 

Add Upwork Single Sign-On details to your IdP

To configure Single Sign-On for your Upwork account, you must first establish a connection between your IdP and Upwork (SP). In order to do so, you must specify the Upwork Single Sign-On details for your IdP. This enables the IdP to send the SAML response to Upwork, which contains information about the user who requests access to Upwork through the IdP.

You can get more information about SAML configuration here.

If your IdP is Microsoft Azure, go to the Azure Gallery and locate the Upwork app. By doing so, you can skip the above steps.

Update IdP details in your Upwork account

To configure Single Sign-On for your Upwork account, you must establish a connection between your IdP and Upwork (SP). In order to do so, you must specify your IdP information in Upwork. This enables Upwork to send a SAML request to your IdP.

Upwork lists the existing domains for your accounts. You will need to configure each domain you want to use with Single Sign-On independently.

To configure Single Sign-On in Upwork, perform the following steps:

  1. Log in to your Upwork Enterprise account as an admin user.
  2. Navigate to Settings from your company logo on the top right navigation bar.
  3. Select Upwork Enterprise from the Settings option.
  4. Under SAML Single Sign-On, select the EDIT option.
  5. Under Domain Configuration, select the EDIT option.
  6. Access the domain that you want to configure and click Edit. In the unlikely event that no domains appear, please contact your account representative.

SAML-1.png

 

Note that you can only configure Single Sign-On for exclusive domains. Exclusive domains are domains that only your company can access. Non-exclusive domains (highlighted below) are domains that belong to other companies and are currently being used by them. If you have added a domain that is not exclusive to your account, you will need to reach out to your account representative.

SAML-2.png

 

Under the Identity Provider section:

  1. Under IdP metadata file, select Attach file to upload the file that contains metadata information from your IdP. Note that you are required to upload a metadata file only if the system does not have any existing metadata information about your IdP. Ensure that you do not upload a file whose size is greater than 2 MB.
  2. In Domain login URL, specify the login page of IdP. This is the page that users can access to log in to Upwork.
  3. In Enterprise Departments Domain, specify the domain of the IdP. This domain contains all the users that need to be authenticated via Single Sign-On. For example, okta.com, onelogin.com.

Advanced Settings

In most cases, you will not need to make changes to these advanced options.

Special Handling of Country and Department

In Country format, select the format in which Upwork needs to detect the country information. This is only applicable if you are sending country information in the SAML assertion to Upwork. The available country formats are:

  • ISO-3166
  • Full country name

Allow Department Selection

The Allow Department Selection beta option allows you to decide if your users should be allowed to select their own team. In most cases, this should remain checked so new users can be assigned to a team in the Team Mapping section. If you are part of our Department Mapping Beta, you can choose to remove this selection if you would like to remove the ability for new users to select a team if your IdP fails to send department information in the SAML assertion for a given user.

Allow Country Selection

Country Selection checkbox should remain checked. Upwork requires correct country mapping for all users. If Upwork does not receive that information from the IdP, they will be prompted to select their respective countries on their first authentication to the Upwork platform.

Special Handling of SAML Response Destination Validation

If you do not want Upwork to validate the SAML assertion destination, select the Skip SAML Response Destination Validation checkbox. Note that Upwork does not recommend that you select this option.

Special Handling for Multiple Email Aliases per User

If your employees use multiple email aliases, you will need to use one of the following two options to avoid user duplication:

  • Enable User Principal ID: Upwork retrieves the unique ID from the SAML assertion sent by the IdP to identify the user by the principal ID. Once you select this checkbox, Upwork allows you to specify the user principal ID attribute on the IdP side in the Attributes section.
  • Enable Secondary Email Fallback: Use this option If you want to avoid user duplication and let your users access the Upwork platform by using two different email aliases. In this case, Upwork retrieves two separate email IDs from the SAML assertion sent by the IdP and avoids creating multiple user accounts in the platform for the same user. Once you select this check box, Upwork allows you to specify the secondary email specific attribute on the IdP side in the Attributes section.  

Upwork_3.png

Under the Service Provider section:

    1. To download the metadata file of Upwork, select Download. This downloads the Upwork metadata file to your local system. You can use the details from this file in your IdP settings.
    2. Go to your IdP and fill out these fields for your domain(s). 

Upwork_4.png

Under the Custom Settings section:

    1. You can use the User exclusion list to let certain users bypass Single Sign-On and give emergency access to such IT users (or whoever handles Single Sign-On configuration). For example, in the case of a failure scenario this user could still log in to make changes to your Single Sign-On configuration. For this field, specify the list of comma-separated email addresses to exclude from Single Sign-On. These users do not need to access the IdP in order to access Upwork; they can directly authenticate with Upwork. You must specify at least one user so that this user's details can be used to access Upwork; if Single Sign-On authentication fails.

NOTE

Upwork recommends that you also specify an email address that corresponds to a team. If you do so, multiple users (within the team) can access Upwork if Single Sign-On login fails.

 

In Hard session timeout, you can specify how long your users can access Upwork via Single Sign-On after a period of inactivity. Once the specified value is reached, inactive users that attempt to resume their session will be asked to authenticate before continuing.

You can set this field to any whole number to reflect a value in minutes, hours, or days.

In Soft session timeout, you can specify how long your users can access Upwork via Single Sign-On after a period of inactivity - without requiring them to log in again. Once the specified value is reached, inactive users that attempt to resume their session will not be asked to authenticate; Upwork will authenticate the user without the user needing to re-authenticate. However, if Upwork fails to authenticate the user, the user will be logged out from Upwork.

You can set this field to any whole number to reflect a value in minutes, hours, or days.

Upwork_5.png

Under the Attributes Mapping section:

This section is used to create profiles for users when they authenticate for the first time. Upwork asks your IdP for the attribute for the user to fill in their First name, Last name, Email address, Country and Department. You can specify the aliases that correspond to the various attributes in your IdP. Note that the values must contain the exact spelling, punctuation, and case, as they do in your IdP.

These details are IdP specific; some IdPs may require you to specify attribute mapping while some do not. If IdP (by default) provides the attributes mapping, you may not have to specify these details.

Be sure to select Save to have all your changes saved.

Upwork_6.png

 

NOTE

To configure Single Sign-On for multiple domains, access such domains and repeat the above steps.

 

Complete SSO Setup

Once you have completed the above steps, you can define how the users within your organization will be added to teams in Upwork.

To configure team mapping in Upwork, perform the following steps:

  1. Log in to your Upwork Enterprise account as an admin user.
  2. Navigate to Settings from your company logo on the top right navigation bar.
  3. Select Upwork Enterprise from the Settings option.
  4. Under SAML Single Sign-On, select the EDIT option.
  5. Under Team Mapping, select the EDIT option.
  6. Select the checkboxes corresponding to all the existing Upwork teams that you want to display to your users when they authenticate for the first time. Your users can then select from the available teams to join.

Alternatively, if you do not want your users to select to join certain teams in their first authentication experience, uncheck the checkboxes for those teams. Upwork will not display those teams to your users during authentication.

 

NOTE

  • To view the Upwork teams that are not available for selection to your users, select the Only show hidden teams for SSO checkbox.
  • If there are no teams listed for your user account, please create a team and then configure the team mapping options. To create a team, access the Teams page.
  • The parent team on your account will not be available to show during a user’s first authentication.

 

SML-3.png

Be sure to select Save to have all of your changes saved.

Once you have completed these steps, Upwork will test the connection to your IdP. If you get any errors during setup, refer to the troubleshooting guide.

Once the setup is successfully validated, contact your Upwork account team so they can help you enable Single Sign-On for your enterprise account. They will help you define how users get added to teams and then go live with Single Sign-On on a date you choose.

Access Upwork 

Once you are live with SSO for your account, users can access Upwork via Single Sign-On. When a user tries to access Upwork for the first time, there are two possible scenarios depending on how you’ve decided to add users to teams:

  • If users can select their own Upwork team:
    You can choose to allow your users to select their own Upwork team the first time they authenticate.

In this case, Upwork does not receive department details from your IdP. These users can select their own department and country when they log in to Upwork for the first time.

  • If departments are mapped to Upwork teams:
    You can choose to automatically add your users to specific teams on Upwork the first time they authenticate. In this scenario, your account’s departments are mapped to individual teams on Upwork.

In this case, Upwork receives the department details from your IdP. Once the IdP authenticates the user with the specific department, the user logs in to Upwork and is automatically added to the Upwork team mapped to that department. 

 

For a Single Sign-On enabled account, do users register on Upwork?

With Single Sign-On, users are not required to register on Upwork. When a user accesses Upwork, the integrated IdP informs Upwork and an account is created for the user if the IdP can locate the user details.

Does Upwork provide an environment to test Single Sign-On?

Currently, Upwork does not support an environment to test Single Sign-On. However, Upwork provides the user exclusion list feature to ensure that customers testing Single Sign-On can easily revert the mechanism if Single Sign-On is configured incorrectly.

How do I exclude specific users from using Single Sign-On?

To exclude certain users from getting authenticated through Single Sign-On, you can add such users in Users exclusion list. You can do so as an administrator user during Single Sign-On setup. To learn more, see Updating IdP details in your Upwork account.

 

Log in to get personalized help.