Setting up SAML v2 SSO via Okta

Before you start

SSO via SAML 2.0 is only available on Vitally's enterprise plans. Contact support@vitally.io, your account manager, or the team via live chat to discuss upgrading to a plan that supports SAML 2.0

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. 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

Audience URL

https://app.vitally.io/saml/yoursubdomain/

Default RelayState

Name ID format

EmailAddress

Application username

Email

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

number

The user's permission level in Vitally. 1 = Restricted, 2 = Admin

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:

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:

User-uploaded Image

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

Do you support SAML just-in-time provisioning?

Yes, Vitally supports SAML just-in-time provisioning. When a user logs in for the first time using SAML, a user will created for them in Vitally. If you've added the vitallyRole attribute, that will determine the user's permission level in Vitally. Otherwise, they will default to being a 'restricted' user.

Will users be able to login with a password anymore?

No, password login is disabled as soon as SAML 2.0 login is enabled.

Will SAML login go into effect immediately?

Existing user sessions will be valid for up to 7 days. Ask each of your users to log out and log back into Vitally to force them to immediately start using SAML login.