As an Enterprise client, you have access to capabilities that allow you to access and use Upwork in the ways that work best for you.
Security Assertion Markup Language (SAML) based Single Sign-On (SSO) gives Upwork Enterprise users access to Upwork through any SAML 2.0 Identity Provider (IdP). When Upwork Enterprise SSO is enabled, Upwork as the service provider (SP) will require users to authenticate through your IdP in order to access your company’s Upwork Enterprise platform, and will use the user data provided by the IdP to create the user’s login without requiring the user to register manually. Similarly, if the user fails authentication in your IdP, a valid SAML response would not be passed on to Upwork and they would not be able to access Upwork Enterprise. Learn more about the benefits of SSO here.
Prerequisites
- SAML-based SSO is only available for Enterprise Standard and Enterprise WPP/Compliance accounts
- To use Upwork’s SSO feature, your Identity Provider (IdP) must be compatible with SAML 2.0 protocol. Some compatible IdPs are Microsoft Azure, Okta, Onelogin, PingIdentity, and VMware Workspace One
- To configure SSO for your Upwork Enterprise account, you must be an administrator user in the Upwork account with full privileges. Learn more about setting admin permissions here or contact your Upwork team to ensure you have proper access
- Once you have completed the configuration steps below, you will need to contact your Upwork team to test and activate SSO
Set up SSO
To configure SSO for your Upwork Enterprise account, you must establish a connection between your IdP and Upwork. In order to do so, you must specify your IdP information in Upwork first to enable Upwork to send a SAML request to your IdP.
Step 1: Access your Upwork Enterprise account
To configure your Upwork Enterprise account for SSO, perform the following steps:
- Log in to your Upwork Enterprise account as an admin user
- Navigate to the Settings section by clicking your company logo in the top right corner of the navigation bar
- Select Upwork Enterprise and then Domain configuration under the SAML single sign-on section
- Find the domain that you want to configure and choose Edit — if no domains appear, please contact your Upwork team for assistance.
Note:
You can only configure SSO for exclusive domains— domains which belong to your company and that only your company can access. You may enable multiple domains for SSO as long as they share the same IdP, but you only need to configure the authentication page for one domain.
Step 2. Proceed with completing the following areas on the authentication page
In the Identity Provider section, select Attach file to upload an XML metadata file from your IdP. Do not upload a file bigger than 2 MB. By exchanging metadata files, Upwork will know how to communicate with your IdP and how to validate requests and assertions.
After you have uploaded your own metadata file, the Download button will activate and allow you to download Upwork’s metadata file to your local desktop. You may need this file and the URLs provided when setting up Upwork as a new service provider in your IdP.
In most cases, you will not need to make changes to these advanced options.
User exclusion list
You can use the user exclusion list to let certain users bypass SSO and give emergency access to other users, such as IT users (or whoever handles SSO configuration). For example, in the rare case the SSO integration fails, this user could still log in using their email and password (bypassing SSO) to make changes to your SSO configuration. For this field, specify in a comma-separated list the email addresses to exclude from SSO.
Note:
We recommend that you specify at least two individuals’ email addresses in the user exclusion list who can access Upwork if SSO login fails or requires updates.
Hard session timeout
Using the hard session timeout dropdowns, you can specify for how long your users can access Upwork via SSO after a period of inactivity before they are logged out. Once the specified value is reached, inactive users that attempt to resume their session will be logged out and must re-authenticate before continuing. You can set this field to any whole number to reflect a value in minutes, hours, or days.
Note:
For hard session timeouts, Upwork enforces a maximum value of 14 days for desktop and 90 days for mobile.Soft session timeout
Using the soft session timeout dropdowns, you can specify how long your users can access Upwork via SSO 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 re-authenticate; Upwork will automatically re-authenticate the user without additional user input. However, if Upwork fails to re-authenticate the user, the user will be logged out. You can set this field to any whole number to reflect a value in minutes, hours, or days.
Note:
For soft session timeouts, we enforce a maximum value of 24 hours.Country format
This dropdown determines the format Upwork should expect your users’ country data to be in when received from your IdP. ISO 3166 is an international standard of country codes and is most common with IdPs, but if this data is provided as the full country name instead, this should be updated accordingly.
Signature algorithm
This value is the resulting hash derived from encrypting the contents of the message (be it the assertion or the entire response, as per your configuration). This value can then be cross checked and validated on the receiving side using the same DigestMethod (for example, SHA1) to ensure the integrity of the message. SHA1-RSA is being deprecated by some vendors, so your IdP may use SHA256-RSA, in which case this should be updated.
Force manual department selection
This option is only applicable for accounts that have set up department mapping. All other accounts can leave this blank. If you have set up department mapping, you can choose this option if you would prefer that your users be asked to manually select their department information on their first authentication, even when the department information is provided in the SAML assertion. For more information on department mapping, see the other options section below.
Force manual country selection
Upwork requires a country mapping for all users, so if your IdP fails to send country information in the SAML assertion for a given user, they will be asked to manually select their country information on their first authentication to Upwork. By selecting this option, your users will be asked to manually select their country information on their first authentication, even when their country information is provided in the SAML assertion.
Skip SAML response destination validation
This feature is only intended for testing and debugging purposes. Do not activate.
Enable user Principal Id
If any of your employees use multiple email aliases, you will need to enable the User PrincipalId or Secondary Email Fallback feature to avoid creating multiple user accounts in the platform for the same user. User PrincipalId allows Upwork to retrieve a unique ID from the SAML assertion sent by your IdP to identify the user, rather than creating a user account for each email alias. Once you select this checkbox, a User Principal Id field will appear in the attributes mapping section to specify the attribute name for the unique ID field to be used.
Note:
If enabled, it is mandatory to provide a User Principal Id attribute in the SAML assertions for all users, otherwise their authentication will fail. Additionally, if a user's email is changed in your IdP, we will update their profile email accordingly on the next successful authentication.Enable secondary email fallback
If your employees use multiple email aliases, you will need to enable the User PrincipalId or secondary email fallback feature to avoid creating multiple user accounts in the platform for the same user. Secondary email fallback allows Upwork to retrieve two separate email IDs from the SAML assertion sent by the IdP, rather than creating a user account for each email alias. Once you select this checkbox, a secondary email field will appear in the attributes mapping section for you to specify the attribute name for the secondary email field to be used.
This area is used to determine how Upwork will create profiles for users when they authenticate for the first time. In this section, you will need to provide the alias names that correspond to various attributes in your IdP. Attribute mapping for first name, last name, and email address (as well as User Principal Id/Secondary Email, if enabled) are required to successfully set up SSO, and alias 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 your IdP provides the attributes mapping by default, you may not have to specify these details.
Note:
If the attribute mapping for country is not provided, users will be asked to manually select their country information on their first authentication to Upwork. Similarly, if you are not set up for department mapping, you do not need to provide an attribute mapping for the department. Instead, new users will be asked to manually select their department/team assignment on their first authentication to Upwork.Step 3: Add Upwork SSO details to your IdP
Once your Upwork Enterprise account is configured for SSO, you will need to set up Upwork as a new service provider in your IdP. The steps to do so are IdP-specific, however, some IdPs (such as Okta, Azure, or OneLogin) will already have Upwork in their public library of applications.
Step 4: Activate and test SSO
Once you have completed the above steps to configure your Enterprise account for SSO and have added Upwork as a new service provider in your IdP, we will need to test the connection to your IdP. Contact your Upwork team to schedule time with Upwork’s SSO team to test the connection live. Be sure to provision a test user or two in your IdP with access to Upwork for testing. If you get any errors during setup and testing, refer to the troubleshooting guide.
Once the setup is successfully validated, work with your Upwork team to determine what users and teams should be provisioned with access to Upwork and choose a go-live date for SSO.
Other options
SCIM 2.0 support
Upwork supports System for Cross-domain Identity Management (SCIM), allowing for user provisioning, de-provisioning, and email changes on a more immediate basis than SAML authentication alone. To enable, contact your Upwork team to receive a tenant ID, SCIM token, and documentation on how to perform the SCIM API calls.
Note:
If using SCIM, country is a mandatory attribute for user provisioning and must be provided from the IdP using the 2-letter ISO 3166 code format — self-selection or full country name is not supported. Additionally, at this time we do not support deletion requests or change requests (other than email) through SCIM.
Department mapping
If you are able to provide a department attribute in the SAML assertion of your IdP, you may want to take advantage of our department mapping option. This option can automatically add new users to the correct Upwork team the first time they authenticate based on the department attribute details of the user. This requires a mapping file and additional intervention from Upwork’s SSO team to set up, so please contact your Upwork team for assistance.
User team/department assignment
Upwork uses a team/department structure to organize users and manage users’ visibility, so all Upwork users must be assigned to a “team” when authenticating for the first time. By default, this assignment is self-selected by the user from a dropdown list at the time of authentication, but team assignment can also be mapped automatically using data from your IdP with our department mapping option.
Self-select option
If utilizing the self-select option, you can manage the list of available teams for selection in-platform by following these steps:
- Log in to your Upwork Enterprise account as an admin user
- Navigate to the Settings section by clicking your company logo in the top right corner of the navigation bar
- Select Upwork Enterprise and then Team setting under the SAML single sign-on section
- Select the checkboxes corresponding to all the Upwork teams that you want to display to new users when they authenticate for the first time. Users will select from this list of available teams to join.
- Alternatively, if you do not want new users 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:
If there are no teams listed or missing teams, you may create new teams by accessing the Teams configuration page. The parent team on your account will always be hidden during a new user’s first authentication.
Frequently Asked Questions
Once SSO is enabled, new users are no longer required to register for an account on Upwork. Instead, when a new user attempts to register or access Upwork using your company’s email domain, they will be redirected automatically through SSO and an account will be created automatically for the user if they pass authentication with your IdP.
Currently, Upwork does not support an environment to test SSO. However, Upwork provides the user exclusion list feature to ensure that users who are self-testing SSO can easily revert the mechanism if SSO is configured incorrectly.
To exclude certain users from getting authenticated through SSO, add them to the users exclusion list. You can do so as an administrator during SSO setup.
If the new email domain is managed within the same IdP, you do not need to re-complete the above configuration steps. Notify your Upwork team, who will ensure the new email domain is activated for SSO.
