Custom OAuth Providers

Aura Auth supports integrations with providers that implement the OAuth 2.0 Authorization Framework and OpenID Connect (OIDC). These protocols allow applications to delegate authorization and authentication to external services and identity providers.

Aura Auth includes built-in providers for widely used services such as GitHub, GitLab, X, and Spotify. See the OAuth Providers guide for the complete list of supported providers.

When an application needs to integrate with an internal authorization server or a provider that is not included by default, Aura Auth supports custom provider configurations. These configurations allow the application to define provider-specific endpoints, scopes, and profile mapping while using Aura Auth's existing authentication flow.

Adding a Custom OAuth ProviderCopy Anchor Link

A custom OAuth provider can be configured using the OAuthProvider type. The provider configuration defines the authorization and token endpoints, optional user information and token management endpoints, requested scopes, and profile mapping.

For the complete list of supported properties and their types, see the OAuth Provider API Reference.

OAuth 2.0 ProviderCopy Anchor Link

The following table describes the main properties available when configuring a custom OAuth 2.0 provider.

import { createAuth, type User } from "@aura-stack/auth"
import type { OAuthProvider } from "@aura-stack/auth/types"

interface CustomProviderProfile {
  id: number
  username: string
  email: string
  name: string
  avatar_url: string
}

const provider: OAuthProvider<CustomProviderProfile, User> = {
  id: "custom",
  name: "Custom Provider",
  authorize: {
    url: "https://custom.com/authorization",
    params: {
      scope: "user:email user:profile",
      responseType: "code",
    },
  },
  accessToken: "https://custom.com/access_token",
  userInfo: "https://api.custom.com/v1/user",
  profile(profile) {
    return {
      sub: profile.id.toString(),
      name: profile.name,
      email: profile.email,
      image: profile.avatar_url,
    }
  },
}

export const auth = createAuth({ oauth: [provider] })

The profile function maps the provider's profile to Aura Auth's user representation. The returned sub value must be a stable, unique identifier for the user within that provider. Avoid using mutable values, such as usernames or email addresses, as the subject identifier.

OpenID Connect ProviderCopy Anchor Link

For providers that implement OpenID Connect, Aura Auth can use the issuer URL to configure the provider. OIDC defines an identity layer on top of OAuth 2.0 and standardizes identity claims and discovery metadata.

The following table describes the main properties available when configuring an OIDC provider.

import { createAuth, type User } from "@aura-stack/auth"
import type { OpenIDProvider } from "@aura-stack/auth/types"

interface CustomOIDCProfile {
  sub: string
  name: string
  email: string
  picture?: string
}

const provider: OpenIDProvider<CustomOIDCProfile, User> = {
  id: "custom-oidc",
  name: "Custom OIDC Provider",
  issuer: "https://custom.com",
  scope: "openid profile email",
  profile(profile) {
    return {
      sub: profile.sub,
      name: profile.name,
      email: profile.email,
      image: profile.picture,
    }
  },
}

export const auth = createAuth({ oauth: [provider] })

For OIDC providers, the sub claim identifies the user within the issuer's namespace. Use this stable identifier to associate the authenticated identity with the correct user.