VT Docs on-premise supports Single Sign-On(SSO) through SAML 2.0. When SSO is enabled, users can sign in to VT Docs using your organization's login system and credentials e.g. Microsoft Active Directory Federation Services (ADFS), Ping, Okta etc.
In SAML terminology VT Docs is a "Service Provider" and your organization's authentication system is an "Identity Provider". To setup SAML SSO, you need to :
- Configure VT Docs Security Settings and provide your Identity Provider's SAML information.
- In your Identity Provider (e.g. ADFS) - setup VT Docs as a Service Provider (aka "Relying Party Trust").
- Test and enable SAML SSO in VT Docs.
- (Optional) Create an environment file for the application to automatically insert your domain into metadata. This requires VT Docs v4.4.3 or later
Note: If optional step four isn't configured, Then 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 Docs Security Settings
To review your current Security Settings :
- login as the System Admin user
- click on Security Settings icon in the sidebar
Out of the box, VT Docs is configured to use it's own local Username/Password credentials.
To get started with Single Sign-On, click Single Sign-On and notice the SSO Settings are now highlighted :
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 :
- EntityDescriptor.entityID
- EntityDescriptor.IDPSSODescriptor.SingleSignOnService.Location
- EntityDescriptor/IDPSSODescriptor/KeyDescriptor/KeyInfo/X509Data/X509Certificate
2. Setup VT Docs (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 Docs metadata xml file will provide most of the information that you will need to setup VT Docs as a Service Provider in your Identity Provider. You can obtain the VT Docs metadata from the above screen in VT Docs | 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.
VT Docs Red Hat
sudo systemctl restart visiblethread-docs
VT Docs Ubuntu
/home/visiblethread/VisibleThreadTools/vt-restart-server.sh
- 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 Docs in ADFS see Setup Single Sign-On for Active Directory and VisibleThread 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 Save Settings and then Confirm :
End-user Login Experience
Once SSO is enabled, VT Docs will authenticate users against your Identity Provider when they open VT Docs 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 Docs.
Note: To access VT Docs the user must already exist in the VT Docs system and the VT Docs username should be the email address sent int he SAML "NAME ID" assertion. We do NOT auto-provision SSO users as VT Docs users. In the case where a user does not already exist in the VT Docs system, the user will see this screen :
For details on adding users see How do I add/remove users from VisibleThread
Troubleshooting
SSO Configuration Issues
If you see either of the following messages when you Test Login from your SAML configuration :
- then this suggests that you have entered an invalid or expired x509 certificate in the VisibleThread Security Settings.
When you Apply changes to your Security Settings we will validate your certificate and report any issues e.g. :
User Login - Access Denied
If a user logins in through SAML but they get the following Access Denied message -"NameID element must be present..."
Then this indicates that either:
- the user does not have an email address associated with their Identity; OR
- the claim (configured in your Identity Provider) that maps a user's email address to the SAML attribute "Name ID" is either missing or not setup correctly.
4. Configuring environment file
This requires VT Docs v4.4.3 or later
To have VT Docs use your domain name as the EntityID, you can create an environment file that VT Docs will pickup every time the service is restarted. As noted at the start of this article if this optional step isn't configured, Then 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.
Create a file called 'visiblethread.env' in the following directory
# Ubuntu and Red Hat Deployments
/etc/default/
# Windows Deployments
C:\Program Files\VisibleThread\vtdocs\
Now edit the file with a text editor of your choice and insert the following line, replacing "yourdomainhere" with your domain for the VT Docs server:
vtdocs.hostname=yourdomainhere
Now save and exit the file.
Verify that the file gets picked up when the service restarts. You can do this by restarting the service:
# Ubuntu
sudo service supervisor restart
# Red Hat
sudo systemctl restart visiblethread-docs
# Windows
Search for Services. In the services panel look for vtdocs-tomcat, right-click and restart
After restarting the service, check the application log for the following line:
INFO: Load default configuration from file : /etc/default/visiblethread.env
Open the application log with a text editor of your choice. The log is located at:
# Ubuntu
/home/visiblethread/tomcat/logs/catalina.out
# Red Hat
/opt/visiblethread/tomcat/logs/catalina.out
# Windows
C:\Program Files\VisibleThread\vtdocs\tomcat\logs\catalina.out
Once you have verified the 'visiblethread.env' file is picked up by VT Docs you are then finished configuring.