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 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.
Prerequisites
- SAML-based SSO is only available for Enterprise, and Compliance accounts.
- Business plans are limited to configuring one domain.
- To use Upwork’s SSO 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 SSO with Upwork, you must be an administrator user on the Upwork account with full privileges. Learn more about setting admin permissions here
Set up SSO
Set up Upwork’s SSO service for your organization with the following steps. If you get any errors during setup, refer to the SSO Troubleshooting guide.
To configure SSO for your Upwork account, you must first establish a connection between your IdP and Upwork. In order to do so, you must specify the Upwork SSO 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.
- Under IdP metadata file, select Attach file to upload the metadata file from your IdP. You only need to upload a metadata file if the system does not have any existing metadata information about your IdP. Do not upload a file bigger than 2 MB.
- In Domain login URL, specify the login page of IdP. This is the page that users can access to log in to Upwork.
- In Enterprise Departments Domain, specify the domain of the IdP. This domain contains all the users that need to be authenticated via SSO. For example, okta.com, onelogin.com.
Advanced settings
In most cases, you will not need to make changes to these advanced options.
Force Manual Department Selection
This option is only applicable for accounts involved in our Department Mapping beta. All other accounts can leave this blank. If you are part of our Department Mapping Beta, you can choose to check this selection if you would like new users to select a team manually even if your IdP fails to send department information in the SAML assertion for a given user.
Force Manual Country Selection
Upwork requires correct country mapping for all users. With SSO configured, your IdP fails can send country information in the SAML assertion for a given user. If this option is checked, users are required to select their respective countries on their first authentication to Upwork even if the SAML assertion includes their country.
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. Skipping is not recommended.
Special Handling for Multiple Email Aliases per User
If your employees use multiple email aliases, you will need to use one of the following 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
- To download the metadata file on 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.
- Go to your IdP and fill out these fields for your domain(s).
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 case of a failure scenario this user could still log in to make changes to your SSO configuration. For this field, specify in a comma-separated list the email addresses to exclude from SSO. 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 SSO 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 SSO login fails.
In Hard session timeout, you can specify how long your users can access Upwork via SSO after a period of inactivity. Once the specified value is reached, inactive users that attempt to resume their session will be asked to re-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 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 from Upwork.
You can set this field to any whole number to reflect a value in minutes, hours, or days.
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 your IdP provides the attributes mapping by default, you may not have to specify these details.
Be sure to select Save to have all your changes saved.
NOTE
To configure SSO for multiple domains, access each domain separately and repeat the above steps.
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:
- Log in to your Upwork Enterprise account as an admin user
- Navigate to Settings from your company logo on the top right navigation bar
- Select Upwork Enterprise from the Settings option
- Under SAML Single Sign-On, select the EDIT option
- Under Team Mapping, select the EDIT option
- 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 will 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 your users to select, check 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.
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 SSO for your enterprise account. They will help you define how users get added to teams and then go live with SSO on a date you choose.
To configure SSO for your Upwork account, you must establish a connection between your IdP and Upwork. 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 SSO independently.
To configure SSO in Upwork, perform the following steps:
- Log in to your Upwork Enterprise account as an admin user
- Navigate to Settings from your company logo on the top right navigation bar
- Select Upwork Enterprise from the Settings option
- Under SAML Single Sign-On, select the EDIT option
- Under Domain Configuration, select the EDIT option
- Access the domain that you want to configure and choose Edit — if no domains appear, please contact your account representative
Note that you can only configure SSO 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.
Access Upwork
Once SSO is live on your account, users can access Upwork via SSO. 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.
With SSO, 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.
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.