Bibliothèque Azure Identity pour TypeScript

Bibliothèque d'authentification pour les clients Azure SDK utilisant Microsoft Entra ID.

Installation

npm install @azure/identity

# Pour le support des identifiants Visual Studio Code
npm install @azure/identity-vscode

Variables d'environnement

Service Principal (Secret)

AZURE_TENANT_ID=<tenant-id>
AZURE_CLIENT_ID=<client-id>
AZURE_CLIENT_SECRET=<client-secret>
AZURE_TOKEN_CREDENTIALS=prod # Requis uniquement si DefaultAzureCredential est utilisé en production

Service Principal (Certificat)

AZURE_TENANT_ID=<tenant-id>
AZURE_CLIENT_ID=<client-id>
AZURE_CLIENT_CERTIFICATE_PATH=/path/to/cert.pem
AZURE_CLIENT_CERTIFICATE_PASSWORD=<optional-password>

Workload Identity (Kubernetes)

AZURE_TENANT_ID=<tenant-id>
AZURE_CLIENT_ID=<client-id>
AZURE_FEDERATED_TOKEN_FILE=/var/run/secrets/tokens/azure-identity

DefaultAzureCredential (Recommandé pour le développement local)

import { DefaultAzureCredential, ManagedIdentityCredential } from "@azure/identity";

// Dev local : DefaultAzureCredential. Production : définir AZURE_TOKEN_CREDENTIALS=prod ou AZURE_TOKEN_CREDENTIALS=<specific_credential>
const credential = new DefaultAzureCredential({requiredEnvVars: ["AZURE_TOKEN_CREDENTIALS"]});
// Ou utiliser une identifiant spécifique directement en production :
// Voir https://learn.microsoft.com/javascript/api/overview/azure/identity-readme?view=azure-node-latest#credential-classes
// const credential = new ManagedIdentityCredential();

// Utiliser avec n'importe quel client Azure SDK
import { BlobServiceClient } from "@azure/storage-blob";
const blobClient = new BlobServiceClient(
  "https://<account>.blob.core.windows.net",
  credential
);

Voir Aperçu de DefaultAzureCredential pour l'ordre de la chaîne d'identifiants actuelle et les valeurs par défaut.

Identité managée

Assignée au système

import { ManagedIdentityCredential } from "@azure/identity";

const credential = new ManagedIdentityCredential();

Assignée à l'utilisateur (par ID client)

const credential = new ManagedIdentityCredential({
  clientId: "<user-assigned-client-id>"
});

Assignée à l'utilisateur (par ID de ressource)

const credential = new ManagedIdentityCredential({
  resourceId: "/subscriptions/<sub>/resourceGroups/<rg>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<name>"
});

Assignée à l'utilisateur (par ID d'objet)

const credential = new ManagedIdentityCredential({
  objectId: "<user-assigned-object-id>"
});

Service Principal

Secret client

import { ClientSecretCredential } from "@azure/identity";

const credential = new ClientSecretCredential(
  "<tenant-id>",
  "<client-id>",
  "<client-secret>"
);

Certificat client

import { ClientCertificateCredential } from "@azure/identity";

const credential = new ClientCertificateCredential(
  "<tenant-id>",
  "<client-id>",
  { certificatePath: "/path/to/cert.pem" }
);

// Avec mot de passe
const credentialWithPwd = new ClientCertificateCredential(
  "<tenant-id>",
  "<client-id>",
  { 
    certificatePath: "/path/to/cert.pem",
    certificatePassword: "<password>"
  }
);

Authentification interactive

Connexion basée sur le navigateur

import { InteractiveBrowserCredential } from "@azure/identity";

const credential = new InteractiveBrowserCredential({
  clientId: "<client-id>",
  tenantId: "<tenant-id>",
  loginHint: "user@example.com"
});

Flux de code d'appareil

import { DeviceCodeCredential } from "@azure/identity";

const credential = new DeviceCodeCredential({
  clientId: "<client-id>",
  tenantId: "<tenant-id>",
  userPromptCallback: (info) => {
    console.log(info.message);
    // "To sign in, use a web browser to open..."
  }
});

Chaîne d'identifiants personnalisée

import { 
  ChainedTokenCredential,
  ManagedIdentityCredential,
  AzureCliCredential
} from "@azure/identity";

// Essayer d'abord l'identité managée, puis la CLI
const credential = new ChainedTokenCredential(
  new ManagedIdentityCredential(),
  new AzureCliCredential()
);

Identifiants développeur

Visual Studio Code

import { useIdentityPlugin, VisualStudioCodeCredential } from "@azure/identity";
import { vsCodePlugin } from "@azure/identity-vscode";

useIdentityPlugin(vsCodePlugin);

const credential = new VisualStudioCodeCredential();

Azure CLI

import { AzureCliCredential } from "@azure/identity";

const credential = new AzureCliCredential();
// Utilise : az login

Azure Developer CLI

import { AzureDeveloperCliCredential } from "@azure/identity";

const credential = new AzureDeveloperCliCredential();
// Utilise : azd auth login

Azure PowerShell

import { AzurePowerShellCredential } from "@azure/identity";

const credential = new AzurePowerShellCredential();
// Utilise : Connect-AzAccount

Clouds souverains

import { ClientSecretCredential, AzureAuthorityHosts } from "@azure/identity";

// Azure Government
const credential = new ClientSecretCredential(
  "<tenant>", "<client>", "<secret>",
  { authorityHost: AzureAuthorityHosts.AzureGovernment }
);

// Azure China
const credentialChina = new ClientSecretCredential(
  "<tenant>", "<client>", "<secret>",
  { authorityHost: AzureAuthorityHosts.AzureChina }
);

Fournisseur de jetons porteurs

import { DefaultAzureCredential, getBearerTokenProvider } from "@azure/identity";

const credential = new DefaultAzureCredential({requiredEnvVars: ["AZURE_TOKEN_CREDENTIALS"]});

// Créer une fonction qui retourne des jetons
const getAccessToken = getBearerTokenProvider(
  credential,
  "https://cognitiveservices.azure.com/.default"
);

// Utiliser avec les APIs qui ont besoin de jetons porteurs
const token = await getAccessToken();

Types clés

import type { 
  TokenCredential, 
  AccessToken, 
  GetTokenOptions 
} from "@azure/core-auth";

import {
  DefaultAzureCredential,
  DefaultAzureCredentialOptions,
  ManagedIdentityCredential,
  ClientSecretCredential,
  ClientCertificateCredential,
  InteractiveBrowserCredential,
  ChainedTokenCredential,
  AzureCliCredential,
  AzurePowerShellCredential,
  AzureDeveloperCliCredential,
  DeviceCodeCredential,
  AzureAuthorityHosts
} from "@azure/identity";

Implémentation d'identifiant personnalisé

import type { TokenCredential, AccessToken, GetTokenOptions } from "@azure/core-auth";

class CustomCredential implements TokenCredential {
  async getToken(
    scopes: string | string[],
    options?: GetTokenOptions
  ): Promise<AccessToken | null> {
    // Logique personnalisée d'acquisition de jeton
    return {
      token: "<access-token>",
      expiresOnTimestamp: Date.now() + 3600000
    };
  }
}

Débogage

import { setLogLevel, AzureLogger } from "@azure/logger";

setLogLevel("verbose");

// Gestionnaire de log personnalisé
AzureLogger.log = (...args) => {
  console.log("[Azure]", ...args);
};

Bonnes pratiques

1. Utiliser DefaultAzureCredential pour le développement local ; utiliser ManagedIdentityCredential ou WorkloadIdentityCredential pour la production
2. Ne jamais coder les identifiants en dur - Utiliser des variables d'environnement ou une identité managée
3. Préférer l'identité managée - Aucun secret à gérer en production
4. Limiter les identifiants de manière appropriée - Utiliser l'identité assignée à l'utilisateur pour les scénarios multi-locataires
5. Gérer le renouvellement de jetons - Le SDK Azure le fait automatiquement
6. Utiliser ChainedTokenCredential - Pour les scénarios de secours personnalisés