Versions Compared

Old Version 3

changes.mady.by.user John Berek

Saved on

compared with

New Version Current

changes.mady.by.user John Berek

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Warningtip

IdP-Initiated Authentication

Not

Now 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

!

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

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.

config.yaml file
Code Block
title
languageymlconfig.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 Blocklanguageymltitle
identity-providers.yaml
Code Block
linenumberslanguagetrueyml
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
Info

The Name property is new as of Vera 2024.1. Enter a user friendly, short name for each configured Identity Provider. This name is to help both admins and users to identify the appropriate Identity Provider to login with.

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.

languageymltitle

Expand
titleClick 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:

Code Block

  1. identity-providers.yaml

linenumbers

  1. Code Block
    language

true

  1. yml
    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

title
Note

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
Code Block
languageyml
titleidentity-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.

Restart Command
Code Block
languagebashtitleRestart 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 AnchorDisable IdP-Initiated AuthenticationDisable 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:Image Removed

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:

    Image Removed 

Table of Contents

Table of Contents
maxLevel2