authkit nextjs
v0.16.0
Next.js の AuthKit ライブラリは、Next.js で WorkOS と AuthKit を使用した認証とセッション管理のための便利なヘルパーを提供します。
注: このライブラリは、Next.js App Router で使用することを目的としています。
次のコマンドを使用してパッケージをインストールします。
npm i @workos-inc/authkit-nextjs
または
yarn add @workos-inc/authkit-nextjs
次の値が.env.local環境変数ファイルに存在することを確認してください。クライアント ID と API キーは WorkOS ダッシュボードで確認でき、リダイレクト URI もそこで構成できます。
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 、セッション Cookie の暗号化に使用される秘密キーです。少なくとも 32 文字の長さである必要があります。 1Password ジェネレーターまたはopensslライブラリを使用して、コマンド ラインから強力なパスワードを生成できます。
openssl rand -base64 24
signOutメソッドを使用するには、WorkOS ダッシュボード設定の [リダイレクト] でアプリのホームページを設定する必要があります。
特定の環境変数はオプションであり、Cookie 設定のデバッグや構成に使用できます。
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使用して、アプリ/ドメイン間で WorkOS セッションを共有できます。注: WORKOS_COOKIE_PASSWORDはアプリ/ドメイン間で同じである必要があります。ほとんどのユースケースでは必要ありません。
WorkOS では、認証後にユーザーをリダイレクトするためのコールバック URL が必要です。 Next.js アプリで API ルートを公開し、以下を追加します。
import { handleAuth } from '@workos-inc/authkit-nextjs' ;
export const GET = handleAuth ( ) ;このルートがWORKOS_REDIRECT_URI変数および WorkOS ダッシュボードで構成されたリダイレクト URI と一致することを確認してください。たとえば、リダイレクト URI がhttp://localhost:3000/auth/callbackの場合、上記のコードを/app/auth/callback/route.tsに置きます。
次のようにreturnPathnameオプションをhandleAuthに渡すことで、サインイン後にユーザーが送信されるパス名を制御することもできます。
export const GET = handleAuth ( { returnPathname : '/dashboard' } ) ; handleAuthいくつかのオプションとともに使用できます。
| オプション | デフォルト | 説明 |
|---|---|---|
returnPathname | / | サインイン後にユーザーをリダイレクトするパス名 |
baseURL | undefined | リクエスト内の URL の代わりにリダイレクト URI に使用するベース URL。ホスト名がリクエスト内のホスト名と異なる可能性がある docker などのコンテナーでアプリが実行されている場合に便利です |
このライブラリは、ルートのセッション管理を提供するために Next.js ミドルウェアに依存しています。プロジェクトのルートにあるmiddleware.tsファイルに次の内容を追加します。
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' ] } ;ミドルウェアはいくつかのオプションを使用して構成できます。
| オプション | デフォルト | 説明 |
|---|---|---|
redirectUri | undefined | リダイレクト URI を動的に設定する必要がある場合に使用されます (Vercel プレビュー展開など)。 |
middlewareAuth | undefined | ミドルウェア認証オプションを構成するために使用されます。詳細については、「ミドルウェア認証」を参照してください。 |
debug | false | デバッグログを有効にします。 |
signUpPaths | [] | AuthKit にリダイレクトするときに「サインアップ」画面のヒントを使用するパスを指定するために使用されます。 |
リダイレクト URI を動的に設定する必要がある場合 (Vercel プレビュー展開など)、 authkitMiddlewareのredirectUriオプションを使用します。
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' ] } ;カスタム リダイレクト URI は、環境変数で構成されたリダイレクト URI 上で使用されます。
AuthKitProviderでラップするAuthKitProvider使用してアプリのレイアウトをラップすると、認証エッジ ケースに対する保護が追加されます。
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 >
) ;
}サインインおよびサインアウトのビューを表示するページの場合は、 withAuth使用して 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 >
) ;
}ユーザーのサインインが必須のページでは、 ensureSignedInオプションを使用できます。
const { user } = await withAuth ( { ensureSignedIn : true } ) ; ensureSignedIn有効にすると、ユーザーが認証されずにページにアクセスしようとした場合に AuthKit にリダイレクトされます。
このライブラリのデフォルトの動作では、ページごとにwithAuthメソッドを介して認証を要求します。 withAuth呼び出したくない場合 (ページにユーザー データが必要ない場合など)、またはミドルウェア マッチャーで定義されたすべてのルートが保護される「デフォルトで安全な」アプローチを希望する場合のユースケースがいくつかあります。特に指定がない限り。そのような場合は、代わりにミドルウェア認証を使用するようにオプトインできます。
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' ] } ;上記の例では、 /adminページにはユーザーのサインインが必要ですが、 /と/aboutはサインインせずにアクセスできます。
unauthenticatedPaths Next.js マッチャーと同じ glob ロジックを使用します。
カスタム ミドルウェアを作成する場合は、ユーザー セッションをチェックすると便利な場合があります。 getSessionヘルパー メソッドは、Cookie からセッションを取得し、アクセス トークンを検証します。
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*' ] } ;現在ログインしているユーザーをサインアウトし、アプリのホームページにリダイレクトするには、 signOutメソッドを使用します。ホームページのリダイレクトは、WorkOS ダッシュボードの [リダイレクト] 設定で設定されます。
アプリ内でImpersonationコンポーネントをレンダリングすると、誰かがユーザーになりすましていることが明確になります。このコンポーネントには、偽装されたユーザーに関する情報を含むフレームと、偽装を停止するボタンが表示されます。
import { Impersonation } from '@workos-inc/authkit-nextjs' ;
export default function App ( ) {
return (
< div >
< Impersonation / >
{ /* Your app content */ }
< / div >
) ;
}別のサービスに API リクエストを行う場合など、アクセス トークンを直接取得すると便利な場合があります。
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 > ;
}サーバー アクションまたはルート ハンドラーでrefreshSessionメソッドを使用して、ユーザーのロールや権限への変更を含む最新のセッションの詳細を取得します。
セッションを別の組織に切り替えるために、 organizationIdパラメータをrefreshSessionに渡すことができます。現在のセッションが次の組織に対して許可されていない場合は、適切な認証エラーが返されます。
signUpPathsオプションをauthkitMiddlewareに渡して、AuthKit にリダイレクトするときに「サインアップ」画面ヒントを使用するパスを指定できます。これは、認証を必須とするパスをサインアップ ページとして扱う必要がある場合に便利です。
import { authkitMiddleware } from '@workos-inc/authkit-nextjs' ;
export default authkitMiddleware ( {
signUpPaths : [ '/account/sign-up' , '/dashboard/:path*' ] ,
} ) ;デバッグ ログを有効にするには、デバッグ フラグを有効にしてミドルウェアを初期化します。
import { authkitMiddleware } from '@workos-inc/authkit-nextjs' ;
export default authkitMiddleware ( { debug : true } ) ;withAuth({ ensureSignedIn: true })呼び出しを try/catch ブロックでラップすると、 NEXT_REDIRECTエラーが発生します。これは、セッションが検出されず、Next のリダイレクトが try/catch の外部で呼び出される必要がある場合に、 withAuthユーザーを AuthKit にリダイレクトしようとするためです。
