{"id":45908392,"url":"https://github.com/zitadel/nestjs-auth","last_synced_at":"2026-02-28T04:27:10.957Z","repository":{"id":308507520,"uuid":"1032005165","full_name":"zitadel/nestjs-auth","owner":"zitadel","description":"A comprehensive Auth.js integration for NestJS applications with TypeScript support, framework-agnostic HTTP adapters, and role-based access control\"","archived":false,"fork":false,"pushed_at":"2026-02-23T20:34:51.000Z","size":1054,"stargazers_count":2,"open_issues_count":2,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-24T02:58:22.964Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/@mridang/nestjs-auth","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","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":"2025-08-04T16:52:56.000Z","updated_at":"2026-02-19T22:35:33.000Z","dependencies_parsed_at":"2025-08-06T10:31:30.029Z","dependency_job_id":"9b36e8d9-ecfa-4908-b4bd-e1ac8ef26294","html_url":"https://github.com/zitadel/nestjs-auth","commit_stats":null,"previous_names":["mridang/nestjs-auth","zitadel/nestjs-auth"],"tags_count":11,"template":false,"template_full_name":null,"purl":"pkg:github/zitadel/nestjs-auth","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zitadel%2Fnestjs-auth","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zitadel%2Fnestjs-auth/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zitadel%2Fnestjs-auth/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zitadel%2Fnestjs-auth/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zitadel","download_url":"https://codeload.github.com/zitadel/nestjs-auth/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zitadel%2Fnestjs-auth/sbom","scorecard":{"id":1242955,"data":{"date":"2026-02-05T07:27:41Z","repo":{"name":"github.com/zitadel/nestjs-auth","commit":"960f2ee21b05b4b3e3b5f37fe3fafca1e5d1b91c"},"scorecard":{"version":"v5.1.1","commit":"cd152cb6742c5b8f2f3d2b5193b41d9c50905198"},"score":5.2,"checks":[{"name":"Code-Review","score":0,"reason":"Found 0/26 approved changesets -- score normalized to 0","details":null,"documentation":{"short":"Determines if the project requires human code review before pull requests (aka merge requests) are merged.","url":"https://github.com/ossf/scorecard/blob/cd152cb6742c5b8f2f3d2b5193b41d9c50905198/docs/checks.md#code-review"}},{"name":"Maintained","score":7,"reason":"9 commit(s) and 0 issue activity found in the last 90 days -- score normalized to 7","details":null,"documentation":{"short":"Determines if the project is \"actively maintained\".","url":"https://github.com/ossf/scorecard/blob/cd152cb6742c5b8f2f3d2b5193b41d9c50905198/docs/checks.md#maintained"}},{"name":"Binary-Artifacts","score":10,"reason":"no binaries found in the repo","details":null,"documentation":{"short":"Determines if the project has generated executable (binary) artifacts in the source repository.","url":"https://github.com/ossf/scorecard/blob/cd152cb6742c5b8f2f3d2b5193b41d9c50905198/docs/checks.md#binary-artifacts"}},{"name":"Dependency-Update-Tool","score":10,"reason":"update tool detected","details":["Info: detected update tool: Dependabot: .github/dependabot.yml:1"],"documentation":{"short":"Determines if the project uses a dependency update tool.","url":"https://github.com/ossf/scorecard/blob/cd152cb6742c5b8f2f3d2b5193b41d9c50905198/docs/checks.md#dependency-update-tool"}},{"name":"Dangerous-Workflow","score":10,"reason":"no dangerous workflow patterns detected","details":null,"documentation":{"short":"Determines if the project's GitHub Action workflows avoid dangerous patterns.","url":"https://github.com/ossf/scorecard/blob/cd152cb6742c5b8f2f3d2b5193b41d9c50905198/docs/checks.md#dangerous-workflow"}},{"name":"Packaging","score":-1,"reason":"packaging workflow not detected","details":["Warn: no GitHub/GitLab publishing workflow detected."],"documentation":{"short":"Determines if the project is published as a package that others can easily download, install, easily update, and uninstall.","url":"https://github.com/ossf/scorecard/blob/cd152cb6742c5b8f2f3d2b5193b41d9c50905198/docs/checks.md#packaging"}},{"name":"Token-Permissions","score":0,"reason":"detected GitHub workflow tokens with excessive permissions","details":["Info: jobLevel 'contents' permission set to 'read': .github/workflows/commitlint.yml:16","Info: jobLevel 'pull-requests' permission set to 'read': .github/workflows/commitlint.yml:17","Warn: jobLevel 'contents' permission set to 'write': .github/workflows/linting.yml:24","Info: jobLevel 'contents' permission set to 'read': .github/workflows/scorecard.yml:16","Info: jobLevel 'contents' permission set to 'read': .github/workflows/unused.yml:16","Info: jobLevel 'pull-requests' permission set to 'read': .github/workflows/unused.yml:17","Info: topLevel 'contents' permission set to 'read': .github/workflows/commitlint.yml:11","Info: topLevel 'contents' permission set to 'read': .github/workflows/depcheck.yml:7","Info: topLevel 'contents' permission set to 'read': .github/workflows/linting.yml:19","Warn: topLevel 'contents' permission set to 'write': .github/workflows/pipeline.yml:7","Info: topLevel 'actions' permission set to 'read': .github/workflows/pipeline.yml:8","Warn: topLevel 'checks' permission set to 'write': .github/workflows/pipeline.yml:9","Warn: no topLevel permission defined: .github/workflows/qodana.yml:1","Warn: topLevel 'packages' permission set to 'write': .github/workflows/release.yml:11","Info: topLevel 'checks' permission set to 'read': .github/workflows/release.yml:13","Warn: topLevel 'contents' permission set to 'write': .github/workflows/release.yml:10","Info: topLevel 'contents' permission set to 'read': .github/workflows/scorecard.yml:9","Warn: no topLevel permission defined: .github/workflows/test.yml:1","Info: topLevel 'contents' permission set to 'read': .github/workflows/typecheck.yml:15","Info: topLevel 'contents' permission set to 'read': .github/workflows/unused.yml:11"],"documentation":{"short":"Determines if the project's workflows follow the principle of least privilege.","url":"https://github.com/ossf/scorecard/blob/cd152cb6742c5b8f2f3d2b5193b41d9c50905198/docs/checks.md#token-permissions"}},{"name":"Pinned-Dependencies","score":8,"reason":"dependency not pinned by hash detected -- score normalized to 8","details":["Warn: third-party GitHubAction not pinned by hash: .github/workflows/commitlint.yml:34: update your workflow using https://app.stepsecurity.io/secureworkflow/zitadel/nestjs-auth/commitlint.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/linting.yml:40: update your workflow using https://app.stepsecurity.io/secureworkflow/zitadel/nestjs-auth/linting.yml/main?enable=pin","Warn: third-party GitHubAction not pinned by hash: .github/workflows/release.yml:41: update your workflow using https://app.stepsecurity.io/secureworkflow/zitadel/nestjs-auth/release.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/test.yml:31: update your workflow using https://app.stepsecurity.io/secureworkflow/zitadel/nestjs-auth/test.yml/main?enable=pin","Warn: third-party GitHubAction not pinned by hash: .github/workflows/test.yml:43: update your workflow using https://app.stepsecurity.io/secureworkflow/zitadel/nestjs-auth/test.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/typecheck.yml:34: update your workflow using https://app.stepsecurity.io/secureworkflow/zitadel/nestjs-auth/typecheck.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/unused.yml:33: update your workflow using https://app.stepsecurity.io/secureworkflow/zitadel/nestjs-auth/unused.yml/main?enable=pin","Warn: third-party GitHubAction not pinned by hash: .github/workflows/unused.yml:42: update your workflow using https://app.stepsecurity.io/secureworkflow/zitadel/nestjs-auth/unused.yml/main?enable=pin","Info:  15 out of  19 GitHub-owned GitHubAction dependencies pinned","Info:  14 out of  18 third-party GitHubAction dependencies pinned","Info:   4 out of   4 npmCommand dependencies pinned"],"documentation":{"short":"Determines if the project has declared and pinned the dependencies of its build process.","url":"https://github.com/ossf/scorecard/blob/cd152cb6742c5b8f2f3d2b5193b41d9c50905198/docs/checks.md#pinned-dependencies"}},{"name":"CII-Best-Practices","score":0,"reason":"no effort to earn an OpenSSF best practices badge detected","details":null,"documentation":{"short":"Determines if the project has an OpenSSF (formerly CII) Best Practices Badge.","url":"https://github.com/ossf/scorecard/blob/cd152cb6742c5b8f2f3d2b5193b41d9c50905198/docs/checks.md#cii-best-practices"}},{"name":"Signed-Releases","score":0,"reason":"Project has not signed or included provenance with any releases.","details":["Warn: release artifact v1.5.0 not signed: https://api.github.com/repos/zitadel/nestjs-auth/releases/283217013","Warn: release artifact v1.4.0 not signed: https://api.github.com/repos/zitadel/nestjs-auth/releases/258081100","Warn: release artifact v1.3.0 not signed: https://api.github.com/repos/zitadel/nestjs-auth/releases/240159432","Warn: release artifact v1.2.1 not signed: https://api.github.com/repos/zitadel/nestjs-auth/releases/239940637","Warn: release artifact v1.2.0 not signed: https://api.github.com/repos/zitadel/nestjs-auth/releases/238891325","Warn: release artifact v1.5.0 does not have provenance: https://api.github.com/repos/zitadel/nestjs-auth/releases/283217013","Warn: release artifact v1.4.0 does not have provenance: https://api.github.com/repos/zitadel/nestjs-auth/releases/258081100","Warn: release artifact v1.3.0 does not have provenance: https://api.github.com/repos/zitadel/nestjs-auth/releases/240159432","Warn: release artifact v1.2.1 does not have provenance: https://api.github.com/repos/zitadel/nestjs-auth/releases/239940637","Warn: release artifact v1.2.0 does not have provenance: https://api.github.com/repos/zitadel/nestjs-auth/releases/238891325"],"documentation":{"short":"Determines if the project cryptographically signs release artifacts.","url":"https://github.com/ossf/scorecard/blob/cd152cb6742c5b8f2f3d2b5193b41d9c50905198/docs/checks.md#signed-releases"}},{"name":"SAST","score":10,"reason":"SAST tool detected","details":["Info: SAST configuration detected: Qodana","Warn: 0 commits out of 5 are checked with a SAST tool"],"documentation":{"short":"Determines if the project uses static code analysis.","url":"https://github.com/ossf/scorecard/blob/cd152cb6742c5b8f2f3d2b5193b41d9c50905198/docs/checks.md#sast"}},{"name":"License","score":10,"reason":"license file detected","details":["Info: project has a license file: LICENSE:0","Info: FSF or OSI recognized license: Apache License 2.0: LICENSE:0"],"documentation":{"short":"Determines if the project has defined a license.","url":"https://github.com/ossf/scorecard/blob/cd152cb6742c5b8f2f3d2b5193b41d9c50905198/docs/checks.md#license"}},{"name":"Fuzzing","score":0,"reason":"project is not fuzzed","details":["Warn: no fuzzer integrations found"],"documentation":{"short":"Determines if the project uses fuzzing.","url":"https://github.com/ossf/scorecard/blob/cd152cb6742c5b8f2f3d2b5193b41d9c50905198/docs/checks.md#fuzzing"}},{"name":"Vulnerabilities","score":10,"reason":"0 existing vulnerabilities detected","details":null,"documentation":{"short":"Determines if the project has open, known unfixed vulnerabilities.","url":"https://github.com/ossf/scorecard/blob/cd152cb6742c5b8f2f3d2b5193b41d9c50905198/docs/checks.md#vulnerabilities"}},{"name":"Branch-Protection","score":0,"reason":"branch protection not enabled on development/release branches","details":["Warn: branch protection not enabled for branch 'main'"],"documentation":{"short":"Determines if the default and release branches are protected with GitHub's branch protection settings.","url":"https://github.com/ossf/scorecard/blob/cd152cb6742c5b8f2f3d2b5193b41d9c50905198/docs/checks.md#branch-protection"}},{"name":"Security-Policy","score":0,"reason":"security policy file not detected","details":["Warn: no security policy file detected","Warn: no security file to analyze","Warn: no security file to analyze","Warn: no security file to analyze"],"documentation":{"short":"Determines if the project has published a security policy.","url":"https://github.com/ossf/scorecard/blob/cd152cb6742c5b8f2f3d2b5193b41d9c50905198/docs/checks.md#security-policy"}},{"name":"CI-Tests","score":10,"reason":"4 out of 4 merged PRs checked by a CI test -- score normalized to 10","details":null,"documentation":{"short":"Determines if the project runs tests before pull requests are merged.","url":"https://github.com/ossf/scorecard/blob/cd152cb6742c5b8f2f3d2b5193b41d9c50905198/docs/checks.md#ci-tests"}},{"name":"Contributors","score":3,"reason":"project has 1 contributing companies or organizations -- score normalized to 3","details":["Info: found contributions from: semantic-release"],"documentation":{"short":"Determines if the project has a set of contributors from multiple organizations (e.g., companies).","url":"https://github.com/ossf/scorecard/blob/cd152cb6742c5b8f2f3d2b5193b41d9c50905198/docs/checks.md#contributors"}}]},"last_synced_at":"2026-02-05T08:32:04.808Z","repository_id":308507520,"created_at":"2026-02-05T08:32:04.809Z","updated_at":"2026-02-05T08:32:04.809Z"},"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29924720,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-27T19:37:42.220Z","status":"online","status_checked_at":"2026-02-28T02:00:07.010Z","response_time":90,"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":[],"created_at":"2026-02-28T04:27:10.410Z","updated_at":"2026-02-28T04:27:10.951Z","avatar_url":"https://github.com/zitadel.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# NestJS Auth.js\n\nA [NestJS](https://nestjs.com/) integration for [Auth.js](https://authjs.dev/)\nthat provides seamless authentication with multiple providers, session\nmanagement, and role-based access control using NestJS patterns.\n\nThis integration brings the power and flexibility of Auth.js to NestJS\napplications with full TypeScript support, framework-agnostic HTTP adapters\n(Express/Fastify), and NestJS-native patterns including guards, decorators,\nand dependency injection.\n\n### Why?\n\nModern web applications require robust, secure, and flexible authentication\nsystems. While Auth.js provides excellent authentication capabilities,\nintegrating it with NestJS applications requires careful consideration of\nframework patterns, dependency injection, and TypeScript integration.\n\nHowever, a direct integration isn't always straightforward. Different types\nof applications or deployment scenarios might warrant different approaches:\n\n- **Framework Integration:** Auth.js operates at the HTTP level, while NestJS\n  uses decorators, guards, and dependency injection. A proper integration\n  should bridge this gap by providing NestJS-native patterns for\n  authentication and authorization while maintaining the full Auth.js\n  ecosystem compatibility.\n- **HTTP Adapter Abstraction:** NestJS supports multiple HTTP frameworks\n  (Express, Fastify). Teams need a unified approach that works seamlessly\n  with both, allowing framework switching without changing authentication\n  code.\n- **Session and Request Lifecycle:** Proper session handling in NestJS\n  requires integration with the request lifecycle, guards, and decorators.\n  Manual integration often leads to inconsistent session management or\n  improper request handling across different routes.\n- **Role-Based Access Control:** Many applications need fine-grained\n  authorization beyond simple authentication. This requires seamless\n  integration between Auth.js user data and NestJS authorization patterns.\n\nThis integration, `@zitadel/nestjs-auth`, aims to provide the flexibility to\nhandle such scenarios. It allows you to leverage the full Auth.js ecosystem\nwhile maintaining NestJS 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/nestjs-auth @auth/core\n```\n\n## Usage\n\nTo use this integration, add `AuthJsModule` to your NestJS application\nmodule. The module provides authentication infrastructure with configurable\nguards, middleware, and decorators.\n\nYou'll need to configure it with your Auth.js providers and options. The\nintegration will then be available throughout your application via NestJS\ndependency injection.\n\nFirst, add the module to your `AppModule`:\n\n```typescript\nimport { Module } from '@nestjs/common';\nimport { AuthJsModule } from '@zitadel/nestjs-auth';\nimport GoogleProvider from '@auth/core/providers/google';\n\n@Module({\n  imports: [\n    AuthJsModule.register({\n      providers: [\n        GoogleProvider({\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    }),\n  ],\n})\nexport class AppModule {}\n```\n\n#### Using the Authentication System\n\nThe integration provides several decorators and guards for handling\nauthentication:\n\n**Decorators and Guards:**\n\n- `@Public()`: Marks routes as publicly accessible, bypassing authentication\n- `@RequireRoles()`: Restricts access to users with specific roles\n- `@AuthSession()`: Injects the current Auth.js session into route handlers\n- `AuthJsGuard`: Global guard for authentication (applied by default)\n- `RolesGuard`: Global guard for role-based authorization\n\n**Basic Usage:**\n\n```typescript\nimport { Controller, Get } from '@nestjs/common';\nimport { AuthSession, Public, RequireRoles } from '@zitadel/nestjs-auth';\nimport type { Session } from '@auth/core/types';\n\n@Controller('api')\nexport class ApiController {\n  @Get('public')\n  @Public() // Bypass authentication\n  getPublicData() {\n    return { message: 'Public endpoint' };\n  }\n\n  @Get('profile')\n  // Authenticated by default (global guard)\n  getProfile(@AuthSession() session: Session | null) {\n    return {\n      user: session?.user,\n      expires: session?.expires,\n    };\n  }\n\n  @Get('admin')\n  @RequireRoles('admin') // Role-based access\n  getAdminData(@AuthSession() session: Session | null) {\n    return { adminData: true };\n  }\n}\n```\n\n##### Example: Advanced Configuration with Multiple Providers\n\nThis example shows how to use async registration with multiple Auth.js\nproviders and custom session configuration:\n\n```typescript\nimport { Module } from '@nestjs/common';\nimport { ConfigModule, ConfigService } from '@nestjs/config';\nimport { AuthJsModule } from '@zitadel/nestjs-auth';\nimport GoogleProvider from '@auth/core/providers/google';\nimport GitHubProvider from '@auth/core/providers/github';\n\n@Module({\n  imports: [\n    ConfigModule.forRoot(),\n    AuthJsModule.registerAsync(\n      {\n        imports: [ConfigModule],\n        useFactory: (configService: ConfigService) =\u003e ({\n          providers: [\n            GoogleProvider({\n              clientId: configService.get('GOOGLE_CLIENT_ID'),\n              clientSecret: configService.get('GOOGLE_CLIENT_SECRET'),\n            }),\n            GitHubProvider({\n              clientId: configService.get('GITHUB_CLIENT_ID'),\n              clientSecret: configService.get('GITHUB_CLIENT_SECRET'),\n            }),\n          ],\n          secret: configService.get('AUTH_SECRET'),\n          trustHost: true,\n          session: {\n            strategy: 'jwt',\n            maxAge: 30 * 24 * 60 * 60, // 30 days\n          },\n          callbacks: {\n            jwt: async ({ token, user }) =\u003e {\n              if (user) {\n                token.roles = user.roles;\n              }\n              return token;\n            },\n            session: async ({ session, token }) =\u003e {\n              session.user.roles = token.roles as string[];\n              return session;\n            },\n          },\n        }),\n        inject: [ConfigService],\n      },\n      {\n        globalGuard: true, // Require auth by default\n        rolesGuard: true, // Enable role-based access\n        basePath: '/auth', // Auth routes base path\n      },\n    ),\n  ],\n})\nexport class AppModule {}\n```\n\n## Known Issues\n\n- **HTTP Adapter Dependencies:** The integration dynamically detects Express\n  or Fastify adapters based on the underlying NestJS HTTP adapter. Other\n  custom HTTP adapters may require additional adapter implementations.\n- **Session Storage Configuration:** The integration relies on Auth.js\n  session handling mechanisms. When configuring custom session storage or\n  database adapters, ensure they are properly configured in the Auth.js\n  options passed to the module.\n- **Role-Based Authorization (`RolesGuard`):** The roles guard expects user\n  roles to be available in the `session.user.roles` array. Ensure your\n  Auth.js callbacks (particularly `jwt` and `session` callbacks) properly\n  populate this field from your authentication provider or database.\n- **Type Augmentation:** The integration automatically augments Express and\n  Fastify request types with session properties. For custom user properties\n  beyond the default Auth.js user schema, you'll need to extend the Auth.js\n  types in your application.\n\n## Useful links\n\n- **[Auth.js](https://authjs.dev/):** The authentication library that this\n  integration is built upon.\n- **[NestJS](https://nestjs.com/):** The Node.js framework this integration\n  is designed for.\n- **[Auth.js Providers](https://authjs.dev/getting-started/providers):**\n  Complete list of supported authentication providers.\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\ncontributions.\n\n## License\n\nApache License 2.0 © 2024 Mridang Agarwalla\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzitadel%2Fnestjs-auth","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzitadel%2Fnestjs-auth","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzitadel%2Fnestjs-auth/lists"}