SSO via Okta

SSO via SAML 2.0 is available on Custom Plans and all our 2022 new plans.

Create a new Vitally application in Okta

In your Okta application settings, add a new application and select "Create New App." Choose "Web" as the platform and "SAML 2.0" as the sign on method:

Name the application "Vitally" and choose the appropriate visibility settings for your organization:

You can use the following image for the app logo:

Configure SAML settings

Add the following settings to your SAML config. You'll need to "Show Advanced Settings" to add all of the encryption-related fields.

The single sign-on URL and Audience URI are both based on your account's subdomain in Vitally. When you login to Vitally, your account is hosted at https://yoursubdomain.vitally.io (or https://yoursubdomain.vitally-eu.io if your account is EU). Make sure to 'yoursubdomain' with your specific account's subdomain.

The encryption certificate you need is attached here:

The table here contains the configuration you should setup for the Vitally application's SAML settings:

The SAML Issuer ID and default RelayState are intentionally left blank - leave them empty in your config as well

The end result will look like this:

Configure SAML Attributes

You can configure Okta to send attributes about each user to Vitally that will be synced on login. Vitally supports the following attributes:

We recommend setting up at least the firstName and lastName attributes:

Below are tips for setting up the vitallyRole attribute in Okta. As outlined above, this attribute provides the user's permission set and is sent to Vitally in every SAML assertion. It's important that this is set correctly in Okta so your team has the right permissions in Vitally!

Before you dive into either method below, it’s important to set up an application-specific attribute in Okta for Vitally. This will need to be called vitallyRole. To learn how to add a custom attribute to an application in Okta, check out this handy Okta Documentation on Custom Attributes.

Method 1 (most common): Using a User Profile Attribute in Okta

Add the vitallyRole attribute to the Okta SAML attribute statements with the following setup:

  • Name: vitallyRole

  • Name Format: Unspecified

  • Value: appuser.vitallyRole

Each user will need a vitallyRole set on their profile. This method ensures the designated role is passed within the SAML assertion via appuser.vitallyRole

Method 2: Using Okta Expression Language

If you prefer dynamic role assignment based on group membership, you can use Okta Expression Language in the attribute statements:

Expression:

user.isMemberOfGroupName("app-vitally-admin") ? "admin" :
user.isMemberOfGroupName("app-vitally-leader") ? "leader" :
user.isMemberOfGroupName("app-vitally-team") ? "team" :
user.isMemberOfGroupName("app-vitally-observer") ? "observer" : null

This method checks group membership at login and dynamically assigns roles, making sure the SAML assertion includes the right role every time.

Okta may change its attribute configuration support at any point, and we might not be able to assist with those changes. If you run into any issues, please reach out to Okta support for help.

Send SSO Instructions to Vitally

Once you've setup Vitally as a service provider in Okta, we'll need to manually enable Okta as the identity provider in Vitally. From the Okta application, press View Setup Instructions:

Vitally will need all three pieces of information displayed on that page to finish setup:

  • Identity Provider SSO URL

  • Identity Provider Issuer

  • X.509 Certificate (Download this and send as an attachment to your Vitally contact)

Login

That's it! When Vitally has completed our server-side setup, you'll be presented with the following login screen the next time you login!

If your users have already logged in using password authentication, their existing authorization will be valid for up to a week. Ask them to log out & log back in to force SAML authentication.

Last updated