OAuth2

This page is marked as "earlydoc", which means that it more of a collection of notes and an early draft before this page turns into good documentation later on. It is hoped that this early form of documentation is useful to you, but please understand that most documentation pages are higher quality than this. If you have suggestions or comments, please do get in contact or consider contributing your suggestions to the OliveTin documentation.

OliveTin supports OAuth2 for login with any OAuth2 compliant provider.

At the moment, username fetching is only supported on GitHub. More will be added soon, probably with the addition of OpenID Connect support.

authOAuth2RedirectUrl: http://localhost:1337/oauth/callback
authOAuth2Providers:
  github:
    clientId: 1234567890
    clientSecret: 1234567890

Provider configuration

  • name - a "simple name" for the provider, used in the login redirect and internally in OliveTin, e.g. github

  • title - the human-readable name of the provider, e.g. GitHub

  • clientId - the client ID provided by the OAuth2 provider

  • clientSecret - the client secret provided by the OAuth2 provider

  • icon - the icon to use for the provider. Accepts any HTML, e.g. <iconify-icon icon="simple-icons:authentik"></iconify-icon>

  • scopes - a list of scopes to request.

  • authUrl - the URL to redirect to for authentication

  • tokenUrl - the URL to exchange the code for a token

  • whoamiUrl - the URL to fetch user information from

  • usernameField - the field in the user information response to use as the username

  • userGroupField - the field in the user information response to use as the group. This is a string containing one group name, e.g. olivetin_group

  • addToUsergroup - a group name to add to every user who logs in via this provider. If the user already has a usergroup (e.g. from userGroupField), this value is appended to it; otherwise it becomes the user’s usergroup. Useful for giving all users from this provider a common group for ACLs, e.g. addToUsergroup: github

  • certBundlePath - the path to a certificate to add to the truststore for authentication requests, e.g. /certs/internal.crt

  • insecureSkipVerify - a boolean to disable certificate verfication

  • connectTimeout - an integer for seconds until the request will timeout, e.g. 10

Built-in providers (name)

OliveTin comes with a few built-in providers for convenience. If you are using one of these with a name, then you don’t need to specify the various URLs, scopes, icon, usernameField, etc. It will be automatically configured for you. You will still need to provide the client ID and client secret.

  • github - GitHub

  • google - Google

AddToUsergroup examples

The addToUsergroup option assigns a group to every user who signs in through that OAuth2 provider. You can use it alone, or together with userGroupField, so that all users from the provider share a common group for ACLs (e.g. "everyone from GitHub") while still keeping provider-specific groups when available.

When the provider does not return a group

Some providers (e.g. Google with standard Gmail accounts) do not return a group claim. Users logging in through them get no group, so they do not match any ACLs and end up with no permissions or visible actions. Use addToUsergroup to give every user from that provider a default group such as guest:

authOAuth2Providers:
  google:
    clientId: your-client-id
    clientSecret: your-client-secret
    addToUsergroup: guest

Then ensure an ACL matches that group, for example matchUsergroups: ["guest"], so those users get the intended access.

All users from a provider in one group

Give every user who logs in via GitHub the group github so you can target them in ACLs:

authOAuth2Providers:
  github:
    clientId: your-client-id
    clientSecret: your-client-secret
    addToUsergroup: github

Then in your actions you can restrict access with allowedUserGroups: ["github"].

Combining with userGroupField

If your provider returns a group (e.g. from GitHub org/team or an IdP), use both userGroupField and addToUsergroup. The provider group is used as the user’s group, and addToUsergroup is appended so the user belongs to both:

authOAuth2Providers:
  github:
    clientId: your-client-id
    clientSecret: your-client-secret
    userGroupField: olivetin_group
    addToUsergroup: github

A user with olivetin_group: admins will end up in groups admins and github; a user with no group will get only github.

Multiple providers, shared and per-provider groups

Use different addToUsergroup values per provider so you can allow "all OAuth users" or "only GitHub" / "only Google":

authOAuth2Providers:
  github:
    clientId: github-client-id
    clientSecret: github-client-secret
    addToUsergroup: github
  google:
    clientId: google-client-id
    clientSecret: google-client-secret
    addToUsergroup: google

Then use ACLs such as allowedUserGroups: ["github"] for GitHub-only actions or allowedUserGroups: ["github", "google"] for any OAuth user.