Ganymede OIDC Integration

This document explains how to implement Monosign with Ganymede, the open-source platform to archive Twitch live streams and videos. It covers Single Sign-On with OpenID Connect (OIDC), which is built into Ganymede. Ganymede discovers the Monosign addresses from the OIDC discovery document, so the OIDC/OpenID access key of Monosign is used. Before you continue, it is better to start with the Ganymede SSO - OpenID Connect documentation.

This configuration is done with Ganymede 4.21.0 running on Docker Compose (image ghcr.io/zibbp/ganymede:4.21.0 and postgres:14). If your Ganymede version or deployment type is different, please check the Ganymede documentation.

Ganymede supports OpenID Connect only. SAML is not available in Ganymede.

Monofor has no responsibility to do Ganymede configurations. If you need support please contact the Ganymede community or your Ganymede support provider.

📑 Instructions

This documentation contains 5 main steps for integration.

Creating an application on Monosign
Configuring the OIDC/OpenID settings on Monosign
Assign a user to the Ganymede application
Configuration Single Sign-On for Ganymede
Sign In Test

1- Creating an Application on Monosign

Create your application on Monosign first. Open the Applications page from the left menu and click Add New.

Applications page in Monosign (1: Applications menu, 2: Add New)

Ganymede is not in the application catalog, so click Create from scratch.

Creating a new application from scratch (1: Create from scratch)

Fill in the application details on the Application tab and click Next.

New Application - Application tab (1: Name, 2: Logo, 3: Next)

Property	Value	Description
Name	`Ganymede`	Name of the application shown to users on the Monosign portal and on the Monosign sign-in page.
Type	`Web`	Ganymede is accessed through a web browser. Options: Web, Mobile, Desktop, API.
Url	Optional	Leave empty or enter the Ganymede address (for example `https://ganymede.example.com`).
Logo	Optional	Browse and upload a logo; it is also shown on the Monosign sign-in page.
Users can see this application on their list	`Enabled`	Displays the application on the user portal.

On the Access tab define who can reach the application and click Create Application.

New Application - Access tab (1: Profile Access Type, 2: Create Application)

Property	Value	Description
User Access Type	`System Default`	Defines which users can access this application. Options: Only Assigned Users, All Users, System Default.
User Group Access Type	`System Default`	Defines the application’s user group access.
Source Using Type	`System Default`	Defines which user sources the application can use.
Profile Access Type	`All`	Defines which user profile attributes are available to the application (Options: Restricted, All).

After the application is created, click Keys and add a new Access Key for OIDC/OpenID access.

Keys tab of the Ganymede application (1: Keys, 2: Add New Access Key)

Select OIDC/OpenID as the key type and click Create. Monosign generates the Client Id and Client Secret automatically.

Creating the OIDC/OpenID Access Key (1: Type OIDC/OpenID, 2: Create)

Property	Value	Options
Type	`OIDC/OpenID`	Rest API, OAuth 2.0, JWT, OIDC/OpenID, SAML, RADIUS, Access Gateway, LDAP, AuthN/Z Server
Client Id / Client Secret	Generated automatically	Use the eye icon next to the secret to reveal it. Both values are required in step 4.
Session	`System Default`	System Default, On-demand, Permanent
State	`Enabled`	Enabled, Disabled
Never Expires	`Yes`	Turn off to define a specific expiration date for the key.

Configuration details for the Ganymede application are provided as follows:

Monosign value	Example	Used in Ganymede as
Client Id	`<client-id>`	`OAUTH_CLIENT_ID`
Client Secret	`<client-secret>`	`OAUTH_CLIENT_SECRET`
Configuration Url (issuer)	`https://<monosign-host>/.well-known/openid-configuration`	`OAUTH_PROVIDER_URL` is the issuer address `https://<monosign-host>/`. Ganymede adds `.well-known/openid-configuration` itself and reads the Auth, Token and JWKS addresses from it.

2- Configuring the OIDC/OpenID Settings on Monosign

Open the key with the Configure button, go to OIDC/OpenID Settings and add the callback address of Ganymede to Allowed Redirect URIs.

OIDC/OpenID Settings - Allowed Redirect URIs

Property	Value	Description
Allowed Redirect URIs	`https://ganymede.example.com/api/v1/auth/oauth/callback`	The address where Monosign sends the user back after sign-in. It is the callback address of the Ganymede API, so it must be exactly the same as `OAUTH_REDIRECT_URL` in step 4.
Scope	Empty	Ganymede sends the scope itself: `openid profile groups`.
Use ‘state’ parameter as ‘nonce’	`Disabled` (default)	No change is required for Ganymede. It sends its own `state` and `nonce` values.
Token lifetimes, CORS, Initiate Login URI	Empty	Default values are used.

Open the Claim Mapping tab, add the preferred_username claim and click Update to save.

OIDC/OpenID Settings - Claim Mapping (1: OIDC/OpenID Settings, 2: Claim Mapping, 3: preferred_username, 4: Update)

Claim Name	Value	Description
preferred_username	`{{UserName}}`	User name of the Ganymede account. It is required: Ganymede reads it from the ID token and rejects the sign-in without it.

Click Update after adding the claim. If the claim is added but not saved, Ganymede answers with preferred_username required, ensure your idP is returning this claim. The claim mapping of Monosign is also written into the ID token that Ganymede reads.

3- Assign a User to the Ganymede Application

Please follow the below instructions on how to assign a user to the Ganymede application. Open the application, click the Assignments tab and click Assign a User.

Assignments tab of the Ganymede application (1: Assignments, 2: Assign a User)

Search and select the users who can sign in to Ganymede, check the Expiration Date and click Save. You can select more than one user.

Property	Value	Description
User(s)	Selected users	Users who can sign in to Ganymede with Monosign.
Expiration Date	Default one year	The assignment expires on this date.
Is Active	`Yes`	Enables or disables the assignment.

4- Configuration Single Sign-On for Ganymede

As we mentioned at the start, please check out the Ganymede documentation first. Ganymede is configured with environment variables; there is no single sign-on screen in the Ganymede settings. In the Docker Compose deployment add the following variables to the environment file of the ganymede service and replace the placeholder values.

Bash

OAUTH_ENABLED=true
OAUTH_PROVIDER_URL=https://<monosign-host>/
OAUTH_CLIENT_ID=<client-id>
OAUTH_CLIENT_SECRET=<client-secret>
OAUTH_REDIRECT_URL=https://ganymede.example.com/api/v1/auth/oauth/callback
SHOW_SSO_LOGIN_BUTTON=true
FORCE_SSO_AUTH=false

Variable	Value	Description
OAUTH_ENABLED	`true`	Enables the OpenID Connect login. The other OAuth variables must be set.
OAUTH_PROVIDER_URL	`https://<monosign-host>/`	Issuer address of Monosign. It must be exactly the `issuer` value of the discovery document, including the trailing slash.
OAUTH_CLIENT_ID / OAUTH_CLIENT_SECRET	Client Id / Client Secret	Copied from the Monosign OIDC/OpenID Access Key Details created in the first step.
OAUTH_REDIRECT_URL	`https://ganymede.example.com/api/v1/auth/oauth/callback`	Callback address of the Ganymede API; the same as the Allowed Redirect URI in Monosign.
SHOW_SSO_LOGIN_BUTTON	`true`	Shows the “Single Sign-On (SSO)” button on the Ganymede login page.
FORCE_SSO_AUTH	`false`	Keeps the local user name and password login. Set to `true` to send every user directly to Monosign.

The environment file contains the client secret. Restrict its permissions (for example chmod 600) and do not store it in a shared repository.

The scope is fixed in Ganymede as openid profile groups. Ganymede creates a user with the role user on the first sign-in. If your identity provider sends a groups claim, the group names ganymede-admin, ganymede-editor, ganymede-archiver and ganymede-user set the role of the user. Monosign does not send a group claim by default, so the role of a user is changed by an administrator in Ganymede (Admin → Users).

Recreate the Ganymede container so that the new variables are loaded:

Bash

cd /opt/ganymede
docker compose up -d --force-recreate ganymede

Check that the sign-in starts at Monosign. The Location header must be the Monosign authorization address with redirect_uri=…/api/v1/auth/oauth/callback, scope=openid+profile+groups, state and nonce:

Bash

curl -s -o /dev/null -D - http://localhost:4800/api/v1/auth/oauth/login | grep -i ^location

Ganymede needs a Twitch application (TWITCH_CLIENT_ID and TWITCH_CLIENT_SECRET) only to archive from Twitch. If you leave both variables empty, Ganymede starts without Twitch and the sign-in works. A wrong value stops the Ganymede services at the start; leave the variables empty or enter the real values of your Twitch application.

Now try to log in to Ganymede using Monosign SSO.

Open a new browser window (or a private window) and type the Ganymede address, for example https://ganymede.example.com.

Click Login and then Single Sign-On (SSO) on the Ganymede login page. The local credentials form stays on the page for the local administrator.

Ganymede login page with the “Single Sign-On (SSO)” button

Ganymede redirects the browser to the Monosign sign-in page of the Ganymede application. You can log in passwordless with your QR code (Monofor Identity), with a Passkey or with your user name and password (Sign in with Password).

Monosign sign-in page of the Ganymede application

After the sign-in Monosign redirects the browser back to Ganymede. Ganymede creates the account of the user on the first sign-in and logs the user in. The user name and the role are shown on the profile page.

User logged in to Ganymede through Monosign SSO (user name and Role: user)

Troubleshooting

Symptom	Cause	Solution
`{"success":false,…"message":"preferred_username required, ensure your idP is returning this claim"}` on `/api/v1/auth/oauth/callback`	The ID token has no `preferred_username` claim.	Add `preferred_username = {{UserName}}` in the Claim Mapping tab and click Update (step 2). Try again in a new browser window.
The “Single Sign-On (SSO)” button is not shown	`SHOW_SSO_LOGIN_BUTTON` is not `true`, or the container was not recreated.	Set the variable and run `docker compose up -d --force-recreate ganymede`.
Monosign shows a redirect URI error	The redirect URI that Ganymede sends does not exactly match the Allowed Redirect URIs.	Add `https://ganymede.example.com/api/v1/auth/oauth/callback` in Monosign and use the same value in `OAUTH_REDIRECT_URL`.
Ganymede cannot reach the provider, or the issuer does not match, when it starts	`OAUTH_PROVIDER_URL` is not exactly the issuer of the discovery document (for example the trailing slash is missing).	Use the `issuer` value of `https://<monosign-host>/.well-known/openid-configuration` exactly as it is.
A user cannot sign in	The user is not assigned to the application.	Assign the user in step 3.
A new user cannot manage Ganymede	New users get the user role.	Change the role in Admin → Users with an administrator account (the local administrator stays available because `FORCE_SSO_AUTH` is `false`), or send a `ganymede-<role>` group claim.
The Ganymede container restarts again and again; the log shows `Error authenticating to Twitch`	The Twitch variables contain a wrong value.	Leave `TWITCH_CLIENT_ID` and `TWITCH_CLIENT_SECRET` empty, or enter the real values of your Twitch application.
SAML sign-in is required	Ganymede supports OpenID Connect only.	Use the OIDC integration in this document.

After completing the configuration on Ganymede and Monosign, it is better to test in a new private browser window if the OIDC SSO doesn’t work, because old session cookies of the Ganymede address may cause errors.

📑 Instructions

1- Creating an Application on Monosign

2- Configuring the OIDC/OpenID Settings on Monosign

3- Assign a User to the Ganymede Application

4- Configuration Single Sign-On for Ganymede

5- Sign In Test

Troubleshooting