Classic file types are no longer available for use as of January 2021. You can transition your classic files or download a PDF. Learn More

Workiva Support Center

Configure SAML single sign-on

Configure SAML single sign-on

  • Last updated on

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 on Security in the left menu.
  3. Click on the Single Sign-On tab.

step 1 sso.png

 

Step 2: Enable SAML SSO

  1. Under the Single Sign-On tab and in the SAML Settings section, check the Enable SAML Single Sign-On option.
    Note: Only checking the Enable SAML Single Sign-On box will not impact the user’s sign-in experience. Users will still be able to sign in with their username and password until you completely finish the SAML single sign-on configuration.
  2. Click Save Changes.
EnableSAML-SSO.jpg

 

Step 3: Access SAML SSO URLs

After enabling SAML SSO:

  1. Under the Single Sign-On tab, click on IdP Settings.
  2. Scroll down to the Service Provider Details section.
  3. You’ll see the Login URL, Metadata URL, Consumer URL, and Logout Service URL. These URLs are unique to each organization and can't be modified and will contain app.wdesk.com, eu.wdesk.com, or apac.wdesk.com.
  4. Copying and pasting the Metadata URL into a browser window will automatically download Workiva’s metadata XML file. You can also copy and save these URL values.
SSO-IdPSettings-ServiceProviderDetails.jpg

 

Step 4: Integrate Workiva with the identity provider

See the below steps for how to integrate Workiva with common identity providers.

To configure SSO with Okta:

  1. Sign in to the Okta admin portal, and under Applications, select Browse App Catalog.
  2. In the App Integration Catalog, search for Workiva and select it. Then click Add Integration.
  3. Set the general settings according to your IT policies and procedures. Then click Next.
  4. In the SAML 2.0 section, leave the Default Relay State blank. Download the metadata XML file to upload into Workiva as outlined in Step 7: Configure IdP Settings. One way to download the XML file is to copy the metadata URL, paste it into a browser, and then save the page as an XML file.
  5. Using the Workiva URLs found in Step 3: Access SAML SSO URLs:
    • Copy and paste the Workiva Consumer URL into the Okta ACS URL field.
    • Copy and paste the Workiva Metadata URL into the Okta Audience URL field.
  6. In Okta’s attributes and claims, it’s recommended to match the Workiva username (case insensitive) to the Primary NameID attribute, so that Workiva automatically maps the attribute to the Workiva username when the user signs in with SSO for the first time. However, this mapping depends on your specific IT policies.
    • If these attributes don’t match, you’ll need to manually map the attribute to the corresponding username as described in Step 5: Set SAML SSO User ID settings before the user can sign in with SSO.

To configure SSO with Azure:

  1. Sign in to the Azure admin portal, and go to Microsoft Entra ID > Enterprise applications.
  2. Click New application.
  3. Search for Workiva and select it. However, if you plan on implementing SCIM, you’ll need to create a custom application.
  4. Name the application, then click Create.
  5. When the application has been created, go to Single sign-on > SAML.
  6. Edit the Basic SAML Configuration.
  7. Using the Workiva URLs found in Step 3: Access SAML SSO URLs.
    • Copy and paste the Workiva Metadata URL into the Azure Identifier (Entity ID) field.
    • Copy and paste the Workiva Consumer URL into the Azure Reply URL (Assertion Consumer Service URL) field.
    • Copy and paste the Workiva Login URL into the Azure Sign-on URL field (optional).
    • Leave the Relay State field blank.
    • Copy and paste the Workiva Logout URL into the Azure Logout URL field (optional).
  8. Once the configuration is saved, edit the Attributes & Claims. It’s recommended to match the Workiva username (case insensitive) to the Primary NameID attribute, so that Workiva automatically maps the attribute to the Workiva username when the user signs in with SSO for the first time. However, this mapping depends on your specific IT policies.
    • If these attributes don’t match, you’ll need to manually map the attribute to the corresponding username as described in Step 5: Set SAML SSO User ID settings before the user can sign in with SSO.
    • Workiva only looks at the required claim Unique User Identifier (NameID) for the users and any additional claims will be ignored.
  9. After setting the attributes and claims, in the SAML Certificates section, click Download next to Federation Metadata XML to download the metadata XML file to upload into Workiva as outlined in Step 7: Configure IdP Settings.

 

Step 5: Set SAML SSO User ID settings

  1. Under the Single Sign-On tab, click on SAML Settings.
  2. Scroll down to the SAML User ID Settings section.
  3. It’s highly recommended to check the SAML User ID is Wdesk Username and Case-insensitive SAML ID settings. These allow Wdesk to expect the incoming Primary NameID attribute to match the Wdesk username, ignoring any case sensitivity, when the user logs in. For example, this allows User.Name.Example to match against user.name.example.
  4. Then click Save Changes.

SAMLuserIDsettings.jpg

 

However, if you’re unable to configure this due to policy, you’ll need to manually establish a SAML ID to Wdesk username mapping:

  1. Under the Single Sign-On tab, click on User Mapping.
  2. You can either upload a SAML ID .csv mapping file (see SAML ID .csv mapping file requirements), or manually set the SAML ID in each user’s profile (this will override the username match check).
OrgAdmin-SSO-UserMapping.jpg

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

 

Some other points to note are:

  • 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

 

Step 6: Set NameIdentifier Settings (optional)

Under the Single Sign-On tab and in SAML Settings, you’ll see the NameIdentifier Settings section.

By default, most configurations will have the NameIdentifier element in Subject statement setting checked. This means that Wdesk will check for the NameIdentifier element in the Subject statement.

However, you can change this setting so that the application looks for the attribute in the SAML response by selecting the NameIdentifier element is Attribute option, and pasting in the desired location. Then click Save Changes to save this setting.

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

 

name identifier.png

 

Step 7: Configure IdP Settings

To upload your IdP metadata XML file:

  1. Under the Single Sign-On tab, click on IdP Settings.
  2. Click Browse to locate and choose your file.
  3. Click Upload. Your changes will automatically save if the upload is successful.
    Note: If you’re using Azure as your identity provider, ensure that the IdP Initiated Sign-in URL field is left blank, or else there will be sign-in errors.
  4. If you want an IdP Sign-out Service URL and a Sign-out Redirect URL and those values aren’t found in your uploaded XML metadata file, then you’ll need to paste in those values separately in their respective fields in the Identity Provider Information section.

If you need to enter the IdP settings manually, instead of uploading a file, enter the appropriate details in the Identity Provider Information fields. The required fields are Identity Provider URL, Binding, Issuer, and Certificate. Then click Save Changes to finish.

UploadProviderMetadata.jpg

 

Step 8: Update SAML SSO requirement options

After you have configured SAML setup and validated that it's working properly, you can then update the SAML requirement options.

  1. Under the Single Sign-On tab and in the SAML Settings section, you’ll see the SAML requirement options:
    • Enable SAML Single Sign-On: Users can sign in with SAML SSO or continue to use their username and password.
      Note: This option must be checked in order for SSO to work correctly.
    • Require SAML Single Sign-On for Users: Non-admin users will be required to use SAML SSO (i.e. they’ll no longer be able to use their username and password), while Org Security Admins may continue to sign in using their username and password.
      Note: Make sure that you conduct comprehensive testing and that you're completely confident in your SAML SSO setup before enabling this option.
    • Require SAML Single Sign-On for Org Security Admins: Org Security Admins will be required to use SAML SSO (i.e. they’ll no longer be able to use their username and password). To enable this option, you’ll also need to check Require SAML Single Sign-On for Users.
  2. Click Save Changes.

saml settings.png

 

If desired, you can allow specific users to sign in without SAML SSO by adding them as a bypass user.

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

 

Was this article helpful?
7 out of 27 found this helpful
Org Security Admins can follow the steps below to configure SAML single sign-on settings for the organization. SAML-b...