\n\n## Description\n\n[Nest](https://github.com/nestjs/nest) framework Module for validating Azure AD JWT Tokens. \nThe Module exports an [AzureTokenValidationService](./src/azure-token-validation/azure-token-validation.service.ts) for validating tokens\nas well as a guard you might consider using [AzureActiveDirectoryGuard](./src/guards/zure-active-directory.guard.ts). \nNote: The exported guard expects the jwt(json web token) in an authtoken header (in Aws APIGateway we don't like to mess with the Authorization header).\n\n## Installation\n\n```bash\n$ npm install --save nest-azure-ad-jwt-validator\n```\n\n## Usage\n\n1. Import the module globally in your app module.\n2. Add the Exported Guard as a global guard or use the exported service\n\n```typescript\nimport {\n AzureActiveDirectoryGuard,\n NestAzureAdJwtValidatorModule,\n} from 'nest-azure-ad-jwt-validator';\nimport { APP_GUARD } from '@nestjs/core';\nimport { AppController } from './app.controller';\nimport { AppService } from './app.service';\nimport { Module } from '@nestjs/common';\n@Module({\n imports: [\n NestAzureAdJwtValidatorModule.forRoot({\n apps: [\n {\n tenantId: '63fca94a-4979-4ee1-b9cc-54169f68ccbf',\n audienceId: '6747e462-323d-4fb7-b1e0-ef99531fe611',\n },\n ],\n serviceTokens: ['random-string-generated-by-you'], // option - used to allow service-to-service communication, ala AWS x-api-key\n enableDebugLogs: true, // optional - false by default\n tokenHeader: 'authorization' // The Header in which the jwt appears defaults to 'authtoken' by default.\n }),\n ],\n controllers: [AppController],\n providers: [\n AppService,\n {\n provide: APP_GUARD,\n useClass: AzureActiveDirectoryGuard,\n },\n ],\n})\nexport class AppModule {}\n```\n\n## Azure Roles\n\n1.\n\nTo use azure roles go to portal.azure.com -> search for App Registrations -> find your app -> edit manifest\n\nAdd your roles to the manifest, the id's should be different Guids:\n\n```json\n{\n\t\"id\": \"xxxx-xxxx-xx-xxxx-xxxxxxx\",\n\t...\n\t\"appRoles\": [\n\t\t{\n\t\t\t\"allowedMemberTypes\": [\n\t\t\t\t\"User\"\n\t\t\t],\n\t\t\t\"description\": \"Admin Users\",\n\t\t\t\"displayName\": \"Admin\",\n\t\t\t\"id\": \"xxxxx-xxxx-xxx-xxx-xxxxxx\",\n\t\t\t\"isEnabled\": true,\n\t\t\t\"lang\": null,\n\t\t\t\"origin\": \"Application\",\n\t\t\t\"value\": \"Admin\"\n\t\t},\n\t\t{\n\t\t\t\"allowedMemberTypes\": [\n\t\t\t\t\"User\"\n\t\t\t],\n\t\t\t\"description\": \"Finance Users have the ability to update finance data.\",\n\t\t\t\"displayName\": \"FinanceUsers\",\n\t\t\t\"id\": \"xxxxxx-xxx-xxxx-xxxx-xxxxxx2\",\n\t\t\t\"isEnabled\": true,\n\t\t\t\"lang\": null,\n\t\t\t\"origin\": \"Application\",\n\t\t\t\"value\": \"FinanceUsers\"\n },\n ...\n\t],\n\t\"oauth2AllowUrlPathMatching\": false,\n\t...\n}\n```\n\n2.\n\nNext go to Enterprise Applications -> search for your app and click on it for details -> Users and Groups (or Assign Users and Groups) -> Add User -> Here you pick azure ad users or groups and put them into the App Roles\n\n3.\n\nNow that Azure roles are setup and returned in the token, roles can be added to the application under the routes such as\nappmodule.ts\n\n```ts\nimport {\n AzureActiveDirectoryGuard,\n NestAzureAdJwtValidatorModule,\n} from 'nest-azure-ad-jwt-validator';\nimport { APP_GUARD } from '@nestjs/core';\nimport { AppController } from './app.controller';\nimport { AppService } from './app.service';\nimport { Module } from '@nestjs/common';\n@Module({\n imports: [\n NestAzureAdJwtValidatorModule.forRoot({\n apps: [\n {\n tenantId: '63fca94a-4979-4ee1-b9cc-54169f68ccbf',\n audienceId: '6747e462-323d-4fb7-b1e0-ef99531fe611',\n },\n ],\n serviceTokens: ['random-string-generated-by-you'], // option - used to allow service-to-service communication, ala AWS x-api-key\n enableDebugLogs: true, // optional - false by default\n }),\n ],\n controllers: [AppController],\n providers: [AppService],\n})\nexport class AppModule {}\n```\n\ncontroller.ts\n\n```ts\nimport { Controller, Get } from '@nestjs/common';\nimport { AzureActiveDirectoryGuard } from 'nest-azure-ad-jwt-validator';\nimport { Roles } from 'nest-azure-ad-jwt-validator';\n@UseGuards(AzureActiveDirectoryGuard)\n@Controller('test')\nexport class TestController {\n @Get('')\n @Roles('admin', 'finance')\n get getTest() {\n return 'success';\n }\n}\n```\n\nOr if you do not wish to add the guard globally to all endpoints you can specify specific controllers to have the guard such as:\n\n```ts\nimport { Controller, Get } from '@nestjs/common';\nimport { Roles } from 'nest-azure-ad-jwt-validator';\n@Controller('test')\nexport class TestController {\n @Get('')\n @Roles('admin', 'finance')\n get getTest() {\n return 'success';\n }\n}\n```\n\nNote: Azure Roles have not been setup an a `@Controller` level that will require a code change to `context.getHandler()` -> `context.getClass()`\n\nNote: If the role does not exist on the role, no roles are checked and everything proceeds as if there are no roles.\n\nNote: If you are assigning users to appRoles via Azure Groups then you need to change the manifest\n\n```json\n\"groupMembershipClaims\": null,\n```\n\nTo\n\n```json\n\"groupMembershipClaims\": \"All\", # or “SecurityGroups”\n```\n\nIn addition you cannot nest security groups, so [you cannot take an existing group and add it to the group assigned to the appRole](https://stackoverflow.com/questions/27633510/assign-nested-group-to-role-in-azure-ad-applications-users-and-groups).\n\nExample:\nappRole: 'Admin'\nUser: 'test@domain.com'\nAD Groups: 'AD-TEST-UI-UG'\n\nEither add ADGroups to the appRole or add the user to the appRole. You cannot add the AD Group 'AD-TEST-UI-UG' to another AD Group superset ('AD-TEST-UI-SUPERSET-UG') group. 'AD-TEST-UI-SUPERSET-UG' would never show roles.\n\nAlso:\n[Vote for this Feature](https://feedback.azure.com/forums/169401-azure-active-directory/suggestions/)15718164-add-support-for-nested-groups-in-azure-ad-app-acc\n[In the Important section](https://docs.microsoft.com/en-us/azure/active-directory/users-groups-roles/groups-saasapps)\n\n## Commit Messages\n\nCommit messages should follow the [semantic commit message by angular(https://nitayneeman.com/posts/understanding-semantic-commit-messages-using-git-and-angular/)\n\n```bash\ngit commit -am \"fix(roles): add service token except to roles authorization\" -m \"The roles authorization should not run when the service now token is used because the service token is used when the application has no auth mechanism. Add warning message if user's roles does not match expected role\" -m \"PR Close #13\"\n```\n\n## Test\n\n```bash\n# unit tests\n$ npm run test\n\n# test coverage\n$ npm run test:cov\n```\n\n## Stay in touch\n\n- Author - [Benjamin Main](mailto:bmain@lumeris.com)\n\n## License\n\nnest-azure-ad-jwt-validator is [MIT licensed](LICENSE).\n","readmeFilename":"README.md"}
![\"Azure](\"./azure-active-directory.svg\")
\n