Overview

UDMG Authentication Proxy enables the authentication of users to the UDMG Server REST API with a token mechanism to maintain the authenticated connection for a period of time. Its main purpose is to allow a user session to happen on the UDMG Admin UI which only relies on the REST API. By extension, it provides integration with other authentication mechanisms like LDAP and SSO and can be used by other UDMG Server REST clients to access the UDMG API with these additional Identity Providers.

The Authentication Proxy concept is split between service and provider entities.

A service defines the target UDMG Server and the supported authentication mechanism or provider.
A provider defines the type and the actual configuration for the related identity provider, for example the address of the LDAP server and the needed entity mapping.

The combination between service and provider is flexible and allows grouping per target environment or per desired authentication type.

For example, the same UDMG Authentication Proxy can be setup to give access to:

Preproduction with LDAP authentication
Quality Assurance with SSO SAML authentication
Development with Local authentication

The provider types are the following:

Name	Description
`local`	Standard UDMG Server authentication, usernames and passwords are stored in the UDMG Server database. This includes the additional TOTP login method.
`ldap`	LDAP or LDAPS Server.
`google`	Google OAuth2 Provider.
`oauth`	Standard OAuth2 Provider.
`oidc`	Standard OpenID Provider.
`saml`	SAML 2.0 Provider.

By default, the local authentication is always enabled for all services.

Local Authentication

Local authentication is the standard authentication with usernames and passwords that are stored in the UDMG Server database. It is available for UDMG Admin UI, the REST API interface and the UDMG Client command line tool.

Note

When the UDMG Server is first started, a single user named 'admin' is created with the password 'admin_password'. The user has full administrative permissions and should only be used to create other users to administer the UDMG Server.

It is strongly recommended that you create one or more users immediately and then change the 'admin' account password.

In case you have lost or forgotten the 'admin' password, please refer to Recover/reset administrator access rights.

Single Sign-On Settings

This covers the following provider types: google, oauth, oidc, saml.

Before you begin

In order to provide an integration via an SSO Provider, it is required that the UDMG users have an email value.

The user's email value is the identifier that is shared between UDMG and the Identity Provider.

Configuration

Please refer to the pages:

LDAP Settings

UDMG Admin UI login page with the LDAP provider.

The LDAP provider first initializes a connection to the LDAP directory using either anonymous or explicit binding. It then tries to search for the given username and bind as that user to verify their password. Searches that return multiple entries are considered ambiguous and will return an error.

Example of a service section in UDMG Authentication Proxy for LDAP authentication.

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

[service.ldap.credential]
username = "ldap_sync"
password = "ldap_password"

[[service.ldap.targets]]
hostname = "localhost"
port = 18080

[service.ldap.auth.ldap]
file = "udmg-ldap-config.json"

Be careful that in this example for the section name "service.ldap.auth.ldap", the first "ldap" is simply the custom name for the service that is shown on the login page, the second "ldap" is the type of the login provider as listed on the above table.

The details of the LDAP server are defined in the JSON file.

User Provisioning

In case of successful authentication on the LDAP, the UDMG user is created with default Read permission in the internal UDMG Server database, if it does not exist. Otherwise, the user credentials are updated in the UDMG Server database to allow for authentication on the REST and CLI interfaces.

The LDAP replication requires access with a user having the permission for creating and updating users. For example to create the 'ldap_sync' user with the command line interface:

udmg-client user add -u ldap_sync -p ldap_password -r 'U=rw'

This user credentials are set in the section [service.ldap.credential] of the UDMG Authentication Proxy configuration file.

Example of log message for a succesful LDAP login and user synchronization:

level=info TS=2024-04-10T14:39:03.127900325Z Internal="performing ldap search %s %s %s[ou=users,dc=stonebranch,dc=com sub (&(objectClass=*)(uid=john))]"
level=info TS=2024-04-10T14:39:03.128621001Z Internal="username %q mapped to entry %s[user cn=john,ou=users,ou=users,dc=stonebranch,dc=com]"
level=error TS=2024-04-10T14:39:04.98115277Z Authentication=Provider Sync=Created
level=info TS=2024-04-10T14:39:04.981406859Z Authentication=Request Session=Success
{"time":"2024-04-10T11:39:04.981480728-03:00","id":"","remote_ip":"127.0.0.1","host":"localhost:5000","method":"POST","uri":"/auth/ldap","user_agent":"vscode-restclient","status":200,"error":"","latency":2174162954,"latency_human":"2.174162954s","bytes_in":74,"bytes_out":184}

The default permissions after the user provisioning:

After the initial synchronization and the user creation with default permission, it may be required that an administrator grant more permissions to the user.

Anonymous Binding

Example of provider configuration file udmg-ldap-config.json for anonymous binding on the LDAP Server.

{
  "host": "ldap_hostname:389",
  "insecureNoSSL": true,
  "usernamePrompt": "Email Address",
  "userSearch": {
    "baseDN": "dc=stonebranch,dc=com",
    "filter": "(objectClass=*)",
    "username": "cn",
    "idAttr": "uidNumber",
    "emailAttr": "uidNumber",
    "nameAttr": "cn"
  },
  "groupSearch": {
    "baseDN": "ou=users,dc=stonebranch,dc=com",
    "filter": "(objectClass=groupOfNames)",
    "userMatchers": [
      {
        "userAttr": "DN",
        "groupAttr": "member"
      }
    ],
    "nameAttr": "cn"
  }
}

Explicit Binding

Example of provider configuration file udmg-ldap-config.json for explicit binding on the LDAP server.

Note the addition of the bindDN and bindPW parameters for the LDAP user "proxy" and password"proxy_password".

{
	"host": "ldap_hostname:389",
	"bindDN": "cn=proxy,ou=users,dc=stonebranch,dc=com",
	"bindPW": "proxy_password",
	"insecureNoSSL": true,
	"usernamePrompt": "Email Address",
	"userSearch": {
		"baseDN": "dc=stonebranch,dc=com",
		"filter": "(objectClass=*)",
		"username": "uid",
		"idAttr": "uidNumber",
		"emailAttr": "uidNumber",
		"nameAttr": "cn"
	},
	"groupSearch": {
		"baseDN": "ou=users,dc=stonebranch,dc=com",
		"filter": "(objectClass=groupOfNames)",
		"userMatchers": [{
			"userAttr": "DN",
			"groupAttr": "member"
		}],
		"nameAttr": "cn"
	}
}

SSL/TLS Secured LDAP (LDAPS)

Example of provider configuration file udmg-ldaps-config.json for explicit binding on the LDAPS Server.

Note the startTLS and insecureSkipVerify options to avoid the certificate verification.

{
	"host": "ldap_hostname:636",
	"bindDN": "cn=proxy,ou=users,dc=stonebranch,dc=com",
	"bindPW": "proxy_password",
    "startTLS": false,
	"insecureSkipVerify": true,
	"usernamePrompt": "Email Address",
	"userSearch": {
		"baseDN": "dc=stonebranch,dc=com",
		"filter": "(objectClass=*)",
		"username": "uid",
		"idAttr": "uidNumber",
		"emailAttr": "uidNumber",
		"nameAttr": "cn"
	},
	"groupSearch": {
		"baseDN": "ou=users,dc=stonebranch,dc=com",
		"filter": "(objectClass=groupOfNames)",
		"userMatchers": [{
			"userAttr": "DN",
			"groupAttr": "member"
		}],
		"nameAttr": "cn"
	}
}

Example with the use of the root CA certificate of the LDAPS Server:

{
	"host": "ldap_hostname:636",
    "rootCA": "ca-cert.pem",
	"bindDN": "cn=proxy,ou=users,dc=stonebranch,dc=com",
	"bindPW": "proxy_password",
    "usernamePrompt": "Email Address",
	"userSearch": {
		"baseDN": "dc=stonebranch,dc=com",
		"filter": "(objectClass=*)",
		"username": "uid",
		"idAttr": "uidNumber",
		"emailAttr": "uidNumber",
		"nameAttr": "cn"
	},
	"groupSearch": {
		"baseDN": "ou=users,dc=stonebranch,dc=com",
		"filter": "(objectClass=groupOfNames)",
		"userMatchers": [{
			"userAttr": "DN",
			"groupAttr": "member"
		}],
		"nameAttr": "cn"
	}
}

LDAP provider configuration parameter list

Parameter	Description
`host`	Host and optional port of the LDAP server in the form "host:port". If the port is not supplied, it will be guessed based on "insecureNoSSL", and "startTLS" flags. 389 for insecure or StartTLS connections, 636 otherwise.
`insecureNoSSL`	Following field is required if the LDAP host is not using TLS (port 389). Because this option inherently leaks passwords to anyone on the same network, THIS OPTION MAY BE REMOVED WITHOUT WARNING IN A FUTURE RELEASE.
`insecureSkipVerify`	If a custom certificate isn't provided, this option can be used to turn off TLS certificate checks. As noted, it is insecure and shouldn't be used outside of explorative phases.
`startTLS`	When connecting to the server, connect using the ldap:// protocol then issue a StartTLS command. If unspecified, connections will use the ldaps:// protocol
`rootCA`	Path to a trusted root certificate file.
`clientCert`	Path to a client cert file generated by rootCA.
`clientKey`	Path to a client private key file generated by rootCA.
`rootCAData`	Base64 encoded PEM data containing root CAs.
`bindDN` `bindPW`	The DN and password for an application service account. The connector uses these credentials to search for users and groups. Not required if the LDAP server provides access for anonymous auth. Please note that if the bind password contains a `$`, it has to be saved in an environment variable which should be given as the value to `bindPW`.
`usernamePrompt`	The attribute to display in the provided password prompt. If unset, will display "Username"
`userSearch`	User entry search configuration, maps a username and password entered by a user to a LDAP entry.
`baseDN`	BaseDN to start the search from. It will translate to the query "(&(objectClass=person)(uid=<username>))". For example "cn=users,dc=example,dc=com".
`filter`	Optional filter to apply when searching the directory. For example "(objectClass=person)"
`username`	Attribute to match against the inputted username. This will be translated and combined with the other filter as "(<attr>=<username>)".
`scope`	Can either be: "sub" - search the whole sub tree, default "one" - only search one level
`idAttr`	String representation of the user. Defaults to "uid"
`emailAttr`	Required. Attribute to map to Email.Defaults to "mail"
`nameAttr`	Maps to display name of users. No default value.
`groupSearch`	Group search queries for groups given a user entry.
`baseDN`	BaseDN to start the search from. It will translate to the query "(&(objectClass=group)(member=<user uid>))". For example "cn=groups,dc=example,dc=com"
`scope`	Can either be: "sub" - search the whole sub tree, default "one" - only search one level
`filter`	Optional filter to apply when searching the directory. For example "(objectClass=posixGroup)"
`userMatchers`	Array of the field pairs used to match a user to a group. Each pair adds an additional requirement to the filter that an attribute in the group match the user's attribute value. For example that the "members" attribute of a group matches the "uid" of the user. The exact filter being added is: (userMatchers[n].<groupAttr>=userMatchers[n].<userAttr value>)
`userAttr` `groupAttr`	The two fields are used to match a user to a group. It adds an additional requirement to the filter that an attribute in the group must match the user's attribute value.
`nameAttr`	The attribute of the group that represents its name.

Browser not supported