Azure 身份验证 TypeScript 库

azure-identity-ts
分类通用
作者Agentic Awesome Skills 社区
许可MIT
评分4.20/5
使用9.2K

Azure Identity SDK for TypeScript

使用多种凭据类型对 Azure 服务进行身份验证。

安装

bash
npm install @azure/identity

环境变量

服务主体 (密钥)

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

服务主体 (证书)

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

工作负载身份 (Kubernetes)

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

DefaultAzureCredential (推荐)

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

const credential = new DefaultAzureCredential();


// 与任何 Azure SDK 客户端配合使用
import { BlobServiceClient } from "@azure/storage-blob";
const blobClient = new BlobServiceClient(
  "https://<account>.blob.core.windows.net",
  credential
);

凭据链顺序：
1. EnvironmentCredential
2. WorkloadIdentityCredential
3. ManagedIdentityCredential
4. VisualStudioCodeCredential
5. AzureCliCredential
6. AzurePowerShellCredential
7. AzureDeveloperCliCredential

托管身份 (Managed Identity)

系统分配

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

const credential = new ManagedIdentityCredential();

用户分配 (通过客户端 ID)

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

用户分配 (通过资源 ID)

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

服务主体 (Service Principal)

客户端密钥

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

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

客户端证书

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

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


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

交互式身份验证

基于浏览器的登录

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

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

设备代码流

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

自定义凭据链

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

// 优先尝试托管身份，失败后回退到 CLI
const credential

= new ChainedTokenCredential(
new ManagedIdentityCredential(),
new AzureCliCredential()
);
code
## 开发者凭据


Azure CLI
typescript import { AzureCliCredential } from "@azure/identity";

const credential = new AzureCliCredential();
// 使用：az login

code
### Azure Developer CLI
typescript
import { AzureDeveloperCliCredential } from "@azure/identity";

const credential = new AzureDeveloperCliCredential();
// 使用：azd auth login

code
### Azure PowerShell
typescript
import { AzurePowerShellCredential } from "@azure/identity";

const credential = new AzurePowerShellCredential();
// 使用：Connect-AzAccount

code
## 主权云 (Sovereign Clouds)
typescript
import { ClientSecretCredential, AzureAuthorityHosts } from "@azure/identity";

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

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

code
## Bearer 令牌提供程序
typescript
import { DefaultAzureCredential, getBearerTokenProvider } from "@azure/identity";

const credential = new DefaultAzureCredential();

// 创建一个返回令牌的函数
const getAccessToken = getBearerTokenProvider(
credential,
"https://cognitiveservices.azure.com/.default"
);

// 用于需要 bearer 令牌的 API
const token = await getAccessToken();

code
## 关键类型
typescript
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";

code
## 自定义凭据实现
typescript
import type { TokenCredential, AccessToken, GetTokenOptions } from "@azure/core-auth";

class CustomCredential implements TokenCredential {
async getToken(
scopes: string | string[],
options?: GetTokenOptions
): Promise<AccessToken | null> {
// 自定义令牌获取逻辑
return {
token: "<access-token>",
expiresOnTimestamp: Date.now() + 3600000
};
}
}

code
## 调试
typescript
import { setLogLevel, AzureLogger } from "@azure/logger";

setLogLevel("verbose");

// 自定义日志处理器
AzureLogger.log = (...args) => {
console.log("[Azure]", ...args);
};
```

最佳实践

1. 使用 DefaultAzureCredential - 同时适用于开发环境 (CLI) 和生产环境 (托管标识)
2. 切勿硬编码凭据 - 使用环境变量或托管标识
3. 优先使用托管标识 - 生产环境中无需管理密钥
4. 合理配置凭据范围 - 在多租户场景中使用用户分配的标识
5. 处理令牌刷新 - Azure SDK 会自动处理
6. 使用 ChainedTokenCredential - 用于自定义回退场景

适用场景

本技能适用于执行概览中描述的工作流或操作。

局限性

  • 仅在任务与上述描述的范围明确匹配时使用此技能。
  • 不要将输出视为针对特定环境的验证、测试或专家评审的替代方案。
  • 如果需求不明确，请停止并请求澄清。
缺少必要的输入、权限、安全边界或成功标准。