Warning
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

Warning
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 File

Description / 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.

Note
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.

Endpoint	Example Entity ID	Assertion Consumer Service URL	Single Logout URL (optional)
VERA Login Endpoint	TX3VERA	https://your.vera.web.url/saml/AssertionConsumerService	https://your.vera.web.url/saml/SingleLogoutService
VERA Signature Endpoint	TX3VERASignatures	https://your.vera.web.url/saml/SignatureAssertionConsumerService	Not 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.

Code Block

language	yml
title	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:

Code Block

language	yml
title	identity-providers.yaml
linenumbers	true

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 Key	Description
IdP Provider Name (1)	N/A	The 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)	type	The type of connection being used. Currently the only supported type is SAML.
Login URL (3)	loginUrl	The URL where users will be redirected to log into the IdP.
Logout URL (4)	logoutUrl	The URL to redirect to when users log out of VERA. This can be left blank.
Certificate Names (5)	certificateNames	A comma-separated list of certificates that will be used to validate the SAML Response from the IdP.

Expand

title	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

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

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

Code Block

language	yml
title	identity-providers.yaml
linenumbers	true

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 Key	Description
Signatures ID (5)	signaturesId	The SAML Issuer ID from Okta for the Signatures endpoint.
Signatures URL	signaturesUrl	The Okta App Link for the Signatures endpoint.

Change the Authentication Context for the Signature SAML Requests

Note

title	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.

Code Block

language	yml
title	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 Key

Description / 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.

Code Block

language	bash
title	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
Anchor
Disable IdP-Initiated Authentication
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

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

Disable IdP-Initiated Authentication in Azure

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

Image Modified

Table of Contents

Table of Contents

maxLevel	2

Versions Compared

Old Version 2

New Version Current

Key

Prerequisites

Gather SAML IdP Information

Create Endpoints for VERA

Server Setup

Upload the Certificates to VERA Server

Create or update the identity-providers.yaml file

Procedure to set up Okta for SSO with VERA

Change the Authentication Context for the Signature SAML Requests

Update the config.yaml File

Restart the Server

(Optional) Add IdP Users to VERA

(Optional) Disable IdP-Initiated Authentication
Anchor
Disable IdP-Initiated Authentication
Disable IdP-Initiated Authentication

Disable IdP-Initiated Authentication in Okta

Disable IdP-Initiated Authentication in Azure

Page Comparison

Versions Compared

Old Version 2

New Version Current

Key

Prerequisites

Gather SAML IdP Information

Create Endpoints for VERA

Server Setup

Upload the Certificates to VERA Server

Create or update the identity-providers.yaml file

Procedure to set up Okta for SSO with VERA

Change the Authentication Context for the Signature SAML Requests

Update the config.yaml File

Restart the Server

(Optional) Add IdP Users to VERA

(Optional) Disable IdP-Initiated Authentication AnchorDisable IdP-Initiated AuthenticationDisable IdP-Initiated Authentication

Disable IdP-Initiated Authentication in Okta

Disable IdP-Initiated Authentication in Azure

(Optional) Disable IdP-Initiated Authentication
Anchor
Disable IdP-Initiated Authentication
Disable IdP-Initiated Authentication