diff --git a/common/config/rush/pnpm-lock.yaml b/common/config/rush/pnpm-lock.yaml index e14b70992fb8..6d2cb0215118 100644 --- a/common/config/rush/pnpm-lock.yaml +++ b/common/config/rush/pnpm-lock.yaml @@ -958,6 +958,19 @@ packages: tslib: 2.3.1 dev: false + /@azure/keyvault-keys/4.2.0: + resolution: {integrity: sha512-8RoXLWoB9xQ/Knf10A/G0XrQPH49CcadN5DY9qtr2UNdGPTJrlxSr8u7+/4MFwEVQI9vtIt/dUjdOT9xoFCWww==} + engines: {node: '>=8.0.0'} + dependencies: + '@azure/abort-controller': 1.0.4 + '@azure/core-http': 1.2.6 + '@azure/core-lro': 1.0.5 + '@azure/core-paging': 1.2.0 + '@azure/core-tracing': 1.0.0-preview.11 + '@azure/logger': 1.0.3 + tslib: 2.3.1 + dev: false + /@azure/keyvault-keys/4.3.0: resolution: {integrity: sha512-OEosl0/rE/mKD5Ji9KaQN7UH+yQnV5MS0MRhGqQIiJrG+qAvAla0MYudJzv3XvBlplpGk0+MVgyL9H3KX/UAwQ==} engines: {node: '>=8.0.0'} @@ -1661,7 +1674,6 @@ packages: /@opentelemetry/node/0.22.0_@opentelemetry+api@1.0.3: resolution: {integrity: sha512-+HhGbDruQ7cwejVOIYyxRa28uosnG8W95NiQZ6qE8PXXPsDSyGeftAPbtYpGit0H2f5hrVcMlwmWHeAo9xkSLA==} engines: {node: '>=8.0.0'} - deprecated: Package renamed to @opentelemetry/sdk-trace-node peerDependencies: '@opentelemetry/api': ^1.0.0 dependencies: @@ -8648,7 +8660,7 @@ packages: dev: false file:projects/app-configuration.tgz: - resolution: {integrity: sha512-HBZl2EancfACeRLK2hWk+nCAgXrptXnS9hX5E5SLleYzlPHovsJRBWf3bv0NopaHCgFPdRcAw5xwKa1C2tPz2g==, tarball: file:projects/app-configuration.tgz} + resolution: {integrity: sha512-h9nLQwnEqw1OjRBrG2YmgFUD/wOCQe+fC+/45l/Kpeh2QBkLKXeJslgi5fme0YsUC0wmSsZqYaQZtn9mOCLjlw==, tarball: file:projects/app-configuration.tgz} name: '@rush-temp/app-configuration' version: 0.0.0 dependencies: @@ -11769,11 +11781,12 @@ packages: dev: false file:projects/identity.tgz: - resolution: {integrity: sha512-zAmsPxL+84yLtShRgsFfE4QFuFf0AByJgqJ5f02zJiyBPSBz/n3CeuEfwmbWE+g6XDqO807Dy2sbG13AK4AbEg==, tarball: file:projects/identity.tgz} + resolution: {integrity: sha512-QkmZNug/KiuamhpKErg2s9yln6725JpmR2QGH0Yeagl13Mw9JgEhz1nfXipLOk2Z0tcoIWxMjlGTCILzuguw1w==, tarball: file:projects/identity.tgz} name: '@rush-temp/identity' version: 0.0.0 dependencies: '@azure/core-tracing': 1.0.0-preview.13 + '@azure/keyvault-keys': 4.2.0 '@azure/msal-browser': 2.19.0 '@azure/msal-common': 4.5.1 '@azure/msal-node': 1.3.3 diff --git a/sdk/identity/identity/README.md b/sdk/identity/identity/README.md index f813a6f34411..3ffd3850a289 100644 --- a/sdk/identity/identity/README.md +++ b/sdk/identity/identity/README.md @@ -10,7 +10,7 @@ Key links: - [Package (npm)](https://www.npmjs.com/package/@azure/identity) - [API Reference Documentation](https://docs.microsoft.com/javascript/api/@azure/identity) - [Product documentation](https://azure.microsoft.com/services/active-directory/) -- [Samples](https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/identity/identity/samples) +- [Samples](https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/identity/identity/samples/v2) ## Getting started diff --git a/sdk/identity/identity/package.json b/sdk/identity/identity/package.json index 5dd4fae60a15..5465bbb243e0 100644 --- a/sdk/identity/identity/package.json +++ b/sdk/identity/identity/package.json @@ -29,16 +29,27 @@ "./dist-esm/src/plugins/consumer.js": "./dist-esm/src/plugins/consumer.browser.js", "./dist-esm/test/httpRequests.js": "./dist-esm/test/httpRequests.browser.js" }, + "//sampleConfiguration": { + "productName": "Azure Identity", + "productSlugs": [ + "azure", + "azure-active-directory" + ], + "requiredResources": { + "Azure Active Directory App Registration": "https://docs.microsoft.com/azure/active-directory/develop/quickstart-register-app", + "Azure Key Vault": "https://docs.microsoft.com/azure/key-vault/quick-create-portal" + } + }, "scripts": { "audit": "node ../../../common/scripts/rush-audit.js && rimraf node_modules package-lock.json && npm i --package-lock-only 2>&1 && npm audit", - "build:samples": "echo skipped", + "build:samples": "echo Obsolete.", "build:test": "tsc -p . && rollup -c 2>&1", "build": "npm run clean && npm run extract-api && tsc -p . && rollup -c 2>&1", - "check-format": "prettier --list-different --config ../../../.prettierrc.json --ignore-path ../../../.prettierignore \"src/**/*.ts\" \"test/**/*.ts\" \"*.{js,json}\" \"samples/**/*.{js,json}\"", "clean": "rimraf dist dist-* types *.tgz *.log", - "execute:samples": "echo skipped", + "execute:samples": "dev-tool samples run samples-dev", "extract-api": "tsc -p . && api-extractor run --local", - "format": "prettier --write --config ../../../.prettierrc.json --ignore-path ../../../.prettierignore \"src/**/*.ts\" \"test/**/*.ts\" \"*.{js,json}\" \"samples/**/*.{js,json}\"", + "format": "prettier --write --config ../../../.prettierrc.json --ignore-path ../../../.prettierignore \"src/**/*.ts\" \"test/**/*.ts\" \"samples-dev/**/*.ts\" \"*.{js,json}\"", + "check-format": "prettier --list-different --config ../../../.prettierrc.json --ignore-path ../../../.prettierignore \"src/**/*.ts\" \"test/**/*.ts\" \"samples-dev/**/*.ts\" \"*.{js,json}\"", "integration-test:browser": "echo skipped", "integration-test:node": "nyc mocha -r esm --require source-map-support/register --reporter ../../../common/tools/mocha-multi-reporter.js --timeout 180000 --full-trace \"dist-esm/test/public/node/*.spec.js\"", "integration-test": "npm run integration-test:node && npm run integration-test:browser", @@ -111,6 +122,7 @@ "uuid": "^8.3.0" }, "devDependencies": { + "@azure/keyvault-keys": "4.2.0", "@azure/eslint-plugin-azure-sdk": "^3.0.0", "@azure/dev-tool": "^1.0.0", "@azure/test-utils": "^1.0.0", diff --git a/sdk/identity/identity/samples/javascript/sample.env b/sdk/identity/identity/sample.env similarity index 100% rename from sdk/identity/identity/samples/javascript/sample.env rename to sdk/identity/identity/sample.env diff --git a/sdk/identity/identity/samples/typescript/src/clientSecretCredential.ts b/sdk/identity/identity/samples-dev/clientSecretCredential.ts similarity index 68% rename from sdk/identity/identity/samples/typescript/src/clientSecretCredential.ts rename to sdk/identity/identity/samples-dev/clientSecretCredential.ts index 5950679da79d..a1583e83ce19 100644 --- a/sdk/identity/identity/samples/typescript/src/clientSecretCredential.ts +++ b/sdk/identity/identity/samples-dev/clientSecretCredential.ts @@ -1,6 +1,10 @@ // Copyright (c) Microsoft Corporation. // Licensed under the MIT license. +/** + * @summary Authenticates with an app registration’s client Id and secret. + */ + import { ClientSecretCredential } from "@azure/identity"; import { KeyClient } from "@azure/keyvault-keys"; @@ -9,9 +13,9 @@ require("dotenv").config(); export async function main(): Promise { const credential = new ClientSecretCredential( - process.env.AZURE_TENANT_ID!, // The tenant ID in Azure Active Directory - process.env.AZURE_CLIENT_ID!, // The application (client) ID registered in the AAD tenant - process.env.AZURE_CLIENT_SECRET! // The client secret for the registered application + process.env.AZURE_TENANT_ID!, // The tenant ID in Azure Active Directory + process.env.AZURE_CLIENT_ID!, // The app registration client Id in the AAD tenant + process.env.AZURE_CLIENT_SECRET! // The app registration secret for the registered application ); const keyVaultUrl = `https://key-vault-name.vault.azure.net`; diff --git a/sdk/identity/identity/samples/typescript/src/defaultAzureCredential.ts b/sdk/identity/identity/samples-dev/defaultAzureCredential.ts similarity index 90% rename from sdk/identity/identity/samples/typescript/src/defaultAzureCredential.ts rename to sdk/identity/identity/samples-dev/defaultAzureCredential.ts index c7bfd5ba7f77..f6aba5199af2 100644 --- a/sdk/identity/identity/samples/typescript/src/defaultAzureCredential.ts +++ b/sdk/identity/identity/samples-dev/defaultAzureCredential.ts @@ -1,6 +1,10 @@ // Copyright (c) Microsoft Corporation. // Licensed under the MIT license. +/** + * @summary Tries several authentication methods using a single credential. The simplest way to use `@azure/identity`. + */ + import { DefaultAzureCredential } from "@azure/identity"; import { KeyClient } from "@azure/keyvault-keys"; diff --git a/sdk/identity/identity/samples/typescript/src/environmentCredential.ts b/sdk/identity/identity/samples-dev/environmentCredential.ts similarity index 91% rename from sdk/identity/identity/samples/typescript/src/environmentCredential.ts rename to sdk/identity/identity/samples-dev/environmentCredential.ts index 7701e1c8466a..4c65691c285a 100644 --- a/sdk/identity/identity/samples/typescript/src/environmentCredential.ts +++ b/sdk/identity/identity/samples-dev/environmentCredential.ts @@ -1,6 +1,10 @@ // Copyright (c) Microsoft Corporation. // Licensed under the MIT license. +/** + * @summary Authenticates as an app registration automatically using environment variables. + */ + import { EnvironmentCredential } from "@azure/identity"; import { KeyClient } from "@azure/keyvault-keys"; diff --git a/sdk/identity/identity/samples/AzureIdentityExamples.md b/sdk/identity/identity/samples/AzureIdentityExamples.md index 102f73118ef5..ad5b7dce3ebd 100644 --- a/sdk/identity/identity/samples/AzureIdentityExamples.md +++ b/sdk/identity/identity/samples/AzureIdentityExamples.md @@ -30,7 +30,7 @@ ## Introduction -Authenticating your application, users, and principals is an integral part of working with the Azure client libraries. The Azure Identity library provides multiple ways to gain access to the Azure services, each with a flexible configuration that covers most scenarios. There is sample code in [JavaScript](https://github.com/Azure/azure-sdk-for-js/tree/main/sdk/identity/identity/samples/javascript) and [TypeScript](https://github.com/Azure/azure-sdk-for-js/tree/main/sdk/identity/identity/samples/typescript) to cover the basic authentication scenarios. This document covers several use cases of Identity with greater context and links to the underlying authentication flows and other available documentation. +Authenticating your application, users, and principals is an integral part of working with the Azure client libraries. The Azure Identity library provides multiple ways to gain access to the Azure services, each with a flexible configuration that covers most scenarios. There is sample code in [JavaScript](https://github.com/Azure/azure-sdk-for-js/tree/main/sdk/identity/identity/samples/v2/javascript) and [TypeScript](https://github.com/Azure/azure-sdk-for-js/tree/main/sdk/identity/identity/samples/v2/typescript) to cover the basic authentication scenarios. This document covers several use cases of Identity with greater context and links to the underlying authentication flows and other available documentation. ## Authenticating client-side browser applications @@ -126,7 +126,7 @@ If your application is hosted in Azure, you can make use of [Managed Identity](h #### Authenticating with `DefaultAzureCredential` -This example demonstrates authenticating the `SecretClient` from the [@azure/keyvault-secrets][secrets_client_library] client library using the `DefaultAzureCredential`. There's also [a runnable sample](https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/identity/identity/samples/typescript/src/defaultAzureCredential.ts) to create a Key Vault key client you can copy-paste. The `DefaultAzureCredential` makes for a terrific starting point as it provides sane defaults with minimal configuration and chains multiple credentials together. While you may outgrow it eventually, it is a sensible first choice for most scenarios where the application is intended to ultimately be run in the Azure Cloud. +This example demonstrates authenticating the `SecretClient` from the [@azure/keyvault-secrets][secrets_client_library] client library using the `DefaultAzureCredential`. There's also [a runnable sample](https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/identity/identity/samples/v2/typescript/src/defaultAzureCredential.ts) to create a Key Vault key client you can copy-paste. The `DefaultAzureCredential` makes for a terrific starting point as it provides sane defaults with minimal configuration and chains multiple credentials together. While you may outgrow it eventually, it is a sensible first choice for most scenarios where the application is intended to ultimately be run in the Azure Cloud. ```ts /** @@ -179,7 +179,7 @@ function withInteractiveBrowserCredential() { #### Authenticating a service principal with a client secret -This example demonstrates authenticating the `SecretClient` from the [@azure/keyvault-secrets][secrets_client_library] client library using the `ClientSecretCredential`. There's also [a runnable sample](https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/identity/identity/samples/typescript/src/clientSecretCredential.ts) to create a Key Vault key client you can copy-paste. +This example demonstrates authenticating the `SecretClient` from the [@azure/keyvault-secrets][secrets_client_library] client library using the `ClientSecretCredential`. There's also [a runnable sample](https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/identity/identity/samples/v2/typescript/src/clientSecretCredential.ts) to create a Key Vault key client you can copy-paste. You'll need to: diff --git a/sdk/identity/identity/samples/javascript/README.md b/sdk/identity/identity/samples/javascript/README.md deleted file mode 100644 index 65f379a3794e..000000000000 --- a/sdk/identity/identity/samples/javascript/README.md +++ /dev/null @@ -1,79 +0,0 @@ ---- -page_type: sample -languages: - - javascript -products: - - azure - - azure-active-directory -urlFragment: identity-javascript ---- - -# Azure Identity library samples for JavaScript - -These sample programs show how to use the JavaScript client libraries for Azure Identity in some common scenarios. - -| **File Name** | **Description** | -| ------------------------------------------------------ | --------------------------------------------------------------- | -| [defaultAzureCredential.js][defaultAzureCredential] | Tries several authentications. The simplest way to use @azure/identity | -| [clientSecretCredential.js][clientSecretCredential] | Authenticates with a client and a client's secret. | -| [environmentCredential.js][environmentCredential] | Authenticates with a client and a client's secret sent through environment variables. | - -## Prerequisites - -The samples are compatible with [LTS versions of Node.js](https://nodejs.org/about/releases/). - -You need [an Azure subscription][freesub] and [an Azure Key Vault][azkeyvault] to run these sample programs. - -To create an AAD application: - -- Follow [Documentation to register a new application](https://docs.microsoft.com/azure/active-directory/develop/quickstart-register-app) in the Azure Active Directory (in the Azure portal). -- Note down the `CLIENT_ID` and `TENANT_ID`. -- In the "Certificates & Secrets" tab, create a secret and note that down. - -To allow your registered application to access your Key Vault - -- In the Azure portal, go to your Azure Key Vault. -- In the left-side-navbar of your Azure Key Vault in the Azure portal, go to the `Access Policies` section, then click the `+ Add Access Policy` button. -- In the `Add access policy` page, select all the permissions for Keys, Secrets and Certificates. -- For the `Select principal` field, click on the `None selected`. A panel will appear at the right of the window. Search for your Azure Active Directory application, click the application on the search results, then click "Select" at the bottom. -- Once your application is selected, click the "Add" button. -- Click the `Save` button at the top of the Access Policies section of your Key Vault. -- For more information on securing your Key Vault: [Learn more](https://docs.microsoft.com/azure/key-vault/general/secure-your-key-vault) - -Adapting the samples to run in the browser may require some additional consideration. For details, please see the [package README][package]. - -## Setup - -To run the samples using the published version of the package: - -1. Install the dependencies using `npm`: - -```bash -npm install -``` - -2. Edit the file `sample.env`, adding the correct credentials to access the Azure service and run the samples. Then rename the file from `sample.env` to just `.env`. The sample programs will read this file automatically. - -3. Run whichever samples you like (note that some samples may require additional setup, see the table above): - -```bash -node helloWorld.js -``` - -Alternatively, run a single sample with the correct environment variables set (step 2 is not required if you do this), for example (cross-platform): - -```bash -npx cross-env KEYVAULT_NAME="" AZURE_TENANT_ID="" AZURE_CLIENT_ID="" AZURE_CLIENT_SECRET="" node environmentCredential.js -``` - -## Next Steps - -Take a look at our [API Documentation][apiref] for more information about the APIs that are available in the clients. - -[defaultAzureCredential]: https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/identity/identity/samples/javascript/defaultAzureCredential.js -[clientSecretCredential]: https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/identity/identity/samples/javascript/clientSecretCredential.js -[environmentCredential]: https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/identity/identity/samples/javascript/environmentCredential.js -[apiref]: https://docs.microsoft.com/javascript/api/@azure/identity -[azkeyvault]: https://docs.microsoft.com/azure/key-vault/quick-create-portal -[freesub]: https://azure.microsoft.com/free/ -[package]: https://github.com/Azure/azure-sdk-for-js/tree/main/sdk/identity/identity/README.md diff --git a/sdk/identity/identity/samples/javascript/package.json b/sdk/identity/identity/samples/javascript/package.json deleted file mode 100644 index 599eb9d86d0e..000000000000 --- a/sdk/identity/identity/samples/javascript/package.json +++ /dev/null @@ -1,35 +0,0 @@ -{ - "name": "azure-identity-samples-js", - "private": true, - "version": "0.1.0", - "description": "Azure Identity client library samples for JavaScript", - "engine": { - "node": ">=12.0.0" - }, - "repository": { - "type": "git", - "url": "git+https://github.com/Azure/azure-sdk-for-js.git" - }, - "keywords": [ - "Azure", - "Identity", - "AAD", - "Node.js", - "JavaScript" - ], - "author": "Microsoft Corporation", - "license": "MIT", - "bugs": { - "url": "https://github.com/Azure/azure-sdk-for-js/issues" - }, - "homepage": "https://github.com/Azure/azure-sdk-for-js#readme", - "sideEffects": false, - "dependencies": { - "@azure/identity": "latest", - "@azure/keyvault-keys": "4.1.0", - "dotenv": "^8.2.0" - }, - "devDependencies": { - "rimraf": "^3.0.0" - } -} diff --git a/sdk/identity/identity/samples/tsconfig.json b/sdk/identity/identity/samples/tsconfig.json deleted file mode 100644 index 8d5707a03e55..000000000000 --- a/sdk/identity/identity/samples/tsconfig.json +++ /dev/null @@ -1,14 +0,0 @@ -{ - "extends": "../tsconfig.json", - "compilerOptions": { - "module": "commonjs", - "declaration": false, - "declarationMap": false, - "declarationDir": null, - "sourceMap": false, - "inlineSources": false, - "outDir": "samples/typescript/dist" - }, - "include": ["typescript/**/*.ts"], - "exclude": ["src/**/*", "test/**/*"] -} diff --git a/sdk/identity/identity/samples/typescript/README.md b/sdk/identity/identity/samples/typescript/README.md deleted file mode 100644 index 537aeaae9ec7..000000000000 --- a/sdk/identity/identity/samples/typescript/README.md +++ /dev/null @@ -1,92 +0,0 @@ ---- -page_type: sample -languages: - - typescript -products: - - azure - - azure-active-directory -urlFragment: identity-typescript ---- - -# Azure Identity library samples for TypeScript - -These sample programs show how to use the TypeScript client libraries for Azure Identity in some common scenarios. - -| **File Name** | **Description** | -| ------------------------------- | ---------------------------------------------------------------- | -| [defaultAzureCredential.ts][defaultAzureCredential] | Tries several authentications. The simplest way to use @azure/identity | -| [clientSecretCredential.ts][clientSecretCredential] | Authenticates with a client and a client's secret. | -| [environmentCredential.ts][environmentCredential] | Authenticates with a client and a client's secret sent through environment variables. | - -## Prerequisites - -The samples are compatible with [LTS versions of Node.js](https://nodejs.org/about/releases/). - -Before running the samples in Node, they must be compiled to TypeScript using the TypeScript compiler. For more information on TypeScript, see the [TypeScript documentation][typescript]. Install the TypeScript compiler using - -```bash -npm install -g typescript -``` - -You need [an Azure subscription][freesub] and [an Azure Key Vault][azkeyvault] to run these sample programs. - -To create an AAD application: - -- Follow [Documentation to register a new application](https://docs.microsoft.com/azure/active-directory/develop/quickstart-register-app) in the Azure Active Directory (in the Azure portal). -- Note down the `CLIENT_ID` and `TENANT_ID`. -- In the "Certificates & Secrets" tab, create a secret and note that down. - -To allow your registered application to access your Key Vault - -- In the Azure portal, go to your Azure Key Vault. -- In the left-side-navbar of your Azure Key Vault in the Azure portal, go to the `Access Policies` section, then click the `+ Add Access Policy` button. -- In the `Add access policy` page, select all the permissions for Keys, Secrets and Certificates. -- For the `Select principal` field, click on the `None selected`. A panel will appear at the right of the window. Search for your Azure Active Directory application, click the application on the search results, then click "Select" at the bottom. -- Once your application is selected, click the "Add" button. -- Click the `Save` button at the top of the Access Policies section of your Key Vault. -- For more information on securing your Key Vault: [Learn more](https://docs.microsoft.com/azure/key-vault/general/secure-your-key-vault) - -Adapting the samples to run in the browser may require some additional consideration. For details, please see the [package README][package]. - -## Setup - -To run the samples using the published version of the package: - -1. Install the dependencies using `npm`: - -```bash -npm install -``` - -2. Compile the samples - -```bash -npm run build -``` - -3. Edit the file `sample.env`, adding the correct credentials to access the Azure service and run the samples. Then rename the file from `sample.env` to just `.env`. The sample programs will read this file automatically. - -4. Run whichever samples you like (note that some samples may require additional setup, see the table above): - -```bash -node dist/helloWorld.ts -``` - -Alternatively, run a single sample with the correct environment variables set (step 3 is not required if you do this), for example (cross-platform): - -```bash -npx cross-env KEYVAULT_NAME="" AZURE_TENANT_ID="" AZURE_CLIENT_ID="" AZURE_CLIENT_SECRET="" node dist/environmentCredential.ts -``` - -## Next Steps - -Take a look at our [API Documentation][apiref] for more information about the APIs that are available in the clients. - -[defaultAzureCredential]: https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/identity/identity/samples/typescript/src/defaultAzureCredential.ts -[clientSecretCredential]: https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/identity/identity/samples/typescript/src/clientSecretCredential.ts -[environmentCredential]: https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/identity/identity/samples/typescript/src/environmentCredential.ts -[apiref]: https://docs.microsoft.com/javascript/api/@azure/identity -[azkeyvault]: https://docs.microsoft.com/azure/key-vault/quick-create-portal -[freesub]: https://azure.microsoft.com/free/ -[package]: https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/keyvault/keyvault-keys/README.md -[typescript]: https://www.typescriptlang.org/docs/home.html diff --git a/sdk/identity/identity/samples/typescript/package.json b/sdk/identity/identity/samples/typescript/package.json deleted file mode 100644 index 5d2a6643d221..000000000000 --- a/sdk/identity/identity/samples/typescript/package.json +++ /dev/null @@ -1,43 +0,0 @@ -{ - "name": "azure-identity-samples-ts", - "private": true, - "version": "0.1.0", - "description": "Azure Identity Keys client library samples for TypeScript", - "engine": { - "node": ">=12.0.0" - }, - "scripts": { - "build": "tsc", - "prebuild": "rimraf dist/" - }, - "repository": { - "type": "git", - "url": "git+https://github.com/Azure/azure-sdk-for-js.git" - }, - "keywords": [ - "Azure", - "Identity", - "AAD", - "Node.js", - "TypeScript" - ], - "author": "Microsoft Corporation", - "license": "MIT", - "bugs": { - "url": "https://github.com/Azure/azure-sdk-for-js/issues" - }, - "homepage": "https://github.com/Azure/azure-sdk-for-js#readme", - "sideEffects": false, - "dependencies": { - "@azure/identity": "^2.0.1", - "@azure/keyvault-keys": "4.1.0", - "@azure/keyvault-secrets": "4.2.0", - "@azure/keyvault-certificates": "4.2.0", - "dotenv": "^8.2.0" - }, - "devDependencies": { - "@types/node": "^12.0.0", - "rimraf": "^3.0.0", - "typescript": "~3.6.4" - } -} diff --git a/sdk/identity/identity/samples/v2/javascript/README.md b/sdk/identity/identity/samples/v2/javascript/README.md new file mode 100644 index 000000000000..ae1dbc0e254b --- /dev/null +++ b/sdk/identity/identity/samples/v2/javascript/README.md @@ -0,0 +1,69 @@ +--- +page_type: sample +languages: + - javascript +products: + - azure + - azure-active-directory +urlFragment: identity-javascript +--- + +# Azure Identity client library samples for JavaScript + +These sample programs show how to use the JavaScript client libraries for Azure Identity in some common scenarios. + +| **File Name** | **Description** | +| --------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | +| [clientSecretCredential.js][clientsecretcredential] | Authenticates with an app registration’s client Id and secret. | +| [defaultAzureCredential.js][defaultazurecredential] | Tries several authentication methods using a single credential. The simplest way to use `@azure/identity`. | +| [environmentCredential.js][environmentcredential] | Authenticates as an app registration automatically using environment variables. | + +## Prerequisites + +The sample programs are compatible with [LTS versions of Node.js](https://nodejs.org/about/releases/). + +You need [an Azure subscription][freesub] and the following Azure resources to run these sample programs: + +- [Azure Active Directory App Registration][createinstance_azureactivedirectoryappregistration] +- [Azure Key Vault][createinstance_azurekeyvault] + +Samples retrieve credentials to access the service endpoint from environment variables. Alternatively, edit the source code to include the appropriate credentials. See each individual sample for details on which environment variables/credentials it requires to function. + +Adapting the samples to run in the browser may require some additional consideration. For details, please see the [package README][package]. + +## Setup + +To run the samples using the published version of the package: + +1. Install the dependencies using `npm`: + +```bash +npm install +``` + +2. Edit the file `sample.env`, adding the correct credentials to access the Azure service and run the samples. Then rename the file from `sample.env` to just `.env`. The sample programs will read this file automatically. + +3. Run whichever samples you like (note that some samples may require additional setup, see the table above): + +```bash +node clientSecretCredential.js +``` + +Alternatively, run a single sample with the correct environment variables set (setting up the `.env` file is not required if you do this), for example (cross-platform): + +```bash +npx cross-env AZURE_TENANT_ID="" AZURE_CLIENT_ID="" AZURE_CLIENT_SECRET="" node clientSecretCredential.js +``` + +## Next Steps + +Take a look at our [API Documentation][apiref] for more information about the APIs that are available in the clients. + +[clientsecretcredential]: https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/identity/identity/samples/v2/javascript/clientSecretCredential.js +[defaultazurecredential]: https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/identity/identity/samples/v2/javascript/defaultAzureCredential.js +[environmentcredential]: https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/identity/identity/samples/v2/javascript/environmentCredential.js +[apiref]: https://docs.microsoft.com/javascript/api/@azure/identity +[freesub]: https://azure.microsoft.com/free/ +[createinstance_azureactivedirectoryappregistration]: https://docs.microsoft.com/azure/active-directory/develop/quickstart-register-app +[createinstance_azurekeyvault]: https://docs.microsoft.com/azure/key-vault/quick-create-portal +[package]: https://github.com/Azure/azure-sdk-for-js/tree/main/sdk/identity/identity/README.md diff --git a/sdk/identity/identity/samples/javascript/clientSecretCredential.js b/sdk/identity/identity/samples/v2/javascript/clientSecretCredential.js similarity index 75% rename from sdk/identity/identity/samples/javascript/clientSecretCredential.js rename to sdk/identity/identity/samples/v2/javascript/clientSecretCredential.js index 94beda58a8fb..974275a904ae 100644 --- a/sdk/identity/identity/samples/javascript/clientSecretCredential.js +++ b/sdk/identity/identity/samples/v2/javascript/clientSecretCredential.js @@ -1,6 +1,10 @@ // Copyright (c) Microsoft Corporation. // Licensed under the MIT license. +/** + * @summary Authenticates with an app registration’s client Id and secret. + */ + const { ClientSecretCredential } = require("@azure/identity"); const { KeyClient } = require("@azure/keyvault-keys"); @@ -10,8 +14,8 @@ require("dotenv").config(); async function main() { const credential = new ClientSecretCredential( process.env.AZURE_TENANT_ID, // The tenant ID in Azure Active Directory - process.env.AZURE_CLIENT_ID, // The application (client) ID registered in the AAD tenant - process.env.AZURE_CLIENT_SECRET // The client secret for the registered application + process.env.AZURE_CLIENT_ID, // The app registration client Id in the AAD tenant + process.env.AZURE_CLIENT_SECRET // The app registration secret for the registered application ); const keyVaultUrl = `https://key-vault-name.vault.azure.net`; diff --git a/sdk/identity/identity/samples/javascript/defaultAzureCredential.js b/sdk/identity/identity/samples/v2/javascript/defaultAzureCredential.js similarity index 90% rename from sdk/identity/identity/samples/javascript/defaultAzureCredential.js rename to sdk/identity/identity/samples/v2/javascript/defaultAzureCredential.js index 30da561a7666..649a9d4d76ff 100644 --- a/sdk/identity/identity/samples/javascript/defaultAzureCredential.js +++ b/sdk/identity/identity/samples/v2/javascript/defaultAzureCredential.js @@ -1,6 +1,10 @@ // Copyright (c) Microsoft Corporation. // Licensed under the MIT license. +/** + * @summary Tries several authentication methods using a single credential. The simplest way to use `@azure/identity`. + */ + const { DefaultAzureCredential } = require("@azure/identity"); const { KeyClient } = require("@azure/keyvault-keys"); diff --git a/sdk/identity/identity/samples/javascript/environmentCredential.js b/sdk/identity/identity/samples/v2/javascript/environmentCredential.js similarity index 91% rename from sdk/identity/identity/samples/javascript/environmentCredential.js rename to sdk/identity/identity/samples/v2/javascript/environmentCredential.js index fdfe5370c189..9de22c42f74a 100644 --- a/sdk/identity/identity/samples/javascript/environmentCredential.js +++ b/sdk/identity/identity/samples/v2/javascript/environmentCredential.js @@ -1,6 +1,10 @@ // Copyright (c) Microsoft Corporation. // Licensed under the MIT license. +/** + * @summary Authenticates as an app registration automatically using environment variables. + */ + const { EnvironmentCredential } = require("@azure/identity"); const { KeyClient } = require("@azure/keyvault-keys"); diff --git a/sdk/identity/identity/samples/v2/javascript/package.json b/sdk/identity/identity/samples/v2/javascript/package.json new file mode 100644 index 000000000000..77984679179c --- /dev/null +++ b/sdk/identity/identity/samples/v2/javascript/package.json @@ -0,0 +1,36 @@ +{ + "name": "azure-identity-samples-js", + "private": true, + "version": "1.0.0", + "description": "Azure Identity client library samples for JavaScript", + "engines": { + "node": ">=12.0.0" + }, + "repository": { + "type": "git", + "url": "git+https://github.com/Azure/azure-sdk-for-js.git", + "directory": "sdk/identity/identity" + }, + "keywords": [ + "azure", + "cloud", + "active directory", + "authentication", + "credential", + "certificate", + "managed identity", + "client secret", + "access token" + ], + "author": "Microsoft Corporation", + "license": "MIT", + "bugs": { + "url": "https://github.com/Azure/azure-sdk-for-js/issues" + }, + "homepage": "https://github.com/Azure/azure-sdk-for-js/tree/main/sdk/identity/identity", + "dependencies": { + "@azure/identity": "latest", + "dotenv": "latest", + "@azure/keyvault-keys": "4.2.0" + } +} diff --git a/sdk/identity/identity/samples/typescript/sample.env b/sdk/identity/identity/samples/v2/javascript/sample.env similarity index 100% rename from sdk/identity/identity/samples/typescript/sample.env rename to sdk/identity/identity/samples/v2/javascript/sample.env diff --git a/sdk/identity/identity/samples/v2/typescript/README.md b/sdk/identity/identity/samples/v2/typescript/README.md new file mode 100644 index 000000000000..1803bafee1e4 --- /dev/null +++ b/sdk/identity/identity/samples/v2/typescript/README.md @@ -0,0 +1,82 @@ +--- +page_type: sample +languages: + - typescript +products: + - azure + - azure-active-directory +urlFragment: identity-typescript +--- + +# Azure Identity client library samples for TypeScript + +These sample programs show how to use the TypeScript client libraries for Azure Identity in some common scenarios. + +| **File Name** | **Description** | +| --------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | +| [clientSecretCredential.ts][clientsecretcredential] | Authenticates with an app registration’s client Id and secret. | +| [defaultAzureCredential.ts][defaultazurecredential] | Tries several authentication methods using a single credential. The simplest way to use `@azure/identity`. | +| [environmentCredential.ts][environmentcredential] | Authenticates as an app registration automatically using environment variables. | + +## Prerequisites + +The sample programs are compatible with [LTS versions of Node.js](https://nodejs.org/about/releases/). + +Before running the samples in Node, they must be compiled to JavaScript using the TypeScript compiler. For more information on TypeScript, see the [TypeScript documentation][typescript]. Install the TypeScript compiler using: + +```bash +npm install -g typescript +``` + +You need [an Azure subscription][freesub] and the following Azure resources to run these sample programs: + +- [Azure Active Directory App Registration][createinstance_azureactivedirectoryappregistration] +- [Azure Key Vault][createinstance_azurekeyvault] + +Samples retrieve credentials to access the service endpoint from environment variables. Alternatively, edit the source code to include the appropriate credentials. See each individual sample for details on which environment variables/credentials it requires to function. + +Adapting the samples to run in the browser may require some additional consideration. For details, please see the [package README][package]. + +## Setup + +To run the samples using the published version of the package: + +1. Install the dependencies using `npm`: + +```bash +npm install +``` + +2. Compile the samples: + +```bash +npm run build +``` + +3. Edit the file `sample.env`, adding the correct credentials to access the Azure service and run the samples. Then rename the file from `sample.env` to just `.env`. The sample programs will read this file automatically. + +4. Run whichever samples you like (note that some samples may require additional setup, see the table above): + +```bash +node dist/clientSecretCredential.js +``` + +Alternatively, run a single sample with the correct environment variables set (setting up the `.env` file is not required if you do this), for example (cross-platform): + +```bash +npx cross-env AZURE_TENANT_ID="" AZURE_CLIENT_ID="" AZURE_CLIENT_SECRET="" node dist/clientSecretCredential.js +``` + +## Next Steps + +Take a look at our [API Documentation][apiref] for more information about the APIs that are available in the clients. + +[clientsecretcredential]: https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/identity/identity/samples/v2/typescript/src/clientSecretCredential.ts +[defaultazurecredential]: https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/identity/identity/samples/v2/typescript/src/defaultAzureCredential.ts +[environmentcredential]: https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/identity/identity/samples/v2/typescript/src/environmentCredential.ts +[apiref]: https://docs.microsoft.com/javascript/api/@azure/identity +[freesub]: https://azure.microsoft.com/free/ +[createinstance_azureactivedirectoryappregistration]: https://docs.microsoft.com/azure/active-directory/develop/quickstart-register-app +[createinstance_azurekeyvault]: https://docs.microsoft.com/azure/key-vault/quick-create-portal +[package]: https://github.com/Azure/azure-sdk-for-js/tree/main/sdk/identity/identity/README.md +[typescript]: https://www.typescriptlang.org/docs/home.html diff --git a/sdk/identity/identity/samples/v2/typescript/package.json b/sdk/identity/identity/samples/v2/typescript/package.json new file mode 100644 index 000000000000..9917c6494139 --- /dev/null +++ b/sdk/identity/identity/samples/v2/typescript/package.json @@ -0,0 +1,44 @@ +{ + "name": "azure-identity-samples-ts", + "private": true, + "version": "1.0.0", + "description": "Azure Identity client library samples for TypeScript", + "engines": { + "node": ">=12.0.0" + }, + "scripts": { + "build": "tsc", + "prebuild": "rimraf dist/" + }, + "repository": { + "type": "git", + "url": "git+https://github.com/Azure/azure-sdk-for-js.git", + "directory": "sdk/identity/identity" + }, + "keywords": [ + "azure", + "cloud", + "active directory", + "authentication", + "credential", + "certificate", + "managed identity", + "client secret", + "access token" + ], + "author": "Microsoft Corporation", + "license": "MIT", + "bugs": { + "url": "https://github.com/Azure/azure-sdk-for-js/issues" + }, + "homepage": "https://github.com/Azure/azure-sdk-for-js/tree/main/sdk/identity/identity", + "dependencies": { + "@azure/identity": "latest", + "dotenv": "latest", + "@azure/keyvault-keys": "4.2.0" + }, + "devDependencies": { + "typescript": "~4.4.0", + "rimraf": "latest" + } +} diff --git a/sdk/identity/identity/samples/v2/typescript/sample.env b/sdk/identity/identity/samples/v2/typescript/sample.env new file mode 100644 index 000000000000..95ba051a2196 --- /dev/null +++ b/sdk/identity/identity/samples/v2/typescript/sample.env @@ -0,0 +1,8 @@ +# The name of the key vault to use in the samples. +# Create a Key Vault in the Azure Portal and enter its URI (e.g. https://mytest.vault.azure.net/) here. +KEYVAULT_URI= + +# Used by some of the credentials to authenticate using Azure AD as a service principal for role-based authentication. +AZURE_TENANT_ID= +AZURE_CLIENT_ID= +AZURE_CLIENT_SECRET= diff --git a/sdk/identity/identity/samples/v2/typescript/src/clientSecretCredential.ts b/sdk/identity/identity/samples/v2/typescript/src/clientSecretCredential.ts new file mode 100644 index 000000000000..a1583e83ce19 --- /dev/null +++ b/sdk/identity/identity/samples/v2/typescript/src/clientSecretCredential.ts @@ -0,0 +1,32 @@ +// Copyright (c) Microsoft Corporation. +// Licensed under the MIT license. + +/** + * @summary Authenticates with an app registration’s client Id and secret. + */ + +import { ClientSecretCredential } from "@azure/identity"; +import { KeyClient } from "@azure/keyvault-keys"; + +// Load the .env file if it exists +require("dotenv").config(); + +export async function main(): Promise { + const credential = new ClientSecretCredential( + process.env.AZURE_TENANT_ID!, // The tenant ID in Azure Active Directory + process.env.AZURE_CLIENT_ID!, // The app registration client Id in the AAD tenant + process.env.AZURE_CLIENT_SECRET! // The app registration secret for the registered application + ); + + const keyVaultUrl = `https://key-vault-name.vault.azure.net`; + const client = new KeyClient(keyVaultUrl, credential); + + // Retrieving the properties of the existing keys in that specific Key Vault. + console.log(await client.listPropertiesOfKeys().next()); +} + +main().catch((err) => { + console.log("error code: ", err.code); + console.log("error message: ", err.message); + console.log("error stack: ", err.stack); +}); diff --git a/sdk/identity/identity/samples/v2/typescript/src/defaultAzureCredential.ts b/sdk/identity/identity/samples/v2/typescript/src/defaultAzureCredential.ts new file mode 100644 index 000000000000..f6aba5199af2 --- /dev/null +++ b/sdk/identity/identity/samples/v2/typescript/src/defaultAzureCredential.ts @@ -0,0 +1,36 @@ +// Copyright (c) Microsoft Corporation. +// Licensed under the MIT license. + +/** + * @summary Tries several authentication methods using a single credential. The simplest way to use `@azure/identity`. + */ + +import { DefaultAzureCredential } from "@azure/identity"; +import { KeyClient } from "@azure/keyvault-keys"; + +// Load the .env file if it exists +require("dotenv").config(); + +/** + * The `DefaultAzureCredential` is appropriate for most scenarios where the application is intended to ultimately be run in the Azure Cloud. + * This is because the `DefaultAzureCredential` combines credentials commonly used to authenticate when deployed, + * with credentials used to authenticate in a development environment. + * + * For more information, you may go to our readme: [link](https://github.com/Azure/azure-sdk-for-js/tree/main/sdk/identity/identity#defaultazurecredential) + */ + +export async function main(): Promise { + const credential = new DefaultAzureCredential(); + + const keyVaultUrl = `https://key-vault-name.vault.azure.net`; + const client = new KeyClient(keyVaultUrl, credential); + + // Retrieving the properties of the existing keys in that specific Key Vault. + console.log(await client.listPropertiesOfKeys().next()); +} + +main().catch((err) => { + console.log("error code: ", err.code); + console.log("error message: ", err.message); + console.log("error stack: ", err.stack); +}); diff --git a/sdk/identity/identity/samples/v2/typescript/src/environmentCredential.ts b/sdk/identity/identity/samples/v2/typescript/src/environmentCredential.ts new file mode 100644 index 000000000000..4c65691c285a --- /dev/null +++ b/sdk/identity/identity/samples/v2/typescript/src/environmentCredential.ts @@ -0,0 +1,32 @@ +// Copyright (c) Microsoft Corporation. +// Licensed under the MIT license. + +/** + * @summary Authenticates as an app registration automatically using environment variables. + */ + +import { EnvironmentCredential } from "@azure/identity"; +import { KeyClient } from "@azure/keyvault-keys"; + +// Load the .env file if it exists +require("dotenv").config(); + +export async function main(): Promise { + // EnvironmentCredential expects the following three environment variables: + // - AZURE_TENANT_ID: The tenant ID in Azure Active Directory + // - AZURE_CLIENT_ID: The application (client) ID registered in the AAD tenant + // - AZURE_CLIENT_SECRET: The client secret for the registered application + const credential = new EnvironmentCredential(); + + const keyVaultUrl = `https://key-vault-name.vault.azure.net`; + const client = new KeyClient(keyVaultUrl, credential); + + // Retrieving the properties of the existing keys in that specific Key Vault. + console.log(await client.listPropertiesOfKeys().next()); +} + +main().catch((err) => { + console.log("error code: ", err.code); + console.log("error message: ", err.message); + console.log("error stack: ", err.stack); +}); diff --git a/sdk/identity/identity/samples/typescript/tsconfig.json b/sdk/identity/identity/samples/v2/typescript/tsconfig.json similarity index 51% rename from sdk/identity/identity/samples/typescript/tsconfig.json rename to sdk/identity/identity/samples/v2/typescript/tsconfig.json index 4332663bf7b7..416c2dd82e00 100644 --- a/sdk/identity/identity/samples/typescript/tsconfig.json +++ b/sdk/identity/identity/samples/v2/typescript/tsconfig.json @@ -1,15 +1,17 @@ { "compilerOptions": { + "target": "ES2018", "module": "commonjs", "moduleResolution": "node", - - "lib": ["dom", "dom.iterable", "esnext.asynciterable"], - + "resolveJsonModule": true, + "esModuleInterop": true, "allowSyntheticDefaultImports": true, - + "strict": true, + "alwaysStrict": true, "outDir": "dist", "rootDir": "src" }, - "include": ["src/**.ts"], - "exclude": ["node_modules"] + "include": [ + "src/**.ts" + ] } diff --git a/sdk/identity/identity/src/credentials/authorizationCodeCredential.ts b/sdk/identity/identity/src/credentials/authorizationCodeCredential.ts index f45a082963a8..dd76a11cef9b 100644 --- a/sdk/identity/identity/src/credentials/authorizationCodeCredential.ts +++ b/sdk/identity/identity/src/credentials/authorizationCodeCredential.ts @@ -33,7 +33,7 @@ export class AuthorizationCodeCredential implements TokenCredential { * the authorization code flow to obtain an authorization code to be used * with this credential. A full example of this flow is provided here: * - * https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/identity/identity/samples/manual/authorizationCodeSample.ts + * https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/identity/identity/samples/v2/manual/authorizationCodeSample.ts * * @param tenantId - The Azure Active Directory tenant (directory) ID or name. * 'common' may be used when dealing with multi-tenant scenarios. @@ -63,7 +63,7 @@ export class AuthorizationCodeCredential implements TokenCredential { * the authorization code flow to obtain an authorization code to be used * with this credential. A full example of this flow is provided here: * - * https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/identity/identity/samples/manual/authorizationCodeSample.ts + * https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/identity/identity/samples/v2/manual/authorizationCodeSample.ts * * @param tenantId - The Azure Active Directory tenant (directory) ID or name. * 'common' may be used when dealing with multi-tenant scenarios. diff --git a/sdk/identity/identity/tsconfig.json b/sdk/identity/identity/tsconfig.json index 3ceaa1947afd..dc4de9e400d1 100644 --- a/sdk/identity/identity/tsconfig.json +++ b/sdk/identity/identity/tsconfig.json @@ -4,8 +4,11 @@ "lib": ["DOM"], "declarationDir": "./types", "outDir": "./dist-esm", - "resolveJsonModule": true + "resolveJsonModule": true, + "paths": { + "@azure/identity": ["./src/index"] + } }, - "include": ["src/**/*", "test/**/*"], + "include": ["src/**/*", "test/**/*", "samples-dev/**/*.ts"], "exclude": ["test/manual*/**/*", "node_modules"] }