Authio Provider for Auth.js (NextAuth.js)

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

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

Prerequisites

This library is an extension of Auth.js and is designed to work with Next.js. Before you begin, ensure you have next and next-auth installed in your project.

• Next.js Documentation
• Auth.js (NextAuth.js) Documentation

Installation

Install the provider using your preferred package manager:

With NPM

npm install @your-npm-username/next-auth-authio-provider next-auth

With Yarn

yarn add @your-npm-username/next-auth-authio-provider next-auth

With PNPM

pnpm add @your-npm-username/next-auth-authio-provider next-auth

Setup

Environment Variables

You need to configure your Authio credentials as environment variables. Create a .env.local file in the root of your project and add the following variables:

AUTH_OIDC_ISSUER="[https://your-authio-instance.com/realms/your-realm](https://your-authio-instance.com/realms/your-realm)"
AUTH_OIDC_CLIENT_ID="your-authio-client-id"
AUTH_OIDC_CLIENT_SECRET="your-authio-client-secret"

# This secret is used by Auth.js to sign and encrypt tokens.
# Generate a strong, random string with: `openssl rand -base64 32`
AUTH_SECRET="your-strong-random-auth-secret"

Configuration

Set up your Auth.js configuration. In the root of your project, create an auth.ts file (or pages/api/auth/[...nextauth].ts for the Pages Router).

// auth.ts
import NextAuth from "next-auth";
import { Authio } from "@your-npm-username/next-auth-authio-provider";

export const { handlers, signIn, signOut, auth } = NextAuth({
  providers: [
    Authio({
      issuer: process.env.AUTH_OIDC_ISSUER,
      clientId: process.env.AUTH_OIDC_CLIENT_ID,
      clientSecret: process.env.AUTH_OIDC_CLIENT_SECRET,
    }),
  ],
});

That's it! The Authio provider will handle the OIDC flow, including the authorization, token, and userinfo endpoints.

Advanced Usage

Accessing Profile Claims with Callbacks

The Authio provider returns a rich profile object. You can access its claims within the Auth.js callbacks to add custom data to your session token.

The AuthioProfile interface provides the following claims:

interface AuthioProfile {
  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;
  // and standard profile properties like sub, name, email
}

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

// auth.ts
import NextAuth from "next-auth";
import { Authio, AuthioProfile } from "@your-npm-username/next-auth-authio-provider";

export const { handlers, signIn, signOut, auth } = NextAuth({
  providers: [
    Authio({
      issuer: process.env.AUTH_OIDC_ISSUER,
      clientId: process.env.AUTH_OIDC_CLIENT_ID,
      clientSecret: process.env.AUTH_OIDC_CLIENT_SECRET,
    }),
  ],
  callbacks: {
    // The `jwt` callback is called first.
    // The `profile` object is only available on the initial sign-in.
    async jwt({ token, profile }) {
      if (profile) {
        // Cast the profile to access custom claims
        const authioProfile = profile as AuthioProfile;
        token.username = authioProfile.preferred_username;
        token.picture = authioProfile.picture; // Persist the picture
      }
      return token;
    },
    // The `session` callback is called next, receiving data from the `token`.
    async session({ session, token }) {
      if (session.user && token.username) {
        // Add the custom `username` property to the session user object
        (session.user as any).username = token.username;
      }
      return session;
    },
  },
});

TypeScript Module Augmentation

To get full type safety for your custom session properties, you need to extend the default Auth.js types. Create a file named types/next-auth.d.ts in your project:

// types/next-auth.d.ts
import "next-auth";

declare module "next-auth" {
  /**
   * Extends the built-in `Session.user` object with your custom properties.
   */
  interface User {
    username?: string;
  }

  interface Session {
    user?: User;
  }
}

// Also augment the JWT type
import "next-auth/jwt";

declare module "next-auth/jwt" {
  /**
   * Extends the built-in JWT token with your custom properties.
   */
  interface JWT {
    username?: string;
  }
}

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

License

This project is licensed under the MIT License. See the LICENSE file for details.