With our Enterprise or Institution plans you are able to use Single sign-on (SSO). SSO allows users of your Vevox account dashboard or participants in your Vevox sessions to log in using your existing SAML-enabled ID provider, such as Active Directory, Ping Identity, Shibboleth and many more.
There are 2 types of SSO you can setup for Vevox:
- Dashboard SSO - This controls access to your Vevox account dashboard, so only people in your Organization/Institution can create and manage Vevox Sessions. This means users do not have to keep track of yet another email and password. It also makes provisioning new users to the account simple.
- Participant SSO - This allows you to make your Vevox sessions authenticated so only people from your organization/institution are able to access your internal Vevox sessions.
Dashboard SSO
How dashboard SSO works
Security Assertion Markup Language (SAML) is a standard protocol that gives identity providers (IdP) a secure way to let a service provider (SP) such as Vevox know who a user is.
Once configured, users can authenticate with the following process:
-
The user navigates to your Vevox account (e.g. https://mycompany.vevox.com).
-
Vevox presents the user with the option to 'Login with SSO'.
-
When clicked, the user's browser will be redirected to the identity provider.
-
The identity provider authenticates the user.
-
Once authenticated, the browser is redirected to Vevox with a SAML assertion.
-
Vevox verifies the SAML assertion and provisions new users.
-
User is granted access to Vevox.
Configuring dashboard SSO
The first thing you will need to do is set up your Identity Provider and generate your IdP metadata file. To do this you will need your Vevox Entity ID and Reply URL.
- Go to the Account section of your dashboard
- Select the Admin Settings
- Select the SSO tab
- Select 'Enable Dashboard SAML SSO'
Here you will find the Entity ID and Reply URL required to set up your IdP. Optionally you can use the Service Provider Metadata file and upload it to your IdP instead.
This will allow you to generate your IdP metadata file.
Upload your IdP Metadata file by pressing 'Select IdP Metadata'
Choose how you want to manage the provisioning of new users.
- Autoprovision OFF - you will need to invite users to join the account before they are granted access to Vevox. In order to do this there needs to be a person within your organisation with the Vevox User Manager role to send out invitation to people you wish to grant access to.
- Autoprovision ON - anybody in your organisation will be granted access straight away to Vevox. This is the easiest and most frictionless experience for people in your organization to gain access and start using Vevox straight away.
When you have finished press 'Save'
You can now go to your account login page (e.g. https://mycompany.vevox.com) and select 'Login with SSO'. From this page there is still the option to login with your normal email and password by pressing 'Admin login'
User Attributes - Dashboard SSO
The SAML identity provider must be configured to provide three attributes: EmailAddress, FirstName, and LastName.
These attributes allow Vevox to properly identify the user and automatically provision users. There is also a forth optional attribute called UPN which can be used when users may have alternate email addresses.
Email Address - Every user in your Vevox account is required to have a valid email address, even when using SSO. Since the identity provider is responsible for managing user information, it must send the user's email address to Vevox in its assertion. Different Identity providers use different naming conventions, Vevox supports email address with the following attribute names:
- EmailAddress
- emailAddress
- User.email
- http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
- emailaddress
First Name - As with email addresses, identity providers may send the first name in several common fields. Vevox supports first name with the following attribute names:
- FirstName
- first_name
- firstname
- firstName
- User.FirstName
- http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname
- givenname
- givenName
Last Name - Vevox supports last name with the following attribute names:
- LastName
- last_name
- lastname
- lastName
- User.LastName
- http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname
- surname
- surName
UPN - This can be used in scenarios where your users may have more than one email address for example when an email address used to login to the IdP differs from the email address that a user may send and receive email from.
- SecondaryEmailAddress,
- SecondaryEmail,
- AlternateEmailAddress,
- AlternateEmail,
- UserPrincipalName,
- userprincipalname,
- UPN,
- upn,
- http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name
- secondary_email
When users exist in Vevox before you implement SSO
After enabling SSO, a user that signs in with SAML for the first time will be linked with their previous authentication details, providing the email address is the same. This means any session created while they logged in with their normal password will still be accessible now that they are using SAML to authenticate instead.
If the email address in the SAML configuration is different to the email address that the person previously used to log in with then they will be registered as a different person. Should this happen then you can contact us and we will be able to assist in making sure the user can access their previously created sessions.
Participant SSO
How participant SSO works
When enabled, participant SSO allows your users to force participants to be authenticated before they join a session. Firstly an Account Admin must configure participant SSO. Once configured it will appear as an extra option for everyone in the account when setting the privacy and identification settings of their sessions.
Configuring participant SSO
The first thing you will need to do is setup your Identity Provider and generate your IdP metadata file. To do this you will need your Vevox Entity ID and Reply URL.
- Go to the Account section of your dashboard
- Select the Admin Settings
- Select the SSO tab
- Select 'Enable Participant SAML SSO'
Here you will find the Entity ID and Reply URL required to set up your IdP. Optionally you can use the Service Provider Metadata file and upload it to your IdP instead.
This will allow you to generate your IdP metadata file.
Upload your IdP Metadata file by pressing 'Select IdP Metadata'.
Optional - Configure different access groups. If your IdP supports it, and you have some defined groups within it, then you can configure groups here to allow you quick access to specific groups of people.
Paste in the Group ID provided by your IdP and give the group a name.
When a group is defined, it will present the session host with the option of only allowing that specific group of people to access the session through the app.
When you have finished press 'Save'.
User Attributes - Participant SSO
As listed above in the Dashboard SSO setup the SAML identity provider must be configured to provide three attributes: EmailAddress, FirstName, and LastName.
If you additionally want to use the optional 'Groups' feature the IdP must also be configured to provide an attribute for that. Valid Group user attributes are:
- Groups
- Group
- groups
- group
- http://schemas.microsoft.com/ws/2008/06/identity/claims/groups
- Roles
- Role
- roles
- role
- http://schemas.microsoft.com/ws/2008/06/identity/claims/role
Applying authentication to a session
When SSO have been enabled to your account you can find the option to enable it per session under the 'Identification' tab of the settings section.
In order to use SSO authentication your session must be set to 'Identified'.
When enabled the default setting will be that everyone within the organization/institution will be able to access the session.
Alternatively, you can select one of the pre-defined groups, if those have been created, or you can enter in the specific email address of people in the organisation/institution. Entering specific email addresses of people is a way to restrict access to certain individuals rather than a group of people.
FAQ
Can we use the same metadata file for both dashboard and participant configurations?
Yes, if your IdP supports multiple reply URL's then it is possible to use the same metadata file for both setups. However, for clarity and to safeguard against any future changes or increased functionality we recommend it would be best to set up 2 apps in your IdP to handle this.
If you have any further questions or require help in setting up your SSO please contact us support@vevox.com.