Authentication services

In-house service

If you wish to integrate with your organisation/institution’s pre-existing authentication service, you will likely have to write a custom authentication provider yourself.

In general, it should be simple to integrate any service that supports the OAuth2 authorisation code flow. You will then need to write an authentication provider that receives the authorisation code and then exchanges it for a authorisation token, and retrieves the user’s username, name, and role via API calls or by extracting it from the token.

See our LumiNUS authentication provider for an example.

If your authentication provider supports OpenID Connect and exposes an OpenID discovery document, then most of this is handled for you via the OpenID authentication provider; you will only need to write an extractor that, given the access token, returns the user’s username, name, and role. See our Cognito claim extractor for an example.


You can use Google as an authentication service. This means that users will sign in using their Google account. The Google account can be a normal account, or it can be an organisation/G Suite account.

Note that because it is not possible to restrict who has a Google account, you must manually create users in the database if you are using Google as an authentication service.

  1. Go to the Google API Console, and create a project (or use one you already have, if you wish).

  2. Go to the credentials page. At the top, select Create credentials, then select the OAuth client ID option. Select Web application as the application type. Give it any name.

    Under Authorised redirect URIs, add the URI to the /login?provider=google route of your deployment. For example, if your deployment is accessible at, add Note: if Google is not your first authentication provider in the frontend configuration, add ?provider=google to the URI.

    You can also add localhost e.g. http://localhost:8000/login for the local frontend development server.

  3. Go to the OAuth consent screen page and configure it to your liking. There are no special scopes required.

  4. Note the client ID and client secret created in step 2.

    In your frontend configuration, add the following variables, changing the number and CLIENT_ID_HERE accordingly. Note: if the number is not 1, make sure you followed the note in step 2.


    In your backend configuration (cadet.exs), add the following to the identity_providers map:

    "google" =>
         openid_provider: :google,
         claim_extractor: Cadet.Auth.Providers.GoogleClaimExtractor

    and the following to the openid_connect_providers list:

    google: [
      discovery_document_uri: "",
      client_id: "CLIENT_ID_HERE",
      client_secret: "CLIENT_SECRET_HERE",
      response_type: "code",
      scope: "openid email"
  5. Done! Note that you need to add users manually. For Google, the username is the primary email of the Google account.

Amazon Cognito