Using OpenID Connect

On an instance with OpenID Connect enabled, the login page of Grappa and of the administration interface both include a link to Login with OpenID Connect. This link redirects you to the OpenID provider’s own authentication interface.

After a successful login through the provider, you will be redirected to Grappa. If you already had an account on Grappa, you will be logged in. If you did not have one already, a new account will be created for you.

In case you were already signed-on on the OpenID provider, clicking this button will redirect you to Grappa after a few seconds and log you in immediately.

Password authentication

After authenticating with OpenID Connect, you will no longer be able to update your password, request a password reset, or log in using a password. You will need to log in exclusively using OpenID Connect.

Instance administrators can disconnect a user account from OpenID Connect to turn it back into a regular Grappa account, which restores password authentication.

Setting up OpenID Connect

OIDC support is disabled by default, as it requires additional configuration. To enable OIDC on an instance, system administrators must set OIDC related settings from the provider.

Using Keycloak

  1. Create an OpenID Connect client on the Keycloak instance.

  2. Under Settings  Access settings, configure the following:

    Root URL

    URL to the Grappa instance.

    Home URL

    URL to the Grappa instance.

    Valid redirect URIs

    URL to the Grappa instance, followed by * to allow any URL within this instance.

    Valid post logout redirect URIs

    URL to the Grappa instance, followed by * to allow any URL within this instance.

    Web origins

    A single plus sign (+). This will cause Keycloak to use the same value as Valid redirect URIs.

  3. Under Settings  Capability config, enable Client authentication and the Standard Flow.

  4. Under Credentials, select Client ID and secret as the Client authenticator and click Save, then copy the Client secret.

  5. Update the Grappa settings with the corresponding values:

    OIDC_ENABLED=true
OIDC_PROVIDER=keycloak
OIDC_PROVIDER_DISCOVERY_URI=https://<YOUR_KEYCLOAK_INSTANCE>/realms/<YOUR_REALM_NAME>
OIDC_CLIENT_ID=<YOUR_CLIENT_ID>
OIDC_CLIENT_SECRET=<YOUR_CLIENT_SECRET>

Using Microsoft Entra ID

  1. Register a new application on Entra ID.

  2. Enable implicit ID tokens on this application.

    As the redirect URI for the new Web platform, use the /oidc/sso-callback on your Grappa instance.

  3. Create a client secret on this application and copy its value.

  4. Update Grappa settings with the corresponding values:

    OIDC_ENABLED=true
OIDC_PROVIDER=default
# This URI can be found under the Endpoints tab of the application overview
OIDC_PROVIDER_DISCOVERY_URI=https://login.microsoftonline.com/.../v2.0
# This can be copied from the Essentials section of the application overview
OIDC_CLIENT_ID=<YOUR_CLIENT_ID>
# This can only be copied immediately after creating the client secret
OIDC_CLIENT_SECRET=<YOUR_CLIENT_SECRET>

Disabling OpenID Connect

System administrators can disable OpenID Connect on an entire instance by defining OIDC_ENABLED=false in the settings.

OpenID Connect is disabled by default.

This will cause Grappa to treat all accounts as local accounts, restoring password authentication:

  • Accounts that were created locally and later connected to OpenID Connect can be used again immediately using their previous password.

  • Accounts that did not exist locally, then were created automatically after logging in through OpenID Connect, do not have any password set. Users will need to request a password reset using the Forgot your password? link on the login page.

Disconnecting individual users

Through the administration interface, instance administrators can disconnect an account from OpenID Connect by editing users individually and erasing the User.oidc_subject value.

Disabling OIDC on an account will restore password authentication. A new password may then need to be set, either through the administration interface or by letting the user click on the Forgot your password? link on the login page.

Technical information

This section contains information that may be helpful to system administrators attempting to diagnose issues with their OIDC configuration.

Token claim retrieval

After a successful authentication, Grappa will look for various claims in the JSON Web Token to login or register a user. Grappa will look for the first occurrence of a claim in the following sections, in order:

  1. info_token_claims

  2. id_token_claims

  3. auth_token_claims

Authentication process

Because Grappa uses email addresses to uniquely identify users, it requires both the sub (subject) and email claims to be present. An HTTP 500 error will occur if these claims are missing.

When an account already exists with this OIDC subject claim, then the login process ends here and the user is authenticated.

When no account exists with this OIDC subject claim, but an account exists with this email instead

  • If it was already using OIDC, but with a different subject claim, a SuspiciousOperation error occurs. System administrators may need to disconnect the existing account from OIDC.

  • If it was not already using OIDC, its display name may be updated from the token claims. It may also be marked as having a verified email.

When there is no existing account, a new one gets created, with its email, display name and email verification defined from the token claims.

Display names

If any of the following claims are present, they will be set as the user’s display name:

  1. preferred_username

  2. username

  3. name

When creating a new account, if none of the above claims are present, Grappa falls back to the email. On existing accounts, the display name remains unchanged.

Email verification

When the non-standard email_verified claim is set to true, the user will be marked as having a verified email. This claim is known to be provided by Keycloak. When this claim does not exist, it is also assumed to be true. If an account already exists and the returned value for email_verified is true, the user email is immediately set as verified in Grappa.

When the authentication process creates an account without a verified email, a verification email is automatically sent like it would with a local user registration.

The authentication process cannot cause an account with an already verified email to lose this status.