Setup a SAML 2.0 SSO Identity Provider

Owned by HB Farris
Nov 14, 2023
4 min read

IdP-Initiated Authentication Not Supported

VERA does not currently support Identity Provider (IdP) initiated authentication. It is recommended that clients disabled any authentication links from their IdP to prevent user confusion. Click here for example instructions to hide the login buttons from Okta and Azure.

Prerequisites

As of VERA Web Portal 1.6.1, SSO requires the use of HTTPS. SSO will not function over a HTTP connection due to changes made by Chromium and the SameSite parameter.

Gather SAML IdP Information

Before enabling SAML integration for VERA, gather the following information:

Information or FileDescription / Example
SAML IdP Provider ID

The Entity ID of the Identity Provider.

Example: Tx3IDP

SAML IdP Certificate(s)The public certificate(s) for the Entity IDs created for VERA logins and VERA Signatures. This can be one or more certificates.

Create Endpoints for VERA

In your Identity Provider, create the following endpoints and record the Entity IDs assigned.

The IdP endpoint for the Tx3VERASignatures entity ID must accept either the ForceAuthN parameter or the "urn:oasis:names:tc:SAML:1.0:am:password" Authentication Context to force re-authentication.


EndpointExample Entity IDAssertion Consumer Service URLSingle Logout URL (optional)
VERA Login EndpointTX3VERAhttps://your.vera.web.url/saml/AssertionConsumerServicehttps://your.vera.web.url/saml/SingleLogoutService
VERA Signature EndpointTX3VERASignatureshttps://your.vera.web.url/saml/SignatureAssertionConsumerServiceNot Used


The Entity ID values are configurable in the config.yaml file in the Configs folder. This is especially useful if you have several VERA instances pointed to the same IdP. To update the Entity IDs, simply edit the following lines in the Config.yaml file.

config.yaml file
# SAML configs
  samlEntityId: TX3VERA
  samlSignaturesEntityId: TX3VERASignatures

Server Setup

Upload the Certificates to VERA Server

All certificates should be placed in the Certificates directory inside of the VERA Server Data Directory.

Create or update the identity-providers.yaml file

If needed, create a plain text file in the Configs directory in the VERA Web Portal Data Directory. The file must be named identity-providers.yaml and should have the following structure:

identity-providers.yaml
https://server.com/saml2/spassertion_consumer:
  type: SAML
  loginUrl: https://example.com/SAML/SingleSignOnService
  logoutUrl: https://example.com/SAML/SingleLogoutService
  certificateNames: login_endpoint.crt, signature_endpoint.crt
Element (line #)YAML KeyDescription
IdP Provider Name (1)N/AThe SAML IdP EntityID from above. This is typically found in the first line of the IdP's metadata xml file and is labeled the entityID.
IdP Type (2)typeThe type of connection being used. Currently the only supported type is SAML.
Login URL (3)loginUrlThe URL where users will be redirected to log into the IdP.
Logout URL (4)logoutUrlThe URL to redirect to when users log out of VERA. This can be left blank.
Certificate Names (5)certificateNamesA comma-separated list of certificates that will be used to validate the SAML Response from the IdP.
 Click here if you are using OKTA for your Identity Provider

If you are using OKTA for an IdP, then you will need to configure additional parameters in the identity-providers.yaml file.

Procedure to set up Okta for SSO with VERA

  1. Setup two endpoints in Okta: one for login and one for signatures.
  2. The Single Sign On URL, Recipient URL and Destination URL should all match the Assertion Consumer Service URL from your VERA Server.
  3. The Audience Restriction should match the Entity ID defined in the config.yaml file.
  4. The Name ID Format should be "Unspecified".
  5. Check the boxes "Do not display application icon to users" and "Do not display application icon in the Okta Mobile app".

  6. Configuration the identity-providers.yaml file with the following additional parameters:

    identity-providers.yaml
    http://www.okta.com/exkt2n6agFLZj#######: <-- Login  Endpoint Issuer ID
  type: SAML
  loginUrl: https://dev.okta.com/app/veraoktalocal_1/exkt2n6agFLZ########/sso/saml <-- Login Endpoint URL
  logoutUrl: 
  signaturesId: http://www.okta.com/exkt2n6cfwgZS######## <-- Signatures Endpoint Issuer ID
  signaturesUrl: https://dev.okta.com/app/verasignatureslocal_1/exkt2n6cfwgZS########/sso/saml <-- Signature Endpoint URL
  certificateNames: okta.cert, okta-sig.cert
    Element (line #)YAML KeyDescription
    Signatures ID (5)signaturesIdThe SAML Issuer ID from Okta for the Signatures endpoint.
    Signatures URLsignaturesUrlThe Okta App Link for the Signatures endpoint.

Change the Authentication Context for the Signature SAML Requests

New in 1.10! Configurable Authentication Contexts

VERA, by default, sends the SAML AuthnContext – "urn:oasis:names:tc:SAML:1.0:am:password" – when a user requests a signature authentication. You can change this by adding a configuration line to the Identity Provider in the identity-providers.yaml file.

Add the "samlAuthnContexts" element to the configured SAML Identity Provider and enter the exact authentication context needed. Text must match the context exactly as VERA will not validate the context. If the "samlAuthnContexts" element is blank or missing, VERA will continue to send the SAML 1.0 password authentication context.

identity-providers.yaml
https://server.com/saml2/spassertion_consumer:
  type: SAML
  loginUrl: https://example.com/SAML/SingleSignOnService
  logoutUrl: https://example.com/SAML/SingleLogoutService
  certificateNames: login_endpoint.crt, signature_endpoint.crt
  samlAuthnContexts: urn:oasis:names:tc:SAML:2.0:ac:classes:Password

Update the config.yaml File

The Entity IDs that you created for your VERA Login and VERA Signatures Endpoints need to be registered with VERA Web Portal. To do this, update the config.yaml file in the VERA Web Portal Data Directory. Update the following lines:

YAML KeyDescription / Default Value
samlEntityId

The Entity ID for the main VERA Login Endpoint that you created in your IdP.

Default: TX3VERA

samlSignaturesEntityId

The Entity ID created for the VERA Signatures Endpoint.

Default: TX3VERASignatures

Restart the Server

Restart the server by running the following command at the command prompt.

Restart Command
docker-compose down
docker-compose up -d

(Optional) Add IdP Users to VERA

Now that the IdP has been registered with VERA, you can import users that will use the IdP for login and signatures. Be sure to use the SAML IdP Provider ID from above as the IdP name in the import file.

(Optional) Disable IdP-Initiated Authentication

In order to prevent user confusion, your IdP should be configured to hide the login buttons for VERA. Below are instructions for Okta and Azure:

Disable IdP-Initiated Authentication in Okta

  1. In both the VERA and VERA-Signature endpoint configurations, check the boxes to no display the icon to users:

Disable IdP-Initiated Authentication in Azure

  1. Under Enterprise Applications, in both the VERA and VERA-Signatures endpoints set the display to users setting to No:

     

Table of Contents