YOUnite supports OAuth authentication with the Open ID Connect protocol. This guide shows how to set up Keycloak (https://www.keycloak.org/) with Open ID Connect to work with YOUnite’s services. This document does not detail how to install Keycloak itself, just how to configure it to work with YOUnite.

Note
 Keycloak is not the only supported identity provider, any Open ID Connect compliant provider should work.

Workflow Diagram

image

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

image

Configure Clients used by YOUnite and the Notification Service

The YOUnite Server acts as a "Resource Server" and requires a client with the "Standard Flow" enabled so that it can send users to Keycloak for authentication.

See Managing Resource Servers for more information on this flow.

Additionally, a client is required so that the YOUnite Notification Service can communicate with the YOUnite Server. This client acts as a "service account", ie it’s used by a service to authenticate and therefore cannot be presented with a login page.

Creating the Client for the YOUnite Server

Under Clients, select add client and choose openid-connect as the client protocol. You may choose any client ID you choose, in this example we’re calling it younite.

image

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

  1. Access Type = confidential

  2. Standard Flow Enabled = 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

image

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

image

Creating the Client for the Notification Service

Under Clients, select add client and choose openid-connect as the client protocol. The client id MUST be notifications to correspond to the permissions created for this service by default.

If it is desired to use a different client id for notifications, a record in the auth_identity table of YOUnite’s database must be updated. For example: UPDATE auth_identity SET ssoid = '<new client id here>' WHERE ssoid = 'notifications'.

image

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

  1. Access Type = confidential

  2. Service Accounts Enabled = On

  3. Disable all other authentication flows

image

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

image

Configure Users

Next step is to create users. This example creates a user to correspond to the admin user with the email address admin@younite.us

image

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

image

Default YOUnite Users

By default, YOUnite comes configured with two Super User accounts. An "admin" and a "data governance steward". The email addresses (or sso ids) of these users is admin@younite.us and dgs@younite.us. Therefore, for YOUnite to work out of the box, two accounts need to be created in Keycloak with these email addresses.

The email addresses of these two super users can be updated in the YOUnite database like so:

UPDATE auth_identity SET ssoid = '<new admin sso id>' WHERE ssoid = 'admin@younite.us';
UPDATE auth_identity SET ssoid = '<new data governancce steward sso id>' WHERE ssoid = 'dgs@younite.us';

Keycloak Configuration Variables

A Keycloak service is configured for a demo/eval deployment using the Docker Compose stack so, no extra configuration is required to be able to run Keycloak.

This implementation can be used as a starting point to build other SSO and OAuth services for YOUnite. To gain access to the YOUnite Keycloak repository contact your YOUnite Systems Integrator.

Its highly recommended that usernames, passwords and secrets are changed. Change the following if these or other changes are required.

Property Description Default Example

KEYCLOAK_USER

Realm master username

None

admin

KEYCLOAK_PASSWORD

Realm master password

None

admin

REDIRECT_URIS

Whitelist of redirect URIs (e.g. API, UI and Notification services)

None

"http://local.younite.org/*", "http://local.younite.org:8080/*", "http://local.younite.org:5601/*"

YOUNITE_CLIENT_SECRET

The client secret to assign to the younite user. Used by the YOUnite API Service to authenticate with Keycloak.

None

dcc766a6-de22-452e-9961-15db0cb4a5b6

NOTIFICATIONS_CLIENT_SECRET

The client secret to assign to the notifications user. Used by the Notifications Service to authenticate with Keycloak.

None

8da84bfb-0956-482b-8703-3f7210480aed

TOKEN_LIFESPAN_SECONDS

Token lifespan in seconds.

24 hours (86,400 seconds)

86400

DB_VENDOR

The database vendor used. The YOUnite implementation uses h2. This value should not be changed.

None

h2

Configuring YOUnite Services for Keycloak

Now that Keycloak is configured, we need to set up the following services with information about the Open ID Connect server:

  • YOUnite API Service

  • Notification Service

  • UI Server

  • Data Virtualization Service

  • Elastic Service

  • Kibana Service

This configuration is done either in application.properties or via environment variables. The example below are values in environment variables:

Descriptions of each property are below in the comments:

YOUnite API Service Configuration

Open ID Connection information, required for authentication.

Property Description Default Example

YOUNITE_API_URL

URL to the public endpoint for the YOUnite API. Required for a redirect after authentication is completed.

None

http://local.younite.org:8080/api

OIDC_DISCOVERY_DOCUMENT_URL

The URL of the discovery document with Open ID Configuration.

None

http://local.younite.org:8800/auth/realms/younite/.well-known/openid-configuration

OIDC_CLIENT_ID

Client ID. If using the default keycloak server, the value will be younite.

None

younite

OIDC_CLIENT_SECRET

Client secret. If using the default keycloak server, the value will be the same as YOUNITE_CLIENT_SECRET.

None

8da84bfb-0956-482b-8703-3f7210480aed

OIDC_SCOPE

Scope to pass to the auth server. must include "openid", and typically the sso attribute we need, ie "openid email".

None

openid email

OIDC_SSO_ATTRIBUTE

Attribute(s) to map to SSO ID in the system. the default value is "email,clientId". the inclusion of clientId ensures that a client (such as the Notifications Service) can be authenticated as it may not have an email.

None

email,clientId

OIDC_SUCCESSFUL_LOGIN_URL

URL to send the user to when they successfully authenticate (such as the UI dashboard)

None

http://local.younite.org/dashboard

Notification Service Configuration

Property Description Default Example

OIDC_ISSUER

URI to the "issuer" of responses to OpenID requests. can be found in the discovery document as "issuer".

None

http://local.younite.org:8800/auth/realms/younite

SSO_ATTRIBUTE

Identify the field in the claims that identifies a user’s SSO ID (usually email).

None

email

NOTIFICATION_SERVICE_CLIENT_ID

Client ID. If using the default keycloak server, the value will be notifications.

None

notifications

NOTIFICATION_SERVICE_CLIENT_SECRET

Client Secret. If using the default keycloak server, the value will be the same as NOTIFICTATIONS_CLIENT_SECRET.

None

8da84bfb-0956-482b-8703-3f7210480aed

UI Server Configuration

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

- SSO_TYPE=O # O = Open ID Connect, S = SAML (not yet supported)
Note
 SAML is not currently supported but may be added in a future release
Property Description Default Example

SSO_TYPE

Set to O for the default single-sign-on service Open ID. Contact your system integrator for other options.

None

O

Data Virtualization Service Configuration

Property Description Default Example

OIDC_ISSUER

oic.issuer

Issuer URI of the Open ID Connect compliant authentication server. Normally the same as used by the YOUnite server.

http://localhost:8800/auth/realms/younite

OIDC_SSO_ATTRIBUTE

oidc.sso.attribute

Attribute that maps to the username in YOUnite, for example, email address.

email

Elastic Service Configuration

Property Description Default Example

OPENID_URL

URL to the Open ID server to be used by Elastic.

None

http://local.younite.org:8800/auth/realms/younite/.well-known/openid-configuration

Kibana Service Configuration

Property Description Default Example

OPENID_URL

URL to the Open ID server

None

http://local.younite.org:8800/auth/realms/younite/.well-known/openid-configuration

OPENID_CLIENT_ID

Typically, the same value used in API Service environment variable OIDC_CLIENT_ID.

None

younite

OPENID_CLIENT_SECRET

Typically, the same value used in API Service environment variable OIDC_CLIENT_SECRET.

None

8da84bfb-0956-482b-8703-3f7210480aed

OPENID_REDIRECT_URL

URL to the Kibana service.

None

http://local.younite.org:5601