VT Writer on-prem supports Single Sign-On(SSO) through SAML 2.0. When SSO is enabled, users can sign in to VT Writer using your organization's login system and credentials e.g. Microsoft Active Directory Federation Services (ADFS), Ping, Okta etc.
In SAML terminology VT Writer is a "Service Provider" and your organization's authentication system is an "Identity Provider". To setup SAML SSO, you need to :
- Configure VT Writer Security Settings and provide your Identity Provider's SAML information.
- In your Identity Provider (e.g. ADFS) - setup VT Writer as a Service Provider (aka "Relying Party Trust").
- Test and enable SAML SSO in VT Writer .
Note: The VT metadata is generated on demand and the EntityID is based on the browser request URL e.g. browser request to 192.168.0.666/saml/metadata. It uses a cert that it has locally on the VM/Instance.
1. Configure VT Writer Security Settings
To review your current Security Settings :
- login to the Writer application. Note you must have the 'System Admin' role in order to access the Security Settings
- click on Security Settings icon in the sidebar
Out of the box, VT Writer is configured to use it's own local Username/Password credentials.
To get started with Single Sign-On, click Single Sign-On:
You must supply your Identity Provider's :
- Entity ID
- SSO url
- x509 certificate
If you don't already know these values your Identity Provider will have a way to obtain it's metadata xml file. The metadata xml (usually available through a url e.g. https://adfs.example.com/FederationMetadata/2007-06/FederationMetadata.xml) should have the following elements :
2. Setup VT Writer (as a Service Provider) in your Identify Provider
This section is carried out within your Identity Provider (e.g. ADFS) and the steps required are particular to each Identity Provider. The VT Writer metadata xml file will provide most of the information that you will need to setup VT Writer as a Service Provider in your Identity Provider. You can obtain the VT Writer metadata from the above screen in VT Writer | Security Settings :
This MetaData file is auto-generated based on the URL you use when you first access the VisibleThread web application. After you download the MetaData file, please review it to ensure that the URLs for the Entity Descriptor's entityID and the Assertion Consumer Service's Location are set to the same URLs the users will access.
Example Entity ID:
Example Assertion Consumer Service Location:
If these are instead set to either the appliance hostname or IP address then
- First the VT services will need to be restarted on the server -
services supervisor restart
- Second, navigate to the web application using the URL the users will access and review the newly-generated MetaData file.
We require that end-users have an email address associated with their Identity in your Identity Provider and that there is a claim created that maps a user's email address to the SAML attribute "Name ID".
For detailed steps to setup VT Writer in ADFS see Setup Single Sign-On for Active Directory and VT Docs on-prem
3. Test and Enable SAML SSO
Once you have completed the above 2 steps you are ready to test out your SSO configuration. In VT Docs, click Test Login :
This will open a new window and should prompt you to login to your Identity Provider. Enter your credentials and if everything is setup correctly you should see :
To save your changes and enable SAML SSO for all users, click Apply Changes.
You will be signed out of the application.
End-user Login Experience
Once SSO is enabled, VT Writer will authenticate users against your Identity Provider when they open VT Writer in their web browser.
If a user does not have an active session with your Identity Provider then they will be re-directed to your Identity Provider's login url. Once a user is successfully authenticated against the Identity Provider then the browser will re-direct the user back to VT Writer.
Note: To access VT Writer the user must already exist in the VT Writer system and the VT Writer username should be the email address sent int he SAML "NAME ID" assertion. By default Writer does NOT auto-provision SSO users as VT Writer users. You can enable auto-provision (see below . In the case where a user does not already exist in the VT Writer system, the user will see this screen :
As described above, by default VT Writer requires that end-users be registered in the Writer application prior to signing in via SSO.
You can choose to enable 'auto-provision' by navigation to the 'System Admin' menu and selecting 'System Settings'. Once auto-provisioning is enabled, any new users that sign in via Single Sign On will be added as users to the Writer system, provided there are user licenses available.
If a new user attempts to sign with auto-provisioning enabled, but no user licenses are available, they will be prompted with the following message: