{"id":50746972,"url":"https://github.com/zitadel/next-auth","last_synced_at":"2026-06-10T22:01:40.721Z","repository":{"id":360005596,"uuid":"1248284357","full_name":"zitadel/next-auth","owner":"zitadel","description":"Official Zitadel auth integration for Next.js.","archived":false,"fork":false,"pushed_at":"2026-05-31T16:05:05.000Z","size":3327,"stargazers_count":0,"open_issues_count":2,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-31T16:24:41.568Z","etag":null,"topics":["auth","authentication","authn","authorization","authz","iam","identity","login","next","nextjs","nodejs","sso","typescript","zitadel"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/@zitadel/next-auth","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zitadel.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-24T12:46:08.000Z","updated_at":"2026-05-31T16:01:39.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/zitadel/next-auth","commit_stats":null,"previous_names":["zitadel/next-auth"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/zitadel/next-auth","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zitadel%2Fnext-auth","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zitadel%2Fnext-auth/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zitadel%2Fnext-auth/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zitadel%2Fnext-auth/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zitadel","download_url":"https://codeload.github.com/zitadel/next-auth/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zitadel%2Fnext-auth/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34172196,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-10T02:00:07.152Z","response_time":89,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["auth","authentication","authn","authorization","authz","iam","identity","login","next","nextjs","nodejs","sso","typescript","zitadel"],"created_at":"2026-06-10T22:01:38.526Z","updated_at":"2026-06-10T22:01:40.715Z","avatar_url":"https://github.com/zitadel.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Next.js Auth\n\nA [Next.js](https://nextjs.org/) App Router integration that provides seamless authentication with\nmultiple providers, session management, and React client primitives.\n\nThis integration brings the power and flexibility of OAuth to Next.js App\nRouter applications with full TypeScript support, native Fetch API handling,\nand React hooks and components for session state management.\n\n### Why?\n\nModern web applications require robust, secure, and flexible authentication\nsystems. Integrating OAuth and session management with Next.js App Router requires\ncareful consideration of framework patterns, server-side rendering, and\nTypeScript integration.\n\nHowever, a direct integration isn't always straightforward. Different types\nof applications or deployment scenarios might warrant different approaches:\n\n- **App Router Compatibility:** OAuth and auth flows operate at the HTTP level, while\n  Next.js App Router uses route handlers, server components, and React Server\n  Components boundaries. A proper integration should bridge this gap by\n  providing App Router-native primitives.\n- **HTTP Request Handling:** Next.js route handlers expect GET and POST\n  exports that accept native `Request` objects. This integration wires OAuth\n  directly to these handlers with no adapter overhead.\n- **Session and React Lifecycle:** Proper session handling requires both\n  server-side utilities for components and layouts and client-side React\n  hooks for interactive UI — `useSession`, `SessionProvider`, and imperative\n  `signIn`/`signOut` helpers.\n- **Route Protection:** Many applications need fine-grained authorization\n  beyond simple authentication. This integration provides server-side `auth()`\n  utilities suitable for middleware and server components.\n\nThis integration, `@zitadel/next-auth`, aims to provide the flexibility to\nhandle such scenarios. It allows you to leverage the full OAuth provider ecosystem\nwhile maintaining Next.js best practices, ultimately leading to a more\neffective and less burdensome authentication implementation.\n\n## Installation\n\nInstall using NPM by using the following command:\n\n```sh\nnpm install @zitadel/next-auth\n```\n\n## Usage\n\nTo use this integration, call `NextAuth()` in a shared server module and\nexport the resulting handlers from your App Router catch-all route.\n\nYou'll need to configure it with your OAuth providers and options. The\nreturned `handlers`, `auth`, `signIn`, and `signOut` utilities are then\navailable throughout your application.\n\nFirst, create your auth configuration:\n\n```ts\n// src/lib/auth.ts\nimport { NextAuth } from '@zitadel/next-auth';\nimport Zitadel from '@auth/core/providers/zitadel';\n\nexport const { handlers, auth, signIn, signOut } = NextAuth({\n  providers: [\n    Zitadel({\n      clientId: process.env.ZITADEL_CLIENT_ID,\n      clientSecret: process.env.ZITADEL_CLIENT_SECRET,\n      issuer: process.env.ZITADEL_DOMAIN,\n    }),\n  ],\n  secret: process.env.AUTH_SECRET,\n  trustHost: true,\n});\n```\n\nThen wire up the route handler:\n\n```ts\n// src/app/api/auth/[...nextauth]/route.ts\nimport { handlers } from '@/lib/auth';\nexport const { GET, POST } = handlers;\n```\n\n#### Using the Authentication System\n\nThe integration provides several functions and hooks for handling\nauthentication:\n\n**Server Utilities:**\n\n- `auth(request)`: Retrieves the current OAuth session server-side\n- `signIn(provider?, options?)`: Server action for programmatic sign-in\n- `signOut(options?)`: Server action for programmatic sign-out\n\n**React Client Exports** (from `@zitadel/next-auth/react`):\n\n- `\u003cSessionProvider\u003e`: Context provider — wrap your root layout\n- `useSession()`: React hook returning `{ data, status, update }`\n- `signIn(provider?, options?)`: Client helper for sign-in\n- `signOut(options?)`: Client helper for sign-out\n- `getProviders()`: Fetch available providers\n- `getCsrfToken()`: Fetch the CSRF token\n\n**Basic Server Component Usage:**\n\n```tsx\n// src/app/page.tsx\nimport { auth } from '@/lib/auth';\n\nexport default async function Page() {\n  const session = await auth(/* request */);\n\n  return (\n    \u003cmain\u003e\n      {session ? (\n        \u003c\u003e\n          \u003cp\u003eWelcome, {session.user?.name}\u003c/p\u003e\n          \u003ca href=\"/api/auth/signout\"\u003eSign out\u003c/a\u003e\n        \u003c/\u003e\n      ) : (\n        \u003ca href=\"/api/auth/signin\"\u003eSign in\u003c/a\u003e\n      )}\n    \u003c/main\u003e\n  );\n}\n```\n\nPrefer client-side session state? Use the React hooks:\n\n```tsx\n// src/app/layout.tsx\nimport { SessionProvider } from '@zitadel/next-auth/react';\n\nexport default function RootLayout({ children }: { children: React.ReactNode }) {\n  return (\n    \u003chtml\u003e\n      \u003cbody\u003e\n        \u003cSessionProvider\u003e{children}\u003c/SessionProvider\u003e\n      \u003c/body\u003e\n    \u003c/html\u003e\n  );\n}\n```\n\n```tsx\n// src/components/UserMenu.tsx\n'use client';\n\nimport { useSession, signIn, signOut } from '@zitadel/next-auth/react';\n\nexport function UserMenu() {\n  const { data: session, status } = useSession();\n\n  if (status === 'loading') return \u003cp\u003eLoading…\u003c/p\u003e;\n\n  return session ? (\n    \u003c\u003e\n      \u003cp\u003eSigned in as {session.user?.email}\u003c/p\u003e\n      \u003cbutton onClick={() =\u003e signOut()}\u003eSign out\u003c/button\u003e\n    \u003c/\u003e\n  ) : (\n    \u003cbutton onClick={() =\u003e signIn('zitadel')}\u003eSign in\u003c/button\u003e\n  );\n}\n```\n\n##### Example: Advanced Configuration with Multiple Providers\n\nThis example shows how to use the integration with multiple OAuth\nproviders and custom session configuration:\n\n```ts\n// src/lib/auth.ts\nimport { NextAuth } from '@zitadel/next-auth';\nimport Zitadel from '@auth/core/providers/zitadel';\nimport Google from '@auth/core/providers/google';\n\nexport const { handlers, auth, signIn, signOut } = NextAuth({\n  providers: [\n    Zitadel({\n      clientId: process.env.ZITADEL_CLIENT_ID,\n      clientSecret: process.env.ZITADEL_CLIENT_SECRET,\n      issuer: process.env.ZITADEL_DOMAIN,\n    }),\n    Google({\n      clientId: process.env.GOOGLE_CLIENT_ID,\n      clientSecret: process.env.GOOGLE_CLIENT_SECRET,\n    }),\n  ],\n  secret: process.env.AUTH_SECRET,\n  trustHost: true,\n  session: {\n    strategy: 'jwt',\n    maxAge: 30 * 24 * 60 * 60, // 30 days\n  },\n  callbacks: {\n    async jwt({ token, user }) {\n      if (user) (token as any).roles = (user as any).roles;\n      return token;\n    },\n    async session({ session, token }) {\n      (session.user as any).roles = (token as any).roles as\n        | string[]\n        | undefined;\n      return session;\n    },\n  },\n});\n```\n\n## Known Issues\n\n- **App Router Required:** This integration targets the Next.js App Router.\n  Pages Router is not supported — use the official `next-auth` package for\n  Pages Router projects.\n- **Environment Configuration:** The integration relies on `AUTH_SECRET` and,\n  in many hosting scenarios, `AUTH_TRUST_HOST`. Ensure these are correctly set\n  in your environment for production.\n- **Callback URLs:** OAuth providers must be configured with the correct\n  callback URL: `[origin]/api/auth/callback/[provider]`.\n- **Type Augmentation:** If you attach additional properties (e.g., roles) to\n  the user session object, extend your app's types accordingly so consumers of\n  `session.user` remain type-safe.\n- **Redirect Semantics:** OAuth providers expect real browser navigations during\n  sign-in. The client helpers handle this for you — avoid manual `fetch()` calls\n  to provider endpoints unless you know you need credential/email flows.\n\n## Useful links\n\n- **[Next.js](https://nextjs.org/):** The framework this integration targets.\n\n## Contributing\n\nIf you have suggestions for how this integration could be improved, or\nwant to report a bug, open an issue — we'd love all and any contributions.\n\n## License\n\nApache-2.0\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzitadel%2Fnext-auth","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzitadel%2Fnext-auth","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzitadel%2Fnext-auth/lists"}