nestjs-entra

A zero-boilerplate NestJS wrapper for server-to-server authentication with Azure AD using the Client Credentials Flow.

features

• Zero-Boilerplate Auth Client: Exports a pre-configured AxiosInstance (ENTRA_HTTP_CLIENT) that automatically injects valid Access Tokens into requests.
• Robust Token Management: Wraps @azure/msal-node to handle token acquisition, caching, and refreshing automatically.
• Dynamic Configuration: Global module with forRootAsync support for injecting secrets via ConfigService.
• Type Safety: strict TypeScript typing for all configurations.

installation

npm install nestjs-entra @azure/msal-node
npm install --save-peer @nestjs/common @nestjs/core @nestjs/config rxjs axios

usage

1. Register the Module

Import EntraModule in your AppModule using forRootAsync.

import { Module } from '@nestjs/common';
import { ConfigModule, ConfigService } from '@nestjs/config';
import { EntraModule } from 'nestjs-entra';

@Module({
  imports: [
    ConfigModule.forRoot({ isGlobal: true }),
    EntraModule.forRootAsync({
      imports: [ConfigModule],
      inject: [ConfigService],
      useFactory: (configService: ConfigService) => ({
        msalConfig: {
          auth: {
            clientId: configService.get('AZURE_CLIENT_ID'),
            clientSecret: configService.get('AZURE_CLIENT_SECRET'),
            authority: `https://login.microsoftonline.com/${configService.get('AZURE_TENANT_ID')}`,
          },
        },
        // Optional: Override default scopes
        // defaultScopes: ['https://graph.microsoft.com/.default'],
      }),
    }),
  ],
})
export class AppModule {}

2. Inject the Authenticated Client

Inject ENTRA_HTTP_CLIENT into your services. This is a standard AxiosInstance that automatically adds the Authorization: Bearer <token> header to every request.

import { Injectable, Inject } from '@nestjs/common';
import { AxiosInstance } from 'axios';
import { ENTRA_HTTP_CLIENT } from 'nestjs-entra';

@Injectable()
export class AppService {
  constructor(
    @Inject(ENTRA_HTTP_CLIENT) private readonly httpClient: AxiosInstance,
  ) {}

  async getUsers() {
    // No need to manually handle tokens!
    const response = await this.httpClient.get('https://graph.microsoft.com/v1.0/users');
    return response.data;
  }
}

3. Advanced Usage: accessing EntraService directly

If you need raw tokens or the full authentication result (e.g. for refresh tokens where applicable), you can inject EntraService.

import { Injectable } from '@nestjs/common';
import { EntraService } from 'nestjs-entra';

@Injectable()
export class TokenService {
  constructor(private readonly entraService: EntraService) {}

  async getRawToken() {
    // Get just the access token string
    const token = await this.entraService.getAccessToken();
    return token;
  }

  async getFullResult() {
    // Get full AuthenticationResult (including expiresOn, extExpiresOn, etc)
    const result = await this.entraService.getAuthResult();
    console.log(result.accessToken);
    console.log(result.expiresOn);
    return result;
  }
}

license

MIT