Skip to content
  • Getting Started

Create an auth provider

useAuth aims to support many authentication providers. We've designed an abstraction layer that hopefully makes this achievable.

As of v1.0.0 there's built-in support for Netlify Identity and Auth0. Consider this a proof-of-concept that the abstraction layer works :)

You can create a provider to contribute to useAuth's codebase, or to make it work with your existing authentication infrastructure. It should be possible to make work with traditional cookie/session based authentication. 🤞

If you're fond of your auth service, please contribute. It would mean the world to me ❤️

What is an auth provider

An auth provider is a service that authenticates users. Like Auth0, Netlify Identity, AWS Cognito, Firebase Auth, and others.

useAuth uses auth wrappers to interact with these services in a uniform way. Each wrapper is a class of this type:

// The shape of auth provider wrappers
export interface AuthProviderClass {
// addDefaultParams: (
// props: Omit<AuthOptions, "dispatch">
// ) => Omit<AuthOptions, "dispatch">;
authorize(): void;
signup(): void;
logout(returnTo?: string): void;
dispatch: PayloadSender<AnyEventObject>
): Promise<boolean>;
checkSession(): Promise<{
user: Auth0UserProfile;
authResult: Auth0DecodedHash;
userId(user: AuthUser): string | null;
userRoles(user: AuthUser): string[] | null;

To maintain interoperability, useAuth avoids interacting with services directly. If it can't fit in those methods, open a bug :)

Abstract implementation

You can use this as a starting point for your auth provider wrapper.

// Auth Wrapper for Auth0
export class Auth0 implements AuthProviderClass {
private auth0: Auth0Client.WebAuth;
private dispatch: (eventName: string, eventData?: any) => void;
// Auth0 specific, used for roles
private customPropertyNamespace?: string;
// Initialize the client and save any custom config
constructor(params: AuthOptions) {
// You will almost always need access to dispatch
this.dispatch = params.dispatch;
// Auth0 specific, used for roles
this.customPropertyNamespace = params.customPropertyNamespace;
// Init your client
this.auth0 = new Auth0Client.WebAuth({
...(params as Auth0Options)
// Makes configuration easier by guessing default options
static addDefaultParams(params: ProviderOptions, callbackDomain: string) {
const vals = params as Auth0Options;
return {
redirectUri: `${callbackDomain}/auth0_callback`,
audience: `https://${vals.domain}/api/v2/`,
responseType: "token id_token",
scope: "openid profile email",
public authorize() {
// Open login dialog
public signup() {
// Open signup dialog
public logout(returnTo?: string) {
// Logs user out of the underlying service
public userId(user: Auth0UserProfile): string {
// Return the userId from Auth0 shape of data
public userRoles(user: AuthUser): string[] | null {
// Return user roles from Auth0 shape of data
public async handleLoginCallback(): Promise<boolean> {
// Handle login data after redirect back from service
// Dispatch ERROR on error
// Dispatch AUTHENTICATED on success
// include the user object and authResult with at least an expiresIn value
public async checkSession(): Promise<{
user: Auth0UserProfile;
authResult: Auth0DecodedHash;
}> {
// verify session is still valid
// return fresh user info


You can see the current list of implemented auth providers on GitHub

Use them to guide your implementation :)

Role/scope permissions
API Reference
Created with ❤️ by Swizec et. al.