SSO SAML Settings

Owned by Stonebranch
May 20, 2024
4 min read

Overview

Note

The information provided on this page assumes you have a working knowledge of SAML Single Sign-On.


UDMG Authentication Proxy enables Web Browser Single Sign-On (SSO) on the UDMG Admin UI through Security Assertion Markup Language 2.0 (SAML 2.0).

SAML 2.0 is an XML-based protocol for exchanging security information between a SAML Identity Provider and a SAML Service Provider.

As a SAML Service Provider, UDMG Authentication Proxy accepts authentication assertions from a configured SAML Identity Provider compliant with the SAML 2.0 Web Browser SSO profile.

SAML SSO eliminates the need for application-specific passwords. UDMG Admin UI issues an authentication request to the configured Identity Provider, through the web browser, for any unauthenticated user accessing the UDMG Admin UI web application through the selected service and provider on the login page.

UDMG Authentication Proxy uses SAML Single Sign-On for authentication and User Provisioning. All user and group authorization must be configured within UDMG through Permission assignment.


Terminology

AcronymFull NameDescription

IdP

Identity Provider 

Third-party system that pre-authenticates SAML users. For example, Okta.

SAML

Security Assertion Markup Language

SAML is an XML-based protocol for exchanging security information between a SAML Identity Provider and a SAML Service Provider.

SP

Service Provider 

Receives and accepts authentications via SAML Single Sign-On. For example, Universal Controller.

SSO

Single Sign-On

Method of authentication.

Administrator Account

A list of administrator accounts and local accounts with fewer privileges can be defined on the UDMG Server database. They can login with the Local authentication provider that is enabled for any service; therefore, these accounts will always be accessible for cases where, for example, SSO settings are incorrectly configured, or the Identity Provider is inaccessible.

Example Configuration:

Assuming the following service configuration on the UDMG Authentication Proxy, the below sections describe how to add the SAML Provider as an option for user authentication.

[service.demo]
protocol = "http"
policy = "failover"

[[service.demo.targets]]
hostname = "udmg.demo"
port = 18080

Example with Okta App Integration

Before you begin


The Single sign on URL (SAML Post URL location, or callback URL) must be determined.

The form is https://<FQDN>:<PORT>/service/auth/sso/saml/callback, FQDN and PORT are the name and port for the host where the UDMG Authentication Proxy and NGINX server are installed.

For example, https://udmg.demo/service/auth/sso/saml/callback.

SAML Integration on Okta

To configure the SAML integration on Okta, follow these steps:

Step 1

Sign in to your Okta tenant as an administrator.

Step 2

In the Admin Console, navigate to Applications > Applications.

Step 3Click Create App Integration
Step 4

In the Create a new app integration dialog, choose SAML 2.0 and click Next.

Step 5

Enter an App name such as stb-udmg, optionally add a logo and click Next:

Step 6

In Configure SAML step, in the SAML Settings section, enter the value for Single sign on URL.

Step 7

Set the Audience URI to stb-udmg.

Step 8

Select EmailAddress for Name ID format.

Step 9

Select Email for Application username.

Step 10

Keep the other default setting and click Next.

Step 11

Review the configuration for Sign On settings.

Step 12

Follow the View SAML setup instructions link.

Step 13

From this view, keep the Identity Provider Single Sign-On URL for later and download the X.509 Certificate.



User Preparation in Okta

Step 1

Create a user with an email address demo@std-udmg.com.

Step 2

Assign the stb-udmg application to this user:


User Preparation in UDMG

For the SSO integration, the users must already exist in UDMG with the primary email that is used on the SSO Identity Provider to identify these users.

For example, the "demo" user:


SAML Integration on UDMG

To configure the SAML integration on UDMG Authentication Proxy, follow these steps.

Step 1

Create a credential and a auth.saml Provider sections in the configuration file for a service, for example here for the service SSO:

[service.demo]
protocol = "http"
policy = "failover"

[service.demo.credential]
username = "user"
password = "password"

[service.demo.auth.saml]
file = "udmg-sso-okta.json"

[[service.demo.targets]]
hostname = "udmg.demo"
port = 18080

Step 2

The user in credential section must exist on UDMG Server and have User Write permission.

Step 3Add a file parameter with a filename, for example udmg-sso-okta.json
Step 4

Create this configuration file in the same location as the UDMG Authentication Proxy configuration file.

{
    "entityIssuer": "stb-udmg",
    "ssoURL": "https://dev-35063850.okta.com/app/dev-35063850_stbudmg_1/exk9k3mscnz06Wx2g5d7/sso/saml",
    "ca": "/config/udmg-okta-sso.cert",
    "redirectURI": "https://udmg.demo/service/auth/sso/saml/callback",
    "insecureSkipSignatureValidation": false,
    "usernameAttr": "name",
    "emailAttr": "name",
    "groupsAttr": "groups"
 }
Step 5Set the entityIssuer to the value that was set for Audience URI: stb-udmg
Step 6Set the ssoURL parameter to the SAML application URL. 
Step 7Set the ca parameter to the path of the downloaded X.509 Certificate, see above.
Step 8Set the redirectURI parameter to Single Sign on URL value.
Step 9Restart the UDMG Auth Proxy.
Step 10The SAML Provider is now available for the SSO service on UDMG Admin UI login page.
Step 11

Go to the Admin UI and select the SAML Provider.

Step 12

Click the arrow button to open the Okta login page.

Step 13

After signing in, the web browser is redirected to the UDMG Admin UI with the authenticated user.

References:

Okta documentation:

https://help.okta.com/oag/en-us/Content/Topics/Access-Gateway/add-app-saml-pass-thru-add-okta.htm