Configure SSO Authentication in VMS

Overview

VAST VMS supports Single Sign-On (SSO) authentication using SAML-based Identity Providers (IdP). This allows VMS managers to sign-in to aVAST Cluster using their credentials an IdP such as Okta,

This guide describes how to configure this using Okta as the IdP.

When configured for SSO with an IdP, VMS acts as the SAML Service Provider (SP),

In the IdP, you must define roles (also referred to as groups in some IdPs) that map to roles in VMS. Users who use the IdP to sign on to VMS use one of these roles. When a user signs into VMS from the IdP using SSO, they receive permissions in VMS associated with the role in VMS that is mapped to the role in the IdP. If a role does not exist in VMS for the user, a Cluster Admin type user has only read-only permissions after signing in. For a Tenant Admin user, login fails if the user does not have a role.

For example, consider a user who has the role VMS Administrators in the IdP, which is mapped to the role VMS Administrators in VMS, with Admin permissions. When the user signs on to VMS from the IdP, they will have Admin permissions in VMS.

For clusters with multiple tenants, if you want to give users login permissions as tenant admins, you need to define the user type and the tenant on the IdP. The user type defaults to cluster admin and therefore does not need to be defined on the IdP for cluster admin users. Tenant admin roles must be configured in VMS for the specific tenant.

VMS does not preserve permissions for users who sign on using SSO. This means that if the role for a user on the IdP is changed to a different role, the user will have the permissions of the new role on VMS when they subsequently sign on to VMS.

VMS supports SP-initiated authentication and IdP-initiated authentication with the IdP. In SP-initiated authentication, the user selects the SSO sign-on option on VMS, and is redirected to the IdP from there to complete the authentication (for example, Okta). In IdP-initiated authentication, the user starts in IdP portal and selects VMS from there (for example, JumpCloud).

SAML Attributes Required by VMS for SSO

IdPs must return these attributes in the SAML assertion response for VMS user creation:

email. A unique identifier to create or update a user,
username. The name of the user
roles. The roles of the user as they appear in the VMS. If this attribute is missing from the assertion, the user only receives read_only permission. For example, if you define a role in VMS called SamlUser with specific permissions, and your IDP roles = SamlUser, all users that are assigned to this role by your IdP will receive this role in VMS with all the permissions you granted for it.
For tenant admin users, user_type. This assigns user type. Allowed values are SUPER_ADMIN for cluster admin access or TENANT_ADMIN for tenant admin login access. The default is SUPER_ADMIN.
Also for tenant admin users, the tenant_name must be set to the name of the tenant that the user should have permission to access.

Configuring SSO on a VAST Cluster

Configuring SSO using the VAST Web UI

On the VAST Web UI, navigate to the Administrators page, then select the SSO tab.
Click Add new identity.

In the General section, add these details for the Identity Provider:

IdP name	The name of the Identify Provider (e.g. Okta)
IdP Entity ID	The Entity ID for the Identity Provider, typically obtained from the metadata.
Force authenticate	Forces authentication with the IdP for each sign-on.

In the Metadata section, enter these details:

Metadata URL

The URL to the metadata on the IdP, usually in the form

<https://<idp-url>/sso/saml/metadata

where idp-url is the URL of the IdP.

Local metadata

Use metadata stored locally on VMS. This is an alternative to including a Metadata URL.

Paste metadata text in the box.

In the Assertions and Certificates section you can optionally enable and configure encryption for SAML assertions and responses. If enabled, you must also provide or upload certificates.
To enable encryption of SAML assertions, toggle Enable assertion encryption. If enabled, follow these steps to configure a certificate and key.
1. Click Add certificate.
2. Paste an X.509 certificate in the box or click Upload, and upload an X.509 certificate file.
3. Click Save to save the certificate.
4. Click Add key.
5. Paste an X.509 key in box or click Upload, and upload an X.509 key file.
6. Click Save.
To enable signatures on SAML assertion responses, toggle Enable assertion response signing . If enabled, follow these steps to configure a certificate and key.
This is enabled independently of the Enable assertion encryption option. The certificate and key used for this option can be different from the ones used for Assertion Encryption.
1. Click Add certificate.
2. Paste an X.509 certificate in the box or click Upload, and upload an X.509 certificate file.
3. Click Save to save the certificate.
4. Click Add key.
5. Paste an X.509 key in box or click Upload, and upload an X.509 key file.
6. Click Save.
Note
The selections here for encryption and signing must match the corresponding selections on the IdP. For example, if assertion encryption is set on the VMS, it must also be set on the IdP.
Click Save.
The IdP is now configured on the cluster.
For a cluster with multiple tenants, to use the IdP for authorizing tenant admin users, enable the IdP on each tenant.
To enable the IdP on an existing tenant:
1. In the Tenants tab of the Element Store page, right-click the tenant and select Edit.
  In the Providers and Users section of the tenant edit dialog, now that there is a SAML IdP configured on the cluster, SAML appears in the list of provider types with "None Selected".
2. Click SAML and then select the configured IdP on the right.
3. Click Update to save your change.
Similarly, when creating a new tenant after configuring the IdP, in the Create Tenant dialog, in the Providers and Users section, select SAML and then select the specific provider configuration.
Make sure there is a role on the cluster that maps to each user's roles as configured on the IdP with the roleattribute. For tenant admins, SSO login to the tenant VMS will fail if no role is configured on the tenant and matches the user's role attribute on the IdP.
To create or modify a role, see Managing Administrative Roles in VAST Web UI.Managing Roles

Configure an Identity Provider for SSO using the VAST CLI

On the VAST CLI use the vms modify_saml command to create or modify the VMS Identity Provider configuration for Single Sign-On:vms modify_saml

vcli: admin> vms modify_saml --idp-name Okta --idp-metadata-url https://45678910.okta.com/app/ekxm4bscg4RuruH8C5g7/sso/saml/metadata --idp-entityid http://www.okta.com/ewkh4aftf7NerrH4C5t1
This action will impact you saml login with Okta.
 Are you sure you want to continue? [y/N] y
Saml Config as been changed for Okta

For a cluster with multiple tenants, to use the IdP for authorizing tenant admin users, use the tenant modify command to enable the IdP on each tenant:
```
vcli: admin> tenant modify --id 3 --identity-provider-name Okta
Are you sure you want to modify the tenant? [y/N] y
```
Make sure there is a role on the cluster that maps to each user's roles as configured on the IdP with the roleattribute. For tenant admins, the role needs to be configured for the tenant (iamrole create):
```
vcli: admin> role create --name tenantrole --tenant-id 3
```

Commands for Configuring IdPs for SSO in the VAST CLI

Use the following commands to configure IdPs for SSO:

vms modify_saml. Add or modify an IdP in VMS. If encryption options are selected, you will be prompted to enter a certificate and key.
vms remove_saml_signed_cert. Remove all signed certificates from an IdP configuration.
vms delete_saml_idp_configuration. Remove a SAML IdP configuration from VMS.
vms show_saml_config. Show details for a SAML configuration for a specific IdP.
vms show_saml_configured_idps. List all IdPs configured in VMS.

Login to a VAST Cluster using SSO

Once you have configured VMS for SSO, using your chosen IdP, you can login to VMS using your IDP.

On the VMS login page, click SSO Login With <IDP_Name> .

You are redirected to the IdP to login there, and then back to VMS. Your permissions on VAST Cluster are determined by the permissions configured for you in the IdP.

If you configured more then one IdP, the SSO Login With shows a drop down list. Select the provider to use for the login. Your permissions on the VAST Cluster are determined by the permissions configured for you in the selected IdP.

Note
SSO cannot be configured to enable access to the VAST CLI or REST API.

Configuring the Okta IDP for SSO login to VMS

Okta uses a SAML application to mediate SAML-based SSO. This is configured on Okta.

Sign in to Okta.
Select Applications > Create App Integration > SAML 2.0 to create a new SAML application.
Configure your application:
1. Enter a name for your application and click Next.
2. Configure the SSO URL for the VAST Cluster (as the SAML SP) in the format https://<mgmt-vip>/api/saml2/metadata/, where <mgmt-vip> is the Virtual IP address of the VAST Cluster.
  Note
  You can also obtain the SSO URL from VMS by running show_saml_config from the VCLI; the URL is included in the response
3. For the Audience URI (SP Entity ID) enter https://<mgmt_vip>/api/saml2/metadata/. where <mgmt_vip> is the VIP for VMS.
4. Change the Name ID format to EmailAddress and Application username to Email.
5. If you need to support tenant admin users on a cluster with multiple tenants, extend the profile to add the custom field tenant_name. (user_type is also needed but this is already provided on Okta). For information about how to do this, see Okta documentation.)
6. If a signed certificate or encryption is required, select Show Advanced Settings and view the certificate in the SP configuration.
7. Enter the username, email, and optionally, (needed for tenant admin support), tenant_name and user_type, in the Attribute Statements pane. Enter the role Name and Name Format attributes in the Group Attribute Statements pane. With the roles attribute, this configuration enables the IDP to return the correct values for the user creation in VMS.
8. Click Next and select I'm an Okta customer adding an internal app, then click Finish.
9. To create a user, select Directory > People > Add person.
10. To create a group, select Directory > Groups > Add group.
11. Select each group name and assign users to it.
12. Configure each user's and group's attributes so that all of the required attributes are populated:
  - All users: email and username
  - All groups: roles
  - Tenant admin users: Set user_type to TENANT_ADMIN. Set tenant_name to the name of the tenant.
Open the Application tab, select the application and click Assign Users to App to assign users to the application. Select the necessary user and click Assign.

Editing your Okta Application Settings

To edit the Okta application settings in Okta, in the Application tab, select Application > Choose your application. You can then edit your application in the General tab.
To configure your SAML settings click Edit for the SAML settings.