Introduction
Viima provides customers to ability to use their own SAML-based Identity Providers (IdP) for Single-Sign On (SSO).
This guide shows you the specifics steps needed to do this with Microsoft AD FS. However, the same principles apply for other SAML IdPs too.
Prerequisites
To be able to use Microsoft Active Directory Federated Services (AD FS) Single Sign-On (SSO) to log in to your Viima board, the following prerequisites must first be met:
An Active Directory instance (AD)
An active Viima Unlimited or Enterprise subscription
Admin access to a Viima board (for credentials, please contact your Viima super user)
A server running Microsoft Server 2012 or 2008
An SSL certificate to sign your AD FS login page with and the fingerprint for that certificate.
Collected data
Viima collects the following data from the AD FS:
User Principal Name
E-mail address
First name
Surname
User Groups (optional)
User Groups is an optional field that is only required when the board access restriction is set to "Allow listed users and users belonging to any of the following users groups". In that case, please ensure to provide the User Group information when creating the claim rules by adding a claim for the User Group LDAP attribute (step 4 of "Creating claim rules"). After that, you can enable the access restriction "Allow listed users and users belonging to any of the following user groups" in Viima and list the desired user groups for which you wish to grant access to the board.
Overview
Adding a Relying Party Trust
Creating claim rules
Configuring Viima
Adding a Relying Party Trust
Step 1:
Go to the AD FS Management console on your AD FS server.
Step 2:
Add a new Relying Party Trust by clicking "Add Relying Party Trust” from the “Action" dropdown menu.
Step 3:
Click “Start” on the opening wizard.
Step 4:
Select "Import data about the relying party published online or on a local network" and enter the following URL into the Federation metadata address:
Then, click "Next".
Step 5:
Enter a Display name for the Relying Party Trust, for example, “Viima”.
Then, click “Next”.
Step 6:
On this screen, you may configure multi-factor authentication (MFA) for your AD FS login.
While this is an optional step you may choose to skip, we highly recommend using MFA. The exact steps are beyond the scope of this guide, so please refer to these instructions for more details. Once you're done, click “Next”.
Step 7:
Select "Permit all users to access this relying party".
Then, click “Next”.
Step 8:
On this screen, the wizard will display an overview of your settings. You can directly proceed by clicking “Next”.
Step 9:
Make sure the “Open the Edit Claim Rules dialog for this relying party trust when the wizard closes” checkbox is marked and click "Close".
This will automatically open the "Edit Claim Rules" dialog.
Creating claim rules
Once the relying party trust has been created, you can add claim rules and update the RPT with minor changes that aren't set by the wizard. If you completed all steps up to this point, the claim rule editor should open automatically.
Step 1:
Click “Add Rule”.
Step 2:
From the dropdown menu under "Claim rule template:", select “Send LDAP Attributes as Claims”.
Then click "Next".
Step 3:
Enter a name for your claim rule, for example, “User attributes”.
Step 4:
From the dropdown menu under "Attribute store:", select "Active Directory".
Under "Mapping of LDAP attributes to outgoing claim types:", create the following claim rules:
Given-Name | Given Name
Surname | Surname
E-Mail-Addresses | E-mail Address
User-Principal-Name | UPN
Then click "Finish"
Warning: If your AD FS server later changes the format or content of the fields used in this mapping, you are likely to encounter errors in the integration. Most commonly from changing the UPN or email address fields, which may lead to users being unable to access Viima.
We recommend you remind IT to document this dependency properly to make sure the claim rule mappings are updated and tested correctly if changes must be made to the used fields.
Configuring Viima
If you already know your board name, the easiest way to get to access rights is through the following URL:
https://app.viima.com/admin/organization-name/board-name/#settings/access
If you do this, proceed directly to Step 3. Otherwise, start from Step 1.
Step 1:
On your Viima Admin account, go to "Settings" in the admin portal of your board.
Step 2:
Go to the "Access rights" sub-section.
Step 3:
Collapse the "Access restrictions" panel.
Step 4:
Mark the "Require login" checkbox.
Step 5:
Choose "SAML 2.0 (AD FS, Okta)" from the login options and click the "Connect to a SAML service" button.
Step 6:
In the "Login URL" field, fill in the Login URL of your SAML service. For example, https://ad.viima.com/adfs/ls/idpinitiatedsignon.
Step 7:
In the "Entity ID" field, fill in your SAML service Identifier. For example, https://ad.viima.com/adfs/services/trust.
This can be found in the AD FS Management console which we opened earlier in this guide (Step 2 of Adding a relying trust party).
In the AD FS Management console, click "Edit Federation Service Properties...” from the “Action" dropdown menu.
From here, you can find your Entity ID under "Federation Service Identifier"
Step 8:
In the text field next to "Certificate fingerprint (SHA1)", fill in your SHA-1 encrypted fingerprint.
The fingerprint can be acquired by running the following PowerShell command on the system with the installed certificate:
C:\> Get-AdfsCertificate
PS. Make sure to use the Token-Signing fingerprint.
Step 9:
Click "Connect".
Congratulations!
You should now have a working AD FS SSO implementation for your Viima board. To test the integration, please log out and try to sign in to your Viima board with AD FS by using a valid account that is in the Active Directory.
If you face any issues with logging in using Internet Explorer, please see our guide for Troubleshooting issues with Internet Explorer.
Troubleshooting SSL certificate expiration & rotation
Please note that SSL certificates typically have an expiration date, which means that you will need to rotate the certificate regularly (often annually) and update the new fingerprint to Viima to keep the integration functional.
This is by far the most common problem and root cause for issues customers face with SAML-based integrations. So, if your SSO login suddenly stops working, this is likely the reason for it.
As such, we recommend creating an internal IT task for updating the certificate fingerprint immediately with the certificate expiration date as the deadline. This helps ensure your integration remains functional at all times.
To update the new certificate from AD FS, you can simply paste the updated fingerprint to the existing AD FS configuration of a Viima board as shown in Step 8 above and click save without repeating the other steps. These instructions may be helpful for your IT, so please pass them along with such rotation requests.
Don't forget to save your changes!
Green "Save" buttons can be found on all pages where changes can be made. Clicking this activates those changes.