Keycloak Authentication¶

If your HCL Connections signs in through Keycloak, Huddo and Huddo Boards can get their tokens from the same Keycloak realm instead of the Connections OAuth provider.

Huddo still validates each token against Connections, at /connections/opensocial/oauth/rest/people/@me/@self. Connections must therefore already accept access tokens from this realm, which it does when it signs in through Keycloak.

Installing alongside Huddo Boards

With sharedServices.deploy: false, Huddo uses the user service of your Boards release. Set the values below on the Boards release, and use the Boards URL in the redirect and logout URLs. See Adding Huddo to an existing Boards install.

Create the Keycloak client¶

In the realm that Connections signs in with, create an OpenID Connect client for Huddo:

Setting	Value
Client authentication	On (a confidential client, with a client secret)
Standard flow	On
Valid redirect URIs	`https://[HUDDO_URL]/auth/connections/callback`
Client scopes	`email`, `profile` and `offline_access`
Backchannel logout URL	Optional. `https://[HUDDO_URL]/auth/connections/backchannel-logout`

Where [HUDDO_URL] is your Huddo URL including the /huddo prefix, e.g. connections.example.com/huddo. For Huddo Boards, use [BOARDS_URL], e.g. connections.example.com/boards.

The client must issue access tokens with full access to the Connections API.

Huddo sends PKCE with every login, so a client that requires PKCE works too.

Configuration¶

Set these in your config file:

Key	Description
`user.env.CONNECTIONS_CLIENT_ID`	The Keycloak client ID
`user.env.CONNECTIONS_CLIENT_SECRET`	The Keycloak client secret
`user.env.CONNECTIONS_URL`	HCL Connections URL, e.g. `https://connections.example.com`
`user.env.CONNECTIONS_KEYCLOAK_URL`	Keycloak URL, e.g. `https://login.example.com`
`user.env.CONNECTIONS_KEYCLOAK_REALM`	Keycloak realm
`user.env.CONNECTIONS_KEYCLOAK_PATH`	Optional. Path to the realms. Default `/auth/realms`. Set to `/realms` if your Keycloak serves realms without the `/auth` prefix, the default in current Keycloak releases
`user.env.CONNECTIONS_OAUTH_SCOPE`	Optional. Scopes requested at login. Default `offline_access email profile`

user:
  env:
    CONNECTIONS_URL: https://connections.example.com
    CONNECTIONS_CLIENT_ID: huddo
    CONNECTIONS_CLIENT_SECRET: '[CLIENT_SECRET]'
    CONNECTIONS_KEYCLOAK_URL: https://login.example.com
    CONNECTIONS_KEYCLOAK_REALM: connections
    CONNECTIONS_KEYCLOAK_PATH: /realms

The URL, path and realm must match the token issuer

Huddo checks each login against the issuer CONNECTIONS_KEYCLOAK_URL + CONNECTIONS_KEYCLOAK_PATH + / + CONNECTIONS_KEYCLOAK_REALM. This must match the issuer in the realm's /.well-known/openid-configuration exactly. If Keycloak has a different frontend hostname, use that hostname, or login fails.

Other OpenID Connect providers¶

To use another provider that Connections trusts, set its endpoints directly instead of the Keycloak values:

Key	Description
`user.env.CONNECTIONS_OAUTH_AUTHORIZE_URL`	The provider's authorization URL
`user.env.CONNECTIONS_OAUTH_TOKEN_URL`	The provider's token URL