Setup a SAML 2.0 SSO Identity Provider

Owned by HB Farris
Last updated: Feb 19, 2024 by John Berek
4 min read

IdP-Initiated Authentication Now Supported!

The Vera Web Portal 2024.1 and later now supports authenticating directly from a configured Identity Provider. Users can click the button from their Identity Provider homepages and will be logged into Vera if they have a configured Vera account.

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 File

Description / Example

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.

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)

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.

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 name: Azure

Element (line #)

YAML Key

Description

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.

Name (6)

name

A user friendly name for the 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

Change the Authentication Context for the Signature SAML Requests

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

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

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.

Restart Command

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