Implementing SSO - Keycloak and Open ID Connect

Owned by Zeke Rogers (Unlicensed)
Last updated: Feb 08, 2019
4 min read


Overview

YOUnite supports two authentication mechanisms: Shibboleth (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.


Workflow Diagram


Setting Up Keycloak

Configure the Realm

You can use an existing realm or create a new realm in Keycloak. For this example we created a realm called "openmdm".

Configure the Client

Under "Clients", click "add client" and choose "openid-connect" as the client protocol


On the next page, set up your client like so. Make sure to set the following:

  1. Access Type = confidential
  2. Standard Flow Enable = On
  3. Disable all other authentication flows
  4. Valid Redirect URLs. These tell the server where it's allowed to redirect to. The most important is the /api/openid/code endpoint as this is the API endpoint that validates the code sent by Keycloak.
    1. (younite url)
    2. (younite url)/dashboard
    3. (younite url)/api/openid/code

Click save after you've configured these options. Once you hit save, the "Credentials" tab will show up if it was not present before. Click on that tab to retrieve the client secret. You will need this for later.


Configure users

Next step is to create users. This example creates a user to correspond to the "MDM admin" user with the email address mdmadmin@democollege.edu

By default the new user won't have a password, reset it like so:


Configuring YOUnite

Now that Keycloak is configured, we need to set up the YOUnite API with information about the Open ID Connect server. This configuration is done either in application.properties or via environment variables. The example below are values in application-dev.properties:

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. must include "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.successful.login.url = URL to send the user to when they successfully authenticate (such as the UI dashboard)

#
# dev configuration for local keycloak
# - 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://openmdm.dev.ccctechcenter.org:8800/auth/realms/openmdm/.well-known/openid-configuration
oidc.host.external=https://openmdm.dev.ccctechcenter.org:8443
oidc.client.id=openmdm
oidc.client.secret=d174ca69-ff0e-41c6-8b5d-c76376363fe8
oidc.successful.login.url=https://openmdm.dev.ccctechcenter.org/dashboard
oidc.scope=openid email
oidc.sso.attribute=email


UI Configuration

The 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.