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:
Config Option | Config Value |
Single sign on URL | https://app.vitally.io/saml/yoursubdomain/assert (or https://app.vitally-eu.io/saml/yoursubdomain/assert if your account is EU) |
Audience URL | https://app.vitally.io/saml/yoursubdomain/ (or https://app.vitally-eu.io/saml/yoursubdomain/ if your account is EU) |
Default RelayState |
|
Name ID format | EmailAddress |
Application username | |
Response | Signed |
Assertion Signature | Signed |
Signature Algorithm | RSA-SHA256 |
Digest Algorithm | SHA256 |
Assertion Algorithm | Encrypted |
Encryption Algorithm | AES256-CBC |
Key Transport Algorithm | RSA-OAEP |
Encryption Certificate | Attached, above |
Enable Single Logout | Disabled |
Authentication Context Class | PasswordProtectedTransport |
Honor Force Authentication | Yes |
SAML Issuer ID |
|
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:
Attribute | Type | Description |
firstName | string | The user's first name |
lastName | string | The user's last name |
vitallyRole | string | Provide a string value for vitallyRole: admin, leader, team, observer |
title | string | The user's job title |
timezone | string | The user's home timezone, used for sending windows and email notifications |
avatar | string (url) | The user's profile picture |
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:
vitallyRoleName 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" : nullThis 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.
FAQ
Q: Does Vitally support SCIM for Okta SSO?
A: No, SCIM connections for Okta SSO are not supported at this time.