Authio Provider for NextAuth.js / Auth.js

An OIDC (OpenID Connect) provider for NextAuth.js and Auth.js that enables easy integration with the Authio authentication service.

This provider is built on top of the standard OIDC provider of each version, ensuring full compatibility and security. It simplifies the setup process by providing a pre-configured client for Authio.

Which entry point do I import?

The package ships two entry points so you can stay on stable NextAuth v4 without waiting for Auth.js v5 to leave beta:

| Your next-auth version | Import from | Provider type | | --- | --- | --- | | ^4.24.0 (stable) | authio-provider-nextauth | oauth + OIDC discovery | | ^5.0.0-beta (Auth.js) | authio-provider-nextauth/v5 | oidc |

Both export the same Authio function and the same AuthioProfile type — only the import path and the underlying config shape differ.

Installation

next-auth is a peer dependency: install the version you actually want to use.

NextAuth v4 (stable)

npm install authio-provider-nextauth next-auth@^4.24.0

Auth.js v5 (beta)

npm install authio-provider-nextauth next-auth@beta

Setup — NextAuth v4 (stable)

Environment variables (v4)

Create a .env.local in the root of your project:

AUTH_AUTHIO_ISSUER="https://your-authio-instance.com/realms/your-realm"
AUTH_AUTHIO_ID="your-authio-client-id"
AUTH_AUTHIO_SECRET="your-authio-client-secret"

# Used by NextAuth to sign and encrypt tokens.
# Generate one with: openssl rand -base64 32
NEXTAUTH_SECRET="your-strong-random-secret"
NEXTAUTH_URL="http://localhost:3000"

Configuration (v4)

// pages/api/auth/[...nextauth].ts
import NextAuth from "next-auth";
import { Authio } from "authio-provider-nextauth";

export default NextAuth({
  providers: [
    Authio({
      issuer: process.env.AUTH_AUTHIO_ISSUER!,
      clientId: process.env.AUTH_AUTHIO_ID!,
      clientSecret: process.env.AUTH_AUTHIO_SECRET!,
    }),
  ],
});

On v4 issuer is required — it is what the /.well-known/openid-configuration discovery URL is built from, and v4 has no environment-variable inference to fall back on. The ! is needed because process.env values are typed as possibly undefined.

The provider is pre-configured with OIDC discovery, scope: "openid email profile", checks: ["pkce", "state"] and idToken: true.

Setup — Auth.js v5 (beta)

Environment variables (v5)

AUTH_AUTHIO_ISSUER="https://your-authio-instance.com/realms/your-realm"
AUTH_AUTHIO_ID="your-authio-client-id"
AUTH_AUTHIO_SECRET="your-authio-client-secret"

# Generate one with: npx auth secret
AUTH_SECRET="your-strong-random-secret"

Configuration (v5)

Auth.js v5 infers clientId, clientSecret and issuer from the AUTH_AUTHIO_* variables above, so no arguments are needed:

// auth.ts
import NextAuth from "next-auth";
import { Authio } from "authio-provider-nextauth/v5";

export const { handlers, signIn, signOut, auth } = NextAuth({
  providers: [Authio],
});

Or pass them explicitly:

providers: [
  Authio({
    issuer: process.env.AUTH_AUTHIO_ISSUER,
    clientId: process.env.AUTH_AUTHIO_ID,
    clientSecret: process.env.AUTH_AUTHIO_SECRET,
  }),
],

Advanced usage

Overriding the default configuration

Anything you pass is deep-merged over the provider defaults, so you can extend a nested value without losing the rest of it:

Authio({
  issuer: process.env.AUTH_AUTHIO_ISSUER!,
  clientId: process.env.AUTH_AUTHIO_ID!,
  clientSecret: process.env.AUTH_AUTHIO_SECRET!,
  // adds "roles" — the default scope is not replaced wholesale
  authorization: { params: { scope: "openid email profile roles" } },
});

Accessing profile claims with callbacks

The AuthioProfile type describes the claims returned by Authio:

interface AuthioProfile {
  sub: string;
  name?: string;
  email?: string;
  picture?: string;
  exp: number;
  iat: number;
  auth_time: number;
  jti: string;
  iss: string;
  aud: string;
  typ: string;
  azp: string;
  session_state: string;
  at_hash: string;
  acr: string;
  sid: string;
  email_verified: boolean;
  preferred_username: string;
  given_name: string;
  family_name: string;
  user: any;
  [claim: string]: unknown; // any extra claim configured on your Authio client
}

Here's how to add preferred_username to the JWT and the session:

import NextAuth from "next-auth";
import { Authio, type AuthioProfile } from "authio-provider-nextauth";

export default NextAuth({
  providers: [
    Authio({
      issuer: process.env.AUTH_AUTHIO_ISSUER!,
      clientId: process.env.AUTH_AUTHIO_ID!,
      clientSecret: process.env.AUTH_AUTHIO_SECRET!,
    }),
  ],
  callbacks: {
    // `profile` is only available on the initial sign-in.
    async jwt({ token, profile }) {
      if (profile) {
        const authioProfile = profile as AuthioProfile;
        token.username = authioProfile.preferred_username;
        token.picture = authioProfile.picture;
      }
      return token;
    },
    async session({ session, token }) {
      if (session.user && token.username) {
        (session.user as any).username = token.username;
      }
      return session;
    },
  },
});

The same callbacks work on v5 — only the import path changes to authio-provider-nextauth/v5.

TypeScript module augmentation

To get full type safety for your custom session properties, extend the built-in types. Create types/next-auth.d.ts:

import "next-auth";
import "next-auth/jwt";

declare module "next-auth" {
  interface User {
    username?: string;
  }

  interface Session {
    user?: User;
  }
}

declare module "next-auth/jwt" {
  interface JWT {
    username?: string;
  }
}

Your editor will now provide autocompletion for session.user.username without any type errors.

Contributing

The two entry points are compiled separately, against the two next-auth majors installed side by side (v5 via the next-auth-v5 npm alias):

npm install
npm run build   # tsc -p tsconfig.json  &&  tsc -p src/v5/tsconfig.json

src/profile.ts is shared and deliberately imports nothing from next-auth, so it compiles identically under both projects.

Why .npmrc sets legacy-peer-deps=true

Both next-auth majors declare next and react as peer dependencies, which npm 7+ would auto-install — pulling the whole Next.js build toolchain (and its CVEs) into a repo that never builds or runs a Next.js app. This package only needs the type declarations to compile, so those peers are skipped. It affects local development only: the published package has no dependencies at all and ships nothing but dist/.

License

This project is licensed under the MIT License.