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 Single Sign-On profile.

SAML Single Sign-On 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

IdP	Identity Provider (for example, Okta)	Third-party system that pre-authenticates SAML users.
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 (for example, Universal Controller)	Receives and accepts authentications via SAML Single Sign-On.
SSO	Single Sign-On	Method of authentication.

Administrator Account

A list of administrator accounts and local account 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, Single Sign-On 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 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.

It will be in the form https://<FQDN>:<PORT>/service/auth/sso/saml/callback, where 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:

Sign in to your Okta tenant as an administrator.
In the Admin Console, navigate to Applications > Applications.
Click Create App Integration
In the Create a new app integration dialog, choose SAML 2.0 and click Next..

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

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

Set the Audience URI to stb-udmg
Select EmailAddress for Name ID format
Select Email for Application username
Keep the other default setting and click Next.

Review the configuration for Sign On Settings

Follow the View SAML setup instructions link.

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

User preparation in Okta

Create a user with an email address demo@std-udmg.com
Assign the stb-udmg application to this user:

User preparation in UDMG

For the SSO integration, the users must aleady 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.

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

The user in credential section must exist on UDMG Server and have "user write" permission.
Add a file parameter with a filename, for example udmg-sso-okta.json
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"
 }

Set the entityIssuer to the value that was set for Audience URI: stb-udmg
Set the ssoURL parameter to the SAML application URL.
Set the ca parameter to the path of the downloaded X.509 Certificate, see above.
Set the redirectURI parameter to Single Sign on URL value
Restart the UDMG Auth Proxy.
The saml provider is now available for the sso service on UDMG Admin UI login page

Go to the Admin UI and select the SAML Provider.