Workiva Support Center

Org Security Admins can follow the steps below to configure SAML single sign-on settings for the organization. SAML-based single sign-on (SSO) gives members access to Workiva through an identity provider (IdP). Before you configure settings, make sure you’ve reviewed What is SAML single sign-on?.

Note: Org Security Admins must be added to a workspace in order to access Organization Admin.

Step 1: Navigate to SAML SSO settings

1. Go to Organization Admin.
2. Click Identity & access management in the left menu.
3. Make sure that you're on the Authentication tab.
4. Click the SSO configuration page.
   

If you have an existing SSO configuration, the page will look like this:

Step 2: Create your SAML SSO configuration and select your identity provider

1. Click Create SSO configuration.
   
2. Enter a Configuration name and select the Identity provider (IdP) from the dropdown.
3. Click Create configuration to proceed.

Step 3: Send the Workiva metadata to your identity provider admin

1. Under the Workiva metadata section, you’ll see the Identifier (Entity ID) and Reply URL.
2. Click Advanced options to see the Sign on URL and Logout URL.
   These URLs are unique to each organization and cannot be modified, and will contain one of the following region markers: app.wdesk.com, apac.wdesk.com, ca.wdesk.com, or eu.wdesk.com.
3. Send these Workiva metadata URLs to your identity provider admin.
   You can also click Download Workiva metadata XML to download and send the Workiva metadata XML file to your identity provider admin instead.

4. You can adjust your Clock Skew Allowance. Clock Skew Allowance is the maximum permitted time difference between your SAML identity provider and Workiva. The default is 300 seconds (5 minutes).

   Tip: A greater value expands the "window of acceptance" for time differences. While this improves reliability by reducing rejected requests, it also introduces security and performance risks. Alternatively, a smaller value increases the probability of authentication failures due to time-outs.

5. If using Microsoft Azure as your identity provider, your identity provider admin can refer to Step 2 under the Azure tab in Configure SAML SSO with your identity provider.
6. If using Okta as your identity provider, your identity provider admin can refer to Step 3 under the Okta tab in Configure SAML SSO with your identity provider.
7. If using a different identity provider other than Microsoft Azure or Okta, contact your identity provider’s customer support if you need assistance.

Step 4: Enter your identity provider metadata into Workiva

Prerequisite: You need to get the required identity provider metadata information from your identity provider admin before proceeding.

• If you are using Microsoft Azure as your identity provider, your identity provider admin can refer to Step 4 under the Azure tab in Configure SAML SSO with your identity provider.
• If you are using Okta as your identity provider, your identity provider admin can refer to Step 2 under the Okta tab in Configure SAML SSO with your identity provider.
• If using an identity provider other than Microsoft Azure or Okta, contact your identity provider’s customer support to get the information.

Under the identity provider metadata section (for example, Microsoft Azure metadata), enter the identity provider metadata.

1. First, in the Preferred entry method dropdown, select how you want to enter in the identity provider metadata. You can enter in a Federation metadata URL, upload a Metadata XML file, or enter the metadata via Manual entry.
   

2. In the file selection dialog, select the file that contains the identity provider metadata information, and then click Import.

   

   Alternatively, you can enter the values manually:
   

Step 5: Set user mapping

In the User mapping section, click the dropdown, and select either:

• Map users to their Workiva username (recommended)
• Map users manually

Note: If you have entered the identity provider metadata information manually, you will need to toggle on the Advanced Options for this section.

Mapping users to their Workiva username

If you selected Map users to their Workiva username in the dropdown, Workiva will then expect the incoming Primary NameID attribute to match the Workiva username, ignoring any case sensitivity, when the user logs in. For example, this allows User.Name.Example to match against user.name.example.

You can then click the Set mapping dropdown, and select Set all SSO IDs to Workiva username to populate the table.

Click Create configuration to proceed.

Mapping users manually

If you selected Map users manually in the dropdown, first check the advanced options. Under NameIdentifier location, most configurations will have the NameIdentifier is in Subject statement option selected. This means that Workiva will check for the NameIdentifier element in the Subject statement.

However, you can select the NameIdentifier is in a different element attribute option and enter the NameIdentifier element attribute, so that the application looks for the attribute in the SAML response.

Note: Most Org Security Admins will not alter the NameIdentifier location from the default. Before making changes, contact Workiva Support for assistance.

Map users via file import

Click Set mapping, and select Import SSO IDs via file to map users to the SSO IDs in a .csv mapping file (see SAML ID .csv mapping file requirements).

• No headers are needed in the mapping file.
• All rows will be processed, and any invalid rows will be skipped.
• If there are duplicate usernames, only the first row with that username will be used.
• If a provided username already has an existing mapping, its mapping will be updated to what's provided in the mapping file.
• If rows are skipped, the failures will be logged in the SAML single sign-on activity log.

Map users individually

If you need to set or edit SSO IDs for users individually, search for the user and/or use the SSO ID status filter to more easily find the user. Then in the table, double click the SSO ID field next to the user, and enter in the correct SSO ID.

After setting the user mapping, click Create configuration to proceed.

SAML ID .csv mapping file requirements

A valid row in the SAML ID .csv mapping file follows the following format:

samlId,username

A row may be invalid if:

• There are less than two items in the row
• The SAML ID and/or username isn't provided
• The provided username doesn't exist
• The user with the provided username isn't a member of the organization
• The user with the provided username's primary organization isn't the same as the organization currently being modified
• The provided SAML ID has already been taken by a different user

An example valid mapping file looks like this:

exampleSamlId,exampleUsername
exampleSamlId2,exampleUsername2
exampleSamlId3,exampleUsername3

Step 6: Activate your SAML SSO configuration

After creating your SAML SSO configuration, you’ll need to explicitly activate it in order for the configuration to take effect.

Click Activate on the configuration. Your configuration will then show as Active.

Step 7: Update SAML SSO authentication options

Workiva strongly recommends forcing users to sign in using SSO as a best practice to simplify your login process and provide a better overall experience. After you have created and activated your SAML SSO configuration:

1. Under the Single sign-on tab, the Force SSO and exceptions section presents two authentication options:

   • Force users to sign in using SSO (Recommended): Non-admin users are forced to use SSO, while Org Security Admins may continue to sign in using their username and password. This option works best if your company wants to force SSO but still allow Org Security Admins to access the platform if SSO experiences any issues.

     Note: Make sure that you conduct comprehensive testing and that you're completely confident in your SAML SSO setup before enabling this option.

   • Force Org Security Admins to sign in using SSO: Org Security Admins are forced to use SSO. This option works best if company security policies don’t want to exempt users from the SSO requirement. To enable this option, you’ll also need to check Force users to sign in using SSO. This is located in the SSO requirements page under the Authentication tab.
     
2. After selecting your options, click Save.

If desired, you can allow specific users to sign in without SAML SSO by adding them to the SSO exceptions list.

Note: Before forcing SAML SSO, make sure to add the necessary users to the SSO exceptions list to avoid locking users out of their accounts.