{"_id":"@automatiseerjouwproces/nextauth-azure-roles","_rev":"2-d6d461265404a968a889d58649fc78a2","name":"@automatiseerjouwproces/nextauth-azure-roles","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@automatiseerjouwproces/nextauth-azure-roles","version":"1.0.0","keywords":["nextauth","azure-ad","authentication","app-roles","rbac","next.js"],"author":{"name":"Automatiseer Jouw Proces","email":"info@automatiseerjouwproces.nl"},"license":"MIT","_id":"@automatiseerjouwproces/nextauth-azure-roles@1.0.0","maintainers":[{"name":"johanvandeglind","email":"johan@i-coso.nl"}],"homepage":"https://github.com/automatiseerjouwproces/nextauth-azure-roles#readme","bugs":{"url":"https://github.com/automatiseerjouwproces/nextauth-azure-roles/issues"},"dist":{"shasum":"035739338759a24d5c668afd4c23390453672a64","tarball":"https://registry.npmjs.org/@automatiseerjouwproces/nextauth-azure-roles/-/nextauth-azure-roles-1.0.0.tgz","fileCount":16,"integrity":"sha512-tqP1bRcGz652pavlmXK4IZVu+5IZNxmbwEU1CzBSfs+jlZwrBvDH/32FgXW01JtMJ8dN9mwaxFuurKRYkQrfEQ==","signatures":[{"sig":"MEYCIQD7hNdEmiMe4ZS6xIjrvoC+YZhzrZEidaxBu8YGnoy18gIhAOReY2lC7nAbWu7HuJY7hoeHcWK4ZbgxV7Pis89uL6cH","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":47832},"main":"build/index.js","types":"build/index.d.ts","scripts":{"test":"echo \"Error: no test specified\" && exit 1","build":"tsc","prepublishOnly":"npm run build"},"_npmUser":{"name":"johanvandeglind","email":"johan@i-coso.nl"},"repository":{"url":"git+https://github.com/automatiseerjouwproces/nextauth-azure-roles.git","type":"git"},"_npmVersion":"11.6.2","description":"NextAuth.js Azure AD provider with App Roles and role-based access control","directories":{},"_nodeVersion":"24.11.1","dependencies":{},"_hasShrinkwrap":false,"devDependencies":{"next":"^14.0.0","react":"^18.0.0","next-auth":"^4.24.0","react-dom":"^18.0.0","typescript":"^5.0.0","@types/node":"^20.0.0","@types/react":"^18.0.0","@prisma/client":"^5.0.0","@types/react-dom":"^18.0.0","@next-auth/prisma-adapter":"^1.0.0"},"peerDependencies":{"next":"^14.0.0 || ^15.0.0 || ^16.0.0","react":"^18.0.0 || ^19.0.0","next-auth":"^4.24.0","react-dom":"^18.0.0 || ^19.0.0","@prisma/client":"^5.0.0","@next-auth/prisma-adapter":"^1.0.0"},"peerDependenciesMeta":{"next":{"optional":false},"react":{"optional":false},"react-dom":{"optional":false}},"_npmOperationalInternal":{"tmp":"tmp/nextauth-azure-roles_1.0.0_1763210817110_0.22732175318600678","host":"s3://npm-registry-packages-npm-production"}}},"time":{"created":"2025-11-15T12:46:56.996Z","modified":"2025-11-28T12:04:51.780Z","1.0.0":"2025-11-15T12:46:57.331Z"},"bugs":{"url":"https://github.com/automatiseerjouwproces/nextauth-azure-roles/issues"},"author":{"name":"Automatiseer Jouw Proces","email":"info@automatiseerjouwproces.nl"},"license":"MIT","homepage":"https://github.com/automatiseerjouwproces/nextauth-azure-roles#readme","keywords":["nextauth","azure-ad","authentication","app-roles","rbac","next.js"],"repository":{"url":"git+https://github.com/automatiseerjouwproces/nextauth-azure-roles.git","type":"git"},"description":"NextAuth.js Azure AD provider with App Roles and role-based access control","maintainers":[{"email":"johan@i-coso.nl","name":"johanvandeglind"},{"email":"stan@automatiseerjouwproces.nl","name":"stanajp"}],"readme":"# NextAuth Azure Roles\r\n\r\nA reusable NextAuth.js provider for Azure AD authentication with App Roles support and automatic role-based access control.\r\n\r\n## Features\r\n\r\n- 🔐 Azure AD authentication with NextAuth.js\r\n- 👥 Automatic role mapping from Azure AD App Roles\r\n- 🎭 Role-based access control (RBAC)\r\n- 🔄 Automatic user creation and role synchronization\r\n- 📊 Support for both App Roles and Group-based roles\r\n- 🎨 Built-in UI components for authentication\r\n- 🛡️ Type-safe with TypeScript\r\n\r\n## Installation\r\n\r\n```bash\r\nnpm install @automatiseerjouwproces/nextauth-azure-roles\r\n# or\r\nyarn add @automatiseerjouwproces/nextauth-azure-roles\r\n# or\r\npnpm add @automatiseerjouwproces/nextauth-azure-roles\r\n```\r\n\r\n## Prerequisites\r\n\r\n- Next.js 14+\r\n- NextAuth.js 4.24+\r\n- Prisma ORM\r\n- Azure AD App Registration with App Roles configured\r\n\r\n## Setup\r\n\r\n### 1. Azure AD Configuration\r\n\r\nCreate an Azure AD App Registration and configure:\r\n\r\n1. **App Roles** in your Azure AD application manifest:\r\n```json\r\n{\r\n  \"appRoles\": [\r\n    {\r\n      \"allowedMemberTypes\": [\"User\"],\r\n      \"description\": \"Admin users can manage all features\",\r\n      \"displayName\": \"Admin\",\r\n      \"id\": \"ccbedf5e-1a0c-4bdc-8241-254025666d8c\",\r\n      \"isEnabled\": true,\r\n      \"value\": \"YourApp.Admin\"\r\n    },\r\n    {\r\n      \"allowedMemberTypes\": [\"User\"],\r\n      \"description\": \"Regular users\",\r\n      \"displayName\": \"User\",\r\n      \"id\": \"583fd075-fcae-4f12-b456-491643dc910d\",\r\n      \"isEnabled\": true,\r\n      \"value\": \"YourApp.User\"\r\n    }\r\n  ]\r\n}\r\n```\r\n\r\n2. **API Permissions**:\r\n   - `User.Read`\r\n   - `Directory.Read.All`\r\n   - `Application.Read.All`\r\n\r\n3. **Redirect URIs**:\r\n   - Add `https://yourdomain.com/api/auth/callback/azure-ad`\r\n\r\n### 2. Environment Variables\r\n\r\nAdd to your `.env.local`:\r\n\r\n```env\r\n# Azure AD\r\nAZURE_AD_CLIENT_ID=your-client-id\r\nAZURE_AD_CLIENT_SECRET=your-client-secret\r\nAZURE_AD_TENANT_ID=your-tenant-id\r\nAZURE_AD_SERVICE_PRINCIPAL_ID=your-service-principal-id\r\n\r\n# NextAuth\r\nNEXTAUTH_URL=https://yourdomain.com\r\nNEXTAUTH_SECRET=your-secret-key\r\n```\r\n\r\n### 3. Prisma Schema\r\n\r\nAdd the required models to your `schema.prisma`:\r\n\r\n```prisma\r\nmodel User {\r\n  id        String   @id @default(cuid())\r\n  email     String   @unique\r\n  name      String?\r\n  image     String?\r\n  role      String   @default(\"USER\") // ADMIN or USER\r\n  azureId   String?  @unique\r\n  createdAt DateTime @default(now())\r\n  updatedAt DateTime @updatedAt\r\n\r\n  accounts Account[]\r\n  sessions Session[]\r\n  \r\n  @@map(\"users\")\r\n}\r\n\r\n// Add NextAuth required models (Account, Session, VerificationToken)\r\n// See: https://next-auth.js.org/adapters/prisma\r\n```\r\n\r\n### 4. NextAuth Configuration\r\n\r\nCreate `src/app/api/auth/[...nextauth]/route.ts`:\r\n\r\n```typescript\r\nimport { createAzureADAuthHandler } from '@automatiseerjouwproces/nextauth-azure-roles'\r\nimport { PrismaClient } from '@prisma/client'\r\n\r\nconst prisma = new PrismaClient()\r\n\r\nconst handler = createAzureADAuthHandler({\r\n  prisma,\r\n  roleMapping: {\r\n    'YourApp.Admin': 'ADMIN',\r\n    'YourApp.User': 'USER'\r\n  },\r\n  pages: {\r\n    signIn: '/auth/signin',\r\n    error: '/auth/error'\r\n  }\r\n})\r\n\r\nexport { handler as GET, handler as POST }\r\n```\r\n\r\n### 5. Session Provider\r\n\r\nWrap your app with `SessionProvider`:\r\n\r\n```tsx\r\n// app/providers.tsx\r\n'use client'\r\n\r\nimport { SessionProvider } from 'next-auth/react'\r\n\r\nexport function Providers({ children }: { children: React.ReactNode }) {\r\n  return <SessionProvider>{children}</SessionProvider>\r\n}\r\n\r\n// app/layout.tsx\r\nimport { Providers } from './providers'\r\n\r\nexport default function RootLayout({ children }: { children: React.ReactNode }) {\r\n  return (\r\n    <html>\r\n      <body>\r\n        <Providers>{children}</Providers>\r\n      </body>\r\n    </html>\r\n  )\r\n}\r\n```\r\n\r\n## Usage\r\n\r\n### Auth Guard Component\r\n\r\nProtect routes with role-based access:\r\n\r\n```tsx\r\nimport { AuthGuard } from '@automatiseerjouwproces/nextauth-azure-roles'\r\n\r\nexport default function AdminPage() {\r\n  return (\r\n    <AuthGuard requiredRole=\"ADMIN\">\r\n      <div>Admin only content</div>\r\n    </AuthGuard>\r\n  )\r\n}\r\n```\r\n\r\n### Sign In Page\r\n\r\n```tsx\r\nimport { AzureSignInButton } from '@automatiseerjouwproces/nextauth-azure-roles'\r\n\r\nexport default function SignInPage() {\r\n  return (\r\n    <div>\r\n      <h1>Sign In</h1>\r\n      <AzureSignInButton />\r\n    </div>\r\n  )\r\n}\r\n```\r\n\r\n### Access User Session\r\n\r\n```tsx\r\n'use client'\r\n\r\nimport { useSession } from 'next-auth/react'\r\n\r\nexport default function Profile() {\r\n  const { data: session } = useSession()\r\n\r\n  return (\r\n    <div>\r\n      <p>Name: {session?.user?.name}</p>\r\n      <p>Email: {session?.user?.email}</p>\r\n      <p>Role: {session?.user?.role}</p>\r\n    </div>\r\n  )\r\n}\r\n```\r\n\r\n### Get User Initials\r\n\r\n```tsx\r\nimport { getInitialsFromName } from '@automatiseerjouwproces/nextauth-azure-roles'\r\n\r\nconst initials = getInitialsFromName('John Doe') // Returns 'JD'\r\n```\r\n\r\n## API Reference\r\n\r\n### `createAzureADAuthHandler(options)`\r\n\r\nCreates a NextAuth handler with Azure AD provider configured.\r\n\r\n**Options:**\r\n- `prisma` (required): Prisma client instance\r\n- `roleMapping` (required): Object mapping Azure AD roles to your app roles\r\n- `pages` (optional): Custom auth pages\r\n- `debug` (optional): Enable debug logging\r\n\r\n### `<AuthGuard>`\r\n\r\nComponent to protect routes based on user roles.\r\n\r\n**Props:**\r\n- `requiredRole` (optional): Required role to access the content\r\n- `fallback` (optional): Component to show when access is denied\r\n- `children` (required): Content to protect\r\n\r\n### `<AzureSignInButton>`\r\n\r\nPre-styled sign in button for Azure AD.\r\n\r\n**Props:**\r\n- `className` (optional): Additional CSS classes\r\n- `callbackUrl` (optional): Redirect URL after sign in\r\n\r\n### `getInitialsFromName(name)`\r\n\r\nUtility to extract initials from a full name.\r\n\r\n**Parameters:**\r\n- `name` (string): Full name\r\n\r\n**Returns:** Initials (e.g., \"JD\" for \"John Doe\")\r\n\r\n## Role Mapping\r\n\r\nThe package automatically maps Azure AD App Roles to your application roles:\r\n\r\n```typescript\r\nroleMapping: {\r\n  'YourApp.Admin': 'ADMIN',      // Azure AD role -> App role\r\n  'YourApp.User': 'USER',\r\n  'YourApp.Manager': 'MANAGER'\r\n}\r\n```\r\n\r\nUsers without any mapped roles will be denied access.\r\n\r\n## Type Safety\r\n\r\nThe package extends NextAuth types:\r\n\r\n```typescript\r\nimport type { Session } from 'next-auth'\r\n\r\n// Session type includes:\r\ninterface Session {\r\n  user: {\r\n    id: string\r\n    name?: string\r\n    email?: string\r\n    image?: string\r\n    role: string  // Added by this package\r\n  }\r\n}\r\n```\r\n\r\n## Troubleshooting\r\n\r\n### Role not detected\r\n\r\nEnsure:\r\n1. User is assigned the role in Azure AD\r\n2. Service Principal ID is correct in env variables\r\n3. API permissions are granted admin consent\r\n4. Role value matches your `roleMapping` configuration\r\n\r\n### Session not persisting\r\n\r\nCheck:\r\n1. `NEXTAUTH_URL` matches your domain\r\n2. `NEXTAUTH_SECRET` is set\r\n3. Cookies are not blocked\r\n4. HTTPS is used in production\r\n\r\n## Examples\r\n\r\nSee the `/examples` directory for complete implementations:\r\n- Basic setup\r\n- Multi-tenant configuration\r\n- Custom role logic\r\n- Group-based roles\r\n\r\n## Contributing\r\n\r\nContributions are welcome! Please read our [Contributing Guide](CONTRIBUTING.md).\r\n\r\n## License\r\n\r\nMIT © Automatiseer Jouw Proces\r\n\r\n## Support\r\n\r\n- 📧 Email: info@automatiseerjouwproces.nl\r\n- 🐛 Issues: [GitHub Issues](https://github.com/automatiseerjouwproces/nextauth-azure-roles/issues)\r\n- 📖 Docs: [Full Documentation](https://github.com/automatiseerjouwproces/nextauth-azure-roles#readme)\r\n","readmeFilename":"README.md"}