azure-identity-ts

Azure Identity SDK for TypeScript

さまざまな種類の認証情報を使用して、Azure サービスに認証します。

インストール

npm install @azure/identity

環境変数

サービスプリンシパル（シークレット）

AZURE_TENANT_ID=<tenant-id>
AZURE_CLIENT_ID=<client-id>
AZURE_CLIENT_SECRET=<client-secret>

サービスプリンシパル（証明書）

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

ワークロード ID（Kubernetes）

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

DefaultAzureCredential（推奨）

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

const credential = new DefaultAzureCredential();

// Use with any Azure SDK client
import { BlobServiceClient } from "@azure/storage-blob";
const blobClient = new BlobServiceClient(
  "https://<account>.blob.core.windows.net",
  credential
);

過去の認証情報チェーンの概要（インストール済みの SDK バージョン／プラグインを確認してください）：

1. EnvironmentCredential
2. WorkloadIdentityCredential
3. ManagedIdentityCredential
4. VisualStudioCodeCredential
5. AzureCliCredential
6. AzurePowerShellCredential
7. AzureDeveloperCliCredential

マネージド ID

システム割り当て

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

const credential = new ManagedIdentityCredential();

ユーザー割り当て（クライアント ID による指定）

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

ユーザー割り当て（リソース ID による指定）

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

サービスプリンシパル

クライアントシークレット

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

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

クライアント証明書

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

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

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

対話型認証

ブラウザーを使ったログイン

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

const credential = new InteractiveBrowserCredential({
  clientId: "<client-id>",
  tenantId: "<tenant-id>",
  loginHint: "[email protected]"
});

デバイスコードフロー

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..."
  }
});

カスタム認証情報チェーン

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

// Try managed identity first, fall back to CLI
const credential = new ChainedTokenCredential(
  new ManagedIdentityCredential(),
  new AzureCliCredential()
);

開発者向け認証情報

Azure CLI

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

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

Azure Developer CLI

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

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

Azure PowerShell

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

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

ソブリンクラウド

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 }
);

ベアラートークンプロバイダー

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

const credential = new DefaultAzureCredential();

// Create a function that returns tokens
const getAccessToken = getBearerTokenProvider(
  credential,
  "https://cognitiveservices.azure.com/.default"
);

// Use with APIs that need bearer tokens
const token = await getAccessToken();

キーの種類

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";

カスタム認証情報の実装

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

class CustomCredential implements TokenCredential {
  async getToken(
    scopes: string | string[],
    options?: GetTokenOptions
  ): Promise<AccessToken | null> {
    // Custom token acquisition logic
    return {
      token: "<access-token>",
      expiresOnTimestamp: Date.now() + 3600000
    };
  }
}

デバッグ

承認された非公開の診断環境でのみ詳細な ID ログを使用し、テナント／アカウント／トークンに関する機密情報を含む出力をマスキングして、終了後に通常のログレベルに戻してください。選択された ID とテナントを確認してください。認証情報チェーンが正常に動作しても、意図したプリンシパルが使用されたとは限りません。

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

setLogLevel("verbose");

// Custom log handler
AzureLogger.log = (...args) => {
  console.log("[Azure]", ...args);
};

ベストプラクティス

1. DefaultAzureCredential を使用する - 開発環境（CLI）と本番環境（マネージド ID）の両方で機能します
2. 認証情報をハードコードしない - 環境変数またはマネージド ID を使用します
3. マネージド ID を優先する - 本番環境で管理するシークレットが不要になります
4. 認証情報の適用範囲を適切に設定する - マルチテナントのシナリオではユーザー割り当て ID を使用します
5. トークンの更新を処理する - Azure SDK が自動的に処理します
6. ChainedTokenCredential を使用する - カスタムのフォールバックが必要なシナリオで使用します

使用する場合

このスキルは、概要で説明されているワークフローまたはアクションを実行する際に適用できます。

制限事項

• このスキルは、タスクが上記の説明にある対象範囲に明確に合致する場合にのみ使用してください。
• 出力を、環境固有の検証、テスト、または専門家によるレビューの代わりとして扱わないでください。
• 必要な入力、権限、安全上の境界、または成功基準が不足している場合は、作業を中断して確認を求めてください。