Skip to main content

Authenticate using OIDC

You can either implement OIDC login using a self-hosted tool, like Keycloak or Authentik, or using a cloud-service.

OIDC using a hosted tool​

You should install an OIDC Identity Provider tool on your own and make it available on the internet. You can also use managed providers, such as Auth0, Microsoft Entra/365 or Google Workspace.

tip

Make sure to update your privacy policy to indicate that you are storing membership details in another system, especially if it's cloud hosted.

To integrate, provide us with the following:

  • OIDC Issuer URL, for instance for Keycloak, this might be https://<HOSTNAME>/auth/realms/<REALM>/
    • We will assume that your OIDC Discovery URL is <issuer URL>/.well-known/openid-configuration
  • Client ID
  • Client Secret
  • Scopes to use on request (default: openid profile email)
  • Claims to use on id_token/userinfo (see below for defaults)
  • Testing account (with no rights other than login to this client)

We will provide you with:

  • Redirect URI for Star Accounts production
  • Redirect URI for Star Accounts test

You should enable the Authorization Code Flow for the Star Accounts client. You can use PKCE.

warning

Make sure that the signature of your ID tokens is RS256, instead of HS256, which is the default for Authentik. In Authentik you need to set a "signing key" on the Provider.

OIDC using an app members use​

You can also use an app members use, such as Slack or Discord. For this, we need to find out a method of checking membership, such as checking if the member is in a certain channel or guild/server.

Please request more information if you want to use this option.

Expected return claims for OIDC​

Your userinfo should provide the following claims:

  • sub: Identifier that we can store to identify this user in the future.
    • You may use your internal identifiers, a hashed version or an anonymised ID.
    • Identifier must not change for the same user over time.
  • name: Full name of the user.
  • given_name: Given name(s) or first name(s) of the user, we will use this to address them.
  • email: E-mail address of the user, used for linking accounts.
  • email_verified: Boolean indicating if the e-mail address was verified, such as by verification email or payment link.
  • Any way to find out that this user is an active member, multiple options:
    • Return a groups claim (groups) and have a member group
    • Return a boolean custom claim/userinfo attribute (is_member)
    • Have us make an additional API call with the access_token
      • May be a custom call (if so, please provide API specification)
      • Or a request to the Slack/Discord API to check channel/guild membership