Overview

YOUnite supports two authentication mechanisms: SAML and Open ID Connect. This guide shows how to set up Keycloak with Open ID Connect to work with Open MDM. This document does not detail how to install Keycloak itself, just how to configure it to work with YOUnite.

...

Descriptions of each property are below in the comments:

API Configuration

#
# Open ID Connection information. Only required if this authentication method is going to be used.
#
# openmdm.api.url = URL to the public endpoint for the Open MDM API. Required for a redirect after authentication is completed.
# oidc.discovery.document.url = the URL of the discovery document with Open ID Configuration
# oidc.host.external = external protocol, host name and port override (ie https://openmdm.dev.ccctechcenter.org:8443).
#                      required when running in docker and the internal and external host and/or port are not the same.
#                      when this configuration is required, the discovery document url should contain the internal URL
#                      and this value should specify the external hostname and port.
# oidc.client.id = Client ID
# oidc.client.secret = Client Secret
# oidc.scope = scope to pass to the auth server. thismust typicallyinclude contains "openid", and typically the sso attribute we need, ie "openid email".
# oidc.sso.attribute = attribute to map to SSO ID in the system, for example email. this should be specified in the scope above.
# oidc.issuer = expected value for "issuer" of the Open ID token. optional, but if specified will be validated.
# oidc.successful.login.url = URL to send the user to when they successfully authenticate (such as the UI dashboard)

#
# dev configuration for local keycloak configuration
# - to avoid certificate errors, access the discovery document on the insecure port
# - however, we still need to set the external host to the secure port as web browsers won't allow a redirect from a secure to non-secure website
#
openmdm.api.url=https://openmdm.dev.ccctechcenter.org/api
oidc.discovery.document.url=http://localhost:8080openmdm.dev.ccctechcenter.org:8800/auth/realms/openmdm/.well-known/openid-configuration
oidc.host.external=https://openmdm.dev.ccctechcenter.org:8443
oidc.client.id=openmdm-client
oidc.client.secret=d50e1d6cd174ca69-ccecff0e-40e841c6-84bd-b6b1df0d2d17
oidc.scope=openid email
oidc.sso.attribute=email
oidc.issuer=http://localhost:8080/auth/realms/openmdm8b5d-c76376363fe8
oidc.successful.login.url=https://openmdm.dev.ccctechcenter.org/dashboard
oidc.scope=openid email
oidc.sso.attribute=email

UI Configuration

The SSO URL will need to be updated on the UI to direct to the new authentication which is /api/openid/login

For example, in the docker-compose file for youniteui the updated parameter would look like:

...

UI needs to be configured with a SSO_TYPE of "O", ie:

- SSO_TYPE=O # S = Shibboleth, O = Open ID Connect

The SSO_APP_URL value does not need to be set for Open ID Connect, only for Shibboleth at this time.

Notes

• Open ID Connect authentication is only used to determine the SSO ID of the user in question (this comes from the ID token). The OAuth token returned by the Open ID Connect service is not used. Instead, a different OAuth token is issued from the internal Oauth2 server (which is part of the API). This token is set as a cookie in the user's browser and used to authenticate requests. An internal OAuth server is used to have more specific control over permissions.