SSO OpenID Connect

Ganymede OAuth should work with any provider.

Flow

Enabling OAuth does not disable "local" authentication. The initial admin account is still created. If you wish to only use SSO then disable registration in the config.json and remove all local user accounts. I recommend still keeping the admin account around to avoid getting locked out.

Tested Providers:

• Authentik (need to select a signing key other than default to use RS256).

General Information:

• JWKS keys are fetched and cached on boot then once every day.
• Only the "profile" scope is requested. Within the profile scope, the "nickname" field is required as that sets the Ganymede username.
• Symmetric signing algorithms are not supported, only asymmetric (RS256).
• Ganymede roles can be applied externally by adding a group to the user within your OAuth provider (see below).

Roles / Groups

Within your OAuth provider groups can be assigned to users that will map to Ganymede roles. The groups are ganymede-admin, ganymede-editor, ganymede-archiver, and ganymede-user. If no group is present during initial OAuth login then it will default to "user".

Enabling SSO / OIDC

1. Enable OAuth in /data/config.json by setting oauth_enabled to true.
2. Edit docker-compose.yml adding / editing the following environment variables.
   1. OAUTH_PROVIDER_URL: URL to OAuth resident provider. Often called "OpenID Configuration Issuer".
   2. OAUTH_CLIENT_ID: OAuth ClientID.
   3. OAUTH_CLIENT_SECRET: OAuth Client Secret.
   4. OAUTH_REDIRECT_URL: URL to callback route, point this to where your Ganymede API is hosted. Ensure to set this in your OAuth provider as well. Examples: http://localhost:4000/api/v1/auth/oauth/callback https://api.ganymede.net/api/v1/auth/oauth/callback
3. Bring the stack up docker-compose up.

Troubleshooting

• oidc: issuer did not match the issuer returned by provider Entered an incorrect URL for OAUTH_PROVIDER_URL. The error should print an expected URL. Most time it's because the url requires or does not require a trailing /.