authkit nextjs

Biblioteca AuthKit Next.js

A biblioteca AuthKit para Next.js fornece ajudantes convenientes para autenticação e gerenciamento de sessão usando WorkOS e AuthKit com Next.js.

Nota: Esta biblioteca deve ser usada com o Next.js App Router.

Instalação

Instale o pacote com:

 npm i @workos-inc/authkit-nextjs

ou

 yarn add @workos-inc/authkit-nextjs

Tutorial em vídeo

Pré-voo

Certifique-se de que os valores a seguir estejam presentes no arquivo de variáveis ​​de ambiente .env.local . O ID do cliente e a chave de API podem ser encontrados no painel do WorkOS, e o URI de redirecionamento também pode ser configurado lá.

WORKOS_CLIENT_ID= " client_... " # retrieved from the WorkOS dashboard
WORKOS_API_KEY= " sk_test_... " # retrieved from the WorkOS dashboard
WORKOS_COOKIE_PASSWORD= " <your password> " # generate a secure password here
NEXT_PUBLIC_WORKOS_REDIRECT_URI= " http://localhost:3000/callback " # configured in the WorkOS dashboard

WORKOS_COOKIE_PASSWORD é a chave privada usada para criptografar o cookie da sessão. Deve ter pelo menos 32 caracteres. Você pode usar o gerador 1Password ou a biblioteca openssl para gerar uma senha forte através da linha de comando:

 openssl rand -base64 24

Para usar o método signOut , você precisará definir a página inicial do seu aplicativo nas configurações do painel do WorkOS em "Redirecionamentos".

Configuração opcional

Certas variáveis ​​de ambiente são opcionais e podem ser usadas para depurar ou definir configurações de cookies.

WORKOS_COOKIE_MAX_AGE= ' 600 ' # maximum age of the cookie in seconds. Defaults to 400 days, the maximum allowed in Chrome
WORKOS_COOKIE_DOMAIN= ' example.com '
WORKOS_COOKIE_NAME= ' authkit-cookie '
WORKOS_API_HOSTNAME= ' api.workos.com ' # base WorkOS API URL
WORKOS_API_HTTPS=true # whether to use HTTPS in API calls
WORKOS_API_PORT=3000 # port to use for API calls

WORKOS_COOKIE_DOMAIN pode ser usado para compartilhar sessões do WorkOS entre aplicativos/domínios. Nota: O WORKOS_COOKIE_PASSWORD precisaria ser o mesmo em todos os aplicativos/domínios. Não é necessário para a maioria dos casos de uso.

Configurar

Rota de retorno de chamada

O WorkOS exige que você tenha um URL de retorno de chamada para redirecionar os usuários após a autenticação. Em seu aplicativo Next.js, exponha uma rota de API e adicione o seguinte.

 import { handleAuth } from '@workos-inc/authkit-nextjs' ;

export const GET = handleAuth ( ) ;

Certifique-se de que esta rota corresponda à variável WORKOS_REDIRECT_URI e ao URI de redirecionamento configurado no painel do WorkOS. Por exemplo, se o seu URI de redirecionamento for http://localhost:3000/auth/callback então você colocaria o código acima em /app/auth/callback/route.ts .

Você também pode controlar o nome do caminho para o qual o usuário será enviado após o login, passando uma opção returnPathname para handleAuth da seguinte forma:

 export const GET = handleAuth ( { returnPathname : '/dashboard' } ) ;

handleAuth pode ser usado com diversas opções.

Opção	Padrão	Descrição
returnPathname	/	O nome do caminho para o qual redirecionar o usuário após fazer login
baseURL	undefined	O URL base a ser usado para o URI de redirecionamento em vez daquele na solicitação. Útil se o aplicativo estiver sendo executado em um contêiner como o docker, onde o nome do host pode ser diferente daquele na solicitação

Middleware

Esta biblioteca depende do middleware Next.js para fornecer gerenciamento de sessão para rotas. Coloque o seguinte no seu arquivo middleware.ts na raiz do seu projeto:

 import { authkitMiddleware } from '@workos-inc/authkit-nextjs' ;

export default authkitMiddleware ( ) ;

// Match against pages that require auth
// Leave this out if you want auth on every resource (including images, css etc.)
export const config = { matcher : [ '/' , '/admin' ] } ;

O middleware pode ser configurado com diversas opções.

Opção	Padrão	Descrição
redirectUri	undefined	Usado nos casos em que você precisa que seu URI de redirecionamento seja definido dinamicamente (por exemplo, implantações de visualização do Vercel)
middlewareAuth	undefined	Usado para configurar opções de autenticação de middleware. Consulte autenticação de middleware para obter mais detalhes.
debug	false	Habilita logs de depuração.
signUpPaths	[]	Usado para especificar caminhos que devem usar a dica da tela de 'inscrição' ao redirecionar para o AuthKit.

URI de redirecionamento personalizado

Nos casos em que você precisa que seu URI de redirecionamento seja definido dinamicamente (por exemplo, implantações de visualização do Vercel), use a opção redirectUri em authkitMiddleware :

 import { authkitMiddleware } from '@workos-inc/authkit-nextjs' ;

export default authkitMiddleware ( {
  redirectUri : 'https://foo.example.com/callback' ,
} ) ;

// Match against pages that require auth
// Leave this out if you want auth on every resource (including images, css etc.)
export const config = { matcher : [ '/' , '/admin' ] } ;

URIs de redirecionamento personalizados serão usados ​​em um URI de redirecionamento configurado nas variáveis ​​de ambiente.

Uso

Envolva seu aplicativo em AuthKitProvider

Use AuthKitProvider para encapsular o layout do seu aplicativo, o que adiciona algumas proteções para casos extremos de autenticação.

 import { AuthKitProvider } from '@workos-inc/authkit-nextjs' ;

export default function RootLayout ( { children } : { children : React . ReactNode } ) {
  return (
    < html lang = "en" >
      < body >
        < AuthKitProvider > { children } < / AuthKitProvider >
      < / body >
    < / html >
  ) ;
}

Obtenha o usuário atual

Para páginas nas quais você deseja exibir uma visualização de login e logout, use withAuth para recuperar o perfil do usuário do WorkOS.

 import Link from 'next/link' ;
import { getSignInUrl , getSignUpUrl , withAuth , signOut } from '@workos-inc/authkit-nextjs' ;

export default async function HomePage ( ) {
  // Retrieves the user from the session or returns `null` if no user is signed in
  const { user } = await withAuth ( ) ;

  if ( ! user ) {
    // Get the URL to redirect the user to AuthKit to sign in
    const signInUrl = await getSignInUrl ( ) ;

    // Get the URL to redirect the user to AuthKit to sign up
    const signUpUrl = await getSignUpUrl ( ) ;

    return (
      < >
        < Link href = { signInUrl } > Log in < / Link >
        < Link href = { signUpUrl } > Sign Up < / Link >
      < / >
    ) ;
  }

  return (
    < form
      action = { async ( ) => {
        'use server' ;
        await signOut ( ) ;
      } }
    >
      < p > Welcome back { user ?. firstName && `, ${ user ?. firstName } ` } < / p >
      < button type = "submit" > Sign out < / button >
    < / form >
  ) ;
}

Exigindo autenticação

Para páginas onde um usuário conectado é obrigatório, você pode usar a opção ensureSignedIn :

 const { user } = await withAuth ( { ensureSignedIn : true } ) ;

Ativar ensureSignedIn redirecionará os usuários para o AuthKit se eles tentarem acessar a página sem serem autenticados.

Autenticação de middleware

O comportamento padrão desta biblioteca é solicitar autenticação por meio do método withAuth por página. Existem alguns casos de uso em que você não deseja chamar withAuth (por exemplo, você não precisa de dados do usuário para sua página) ou se preferir uma abordagem "segura por padrão", onde todas as rotas definidas em seu matcher de middleware são protegidas salvo especificação em contrário. Nesses casos, você pode optar por usar a autenticação de middleware:

 import { authkitMiddleware } from '@workos-inc/authkit-nextjs' ;

export default authkitMiddleware ( {
  middlewareAuth : {
    enabled : true ,
    unauthenticatedPaths : [ '/' , '/about' ] ,
  } ,
} ) ;

// Match against pages that require auth
// Leave this out if you want auth on every resource (including images, css etc.)
export const config = { matcher : [ '/' , '/admin/:path*' , '/about' ] } ;

No exemplo acima, a página /admin exigirá que um usuário esteja conectado, enquanto / e /about podem ser acessados ​​sem login.

unauthenticatedPaths usa a mesma lógica glob do matcher Next.js.

Recuperar sessão no middleware

Às vezes é útil verificar a sessão do usuário se você deseja compor um middleware customizado. O método auxiliar getSession recuperará a sessão do cookie e verificará o token de acesso.

 import { authkitMiddleware , getSession } from '@workos-inc/authkit-nextjs' ;
import { NextRequest , NextFetchEvent } from 'next/server' ;

export default async function middleware ( request : NextRequest , event : NextFetchEvent ) {
  // authkitMiddleware will handle refreshing the session if the access token has expired
  const response = await authkitMiddleware ( ) ( request , event ) ;

  // If session is undefined, the user is not authenticated
  const session = await getSession ( response ) ;

  // ...add additional middleware logic here

  return response ;
}

// Match against pages that require auth
export const config = { matcher : [ '/' , '/account/:path*' ] } ;

Saindo

Use o método signOut para desconectar o usuário conectado no momento e redirecionar para a página inicial do seu aplicativo. O redirecionamento da página inicial é definido nas configurações do painel do WorkOS em "Redirecionar".

Visualizando uma representação

Renderize o componente Impersonation em seu aplicativo para que fique claro quando alguém está se passando por um usuário. O componente exibirá um quadro com algumas informações sobre o usuário personificado, bem como um botão para interromper a representação.

 import { Impersonation } from '@workos-inc/authkit-nextjs' ;

export default function App ( ) {
  return (
    < div >
      < Impersonation / >
      { /* Your app content */ }
    < / div >
  ) ;
}

Obtenha o token de acesso

Às vezes é útil obter o token de acesso diretamente, por exemplo, para fazer solicitações de API para outro serviço.

 import { withAuth } from '@workos-inc/authkit-nextjs' ;

export default async function HomePage ( ) {
  const { accessToken } = await withAuth ( ) ;

  if ( ! accessToken ) {
    return < div > Not signed in < / div > ;
  }

  const serviceData = await fetch ( '/api/path' , {
    headers : {
      Authorization : `Bearer ${ accessToken } ` ,
    } ,
  } ) ;

  return < div > { serviceData } < / div > ;
}

Atualizando a sessão

Use o método refreshSession em uma ação de servidor ou manipulador de rota para buscar os detalhes mais recentes da sessão, incluindo quaisquer alterações nas funções ou permissões do usuário.

O parâmetro organizationId pode ser passado para refreshSession para alternar a sessão para uma organização diferente. Se a sessão atual não for autorizada para a próxima organização, será retornado um erro de autenticação apropriado.

Inscrever caminhos

A opção signUpPaths pode ser passada para authkitMiddleware para especificar caminhos que devem usar a dica de tela de 'inscrição' ao redirecionar para AuthKit. Isto é útil para casos em que você deseja que um caminho que exija a autenticação seja tratado como uma página de inscrição.

 import { authkitMiddleware } from '@workos-inc/authkit-nextjs' ;

export default authkitMiddleware ( {
  signUpPaths : [ '/account/sign-up' , '/dashboard/:path*' ] ,
} ) ;

Depuração

Para habilitar logs de depuração, inicialize o middleware com o sinalizador de depuração habilitado.

 import { authkitMiddleware } from '@workos-inc/authkit-nextjs' ;

export default authkitMiddleware ( { debug : true } ) ;

Solução de problemas

Erro NEXT_REDIRECT ao usar blocos try/catch

Envolver uma chamada withAuth({ ensureSignedIn: true }) em um bloco try/catch causará um erro NEXT_REDIRECT . Isso ocorre porque withAuth tentará redirecionar o usuário para o AuthKit se nenhuma sessão for detectada e os redirecionamentos em Next deverão ser chamados fora de um try/catch.