Skip to main content

OAuth and identity

Authenik8 normalizes Google and GitHub callbacks into one identity model. OAuth state is stored in Redis and consumed once.

const auth = await createAuthenik8({
  jwt,
  refreshSecret,
  oauth: {
    google: {clientId, clientSecret, redirectUri},
    github: {clientId, clientSecret, redirectUri},
  },
});

Each configured provider exposes redirect(req, res, mode?) and handleCallback(req).

Resolution outcomes​

  • Existing provider login: The provider identity is already linked, so tokens are issued.
  • New identity: No email or provider match exists, so a new identity is created.
  • Link required: The email belongs to an existing identity, but the provider is not linked.
  • Explicit link: An authenticated user starts link mode and attaches the provider to that identity.

Authenik8 does not automatically link an OAuth provider only because its email matches an existing account. Generated fullstack applications use an authenticated, short-lived link-intent flow.

Normalized profile​

{
  email: 'user@example.com',
  name: 'User Name',
  provider: 'google',
  providerId: 'provider-user-id',
  email_verified: true,
}

OAuth state lives under <redisKeyPrefix>:oauth:state:<state> for five minutes. Redis identity indexes use <redisKeyPrefix>:oauth:v1:user:<userId>, <redisKeyPrefix>:oauth:v1:email:<email>, and <redisKeyPrefix>:oauth:v1:provider:<provider>:<providerId>. The default redisKeyPrefix is derived from the configured issuer and audience.