Skip to content

[Identity] Readme updates #12310

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
sophiajt merged 3 commits into from
Nov 5, 2020
Merged

[Identity] Readme updates #12310

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
602cfff
Align readme with other languages
Nov 5, 2020
7e5c721
Align readme with other languages
Nov 5, 2020
b52811e
Remove unused links
Nov 5, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
100 changes: 60 additions & 40 deletions sdk/identity/identity/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,13 +6,25 @@ to authenticate API requests. It supports token authentication using an Azure Ac

## Getting started

### Install the package

Install Azure Identity with `npm`:

```sh
npm install --save @azure/identity
```

### Prerequisites

- Node.js 8 LTS or higher
- An Azure subscription.
- You can sign up for a [free account](https://azure.microsoft.com/free/).
- You can sign up for a [free account](https://azure.microsoft.com/free/).
- The [Azure CLI][azure_cli] can also be useful for authenticating in a development environment, creating accounts, and managing account roles.

### Authenticate the client

When debugging and executing code locally it is typical for a developer to use their own account for authenticating calls to Azure services. There are several developer tools which can be used to perform this authentication in your development environment.
Copy link
Copy Markdown
Contributor

@sadasant sadasant Nov 5, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I like this!


#### Authenticating via Visual Studio Code

Developers using Visual Studio Code can use the [Azure Account Extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode.azure-account), to authenticate via the IDE. Applications using the `DefaultAzureCredential` or the `VisualStudioCodeCredential` can then use this account to authenticate calls in their application when running locally.
Expand All @@ -33,14 +45,6 @@ For systems without a default web browser, the `az login` command will use the d

![Azure CLI Account Device Code Sign In][azureclilogindevicecode_image]

### Install the package

Install Azure Identity with `npm`:

```sh
npm install --save @azure/identity
```

## Key concepts

If this is your first time using `@azure/identity` or the Microsoft identity platform (Azure Active Directory), we recommend that you read [Using `@azure/identity` with Microsoft Identity Platform](https://github.com/Azure/azure-sdk-for-js/blob/master/documentation/using-azure-identity.md) first. This document will give you a deeper understanding of the platform and how to configure your Azure account correctly.
Expand All @@ -64,18 +68,35 @@ The `DefaultAzureCredential` is appropriate for most scenarios where the applica
- Visual Studio Code - If the developer has authenticated via the Visual Studio Code Azure Account plugin, the `DefaultAzureCredential` will authenticate with that account.
- Azure CLI - If the developer has authenticated an account via the Azure CLI `az login` command, the `DefaultAzureCredential` will authenticate with that account.

### Environment variables
## Environment Variables

`DefaultAzureCredential` and `EnvironmentCredential` can be configured with environment variables. Each type of authentication requires values for specific variables:

`DefaultAzureCredential` and `EnvironmentCredential` are configured for service principal authentication with these environment variables:
#### Service principal with secret

| variable name | value |
| ------------------------------- | ---------------------------------------------------------------------------------------------------- |
| `AZURE_CLIENT_ID` | service principal's app id |
| `AZURE_TENANT_ID` | id of the principal's Azure Active Directory tenant |
| `AZURE_CLIENT_SECRET` | one of the service principal's client secrets (implies `ClientSecretCredential`) |
| `AZURE_CLIENT_CERTIFICATE_PATH` | path to a PEM-encoded certificate file including private key (implies `ClientCertificateCredential`) |
| `AZURE_USERNAME` | the username of a user in the tenant (implies `UsernamePasswordCredential`) |
| `AZURE_PASSWORD` | the password of the user specified in `AZURE_USERNAME` |
| variable name | value |
| --------------------- | ----------------------------------------------------- |
| `AZURE_CLIENT_ID` | id of an Azure Active Directory application |
| `AZURE_TENANT_ID` | id of the application's Azure Active Directory tenant |
| `AZURE_CLIENT_SECRET` | one of the application's client secrets |

#### Service principal with certificate

| variable name | value |
| ------------------------------- | ------------------------------------------------------------------------------------------ |
| `AZURE_CLIENT_ID` | id of an Azure Active Directory application |
| `AZURE_TENANT_ID` | id of the application's Azure Active Directory tenant |
| `AZURE_CLIENT_CERTIFICATE_PATH` | path to a PEM-encoded certificate file including private key (without password protection) |

#### Username and password

| variable name | value |
| ----------------- | ------------------------------------------- |
| `AZURE_CLIENT_ID` | id of an Azure Active Directory application |
| `AZURE_USERNAME` | a username (usually an email address) |
| `AZURE_PASSWORD` | that user's password |

Configuration is attempted in the above order. For example, if values for a client secret and certificate are both present, the client secret will be used.

## Examples

Expand Down Expand Up @@ -131,36 +152,35 @@ const client = new KeyClient(vaultUrl, credentialChain);

### Authenticating Azure Hosted Applications

|credential | usage
|-|-
|`DefaultAzureCredential`|provides a simplified authentication experience to quickly start developing applications run in the Azure cloud
|`ChainedTokenCredential`|allows users to define custom authentication flows composing multiple credentials
|`EnvironmentCredential`|authenticates a service principal or user via credential information specified in environment variables
|`ManagedIdentityCredential`|authenticates the managed identity of an azure resource
| credential | usage |
| --------------------------- | --------------------------------------------------------------------------------------------------------------- |
| `DefaultAzureCredential` | provides a simplified authentication experience to quickly start developing applications run in the Azure cloud |
| `ChainedTokenCredential` | allows users to define custom authentication flows composing multiple credentials |
| `EnvironmentCredential` | authenticates a service principal or user via credential information specified in environment variables |
| `ManagedIdentityCredential` | authenticates the managed identity of an azure resource |

### Authenticating Service Principals

|credential | usage
|-|-
|`ClientSecretCredential`|authenticates a service principal using a secret
|`ClientCertificateCredential`|authenticates a service principal using a certificate
| credential | usage |
| ----------------------------- | ----------------------------------------------------- |
| `ClientSecretCredential` | authenticates a service principal using a secret |
| `ClientCertificateCredential` | authenticates a service principal using a certificate |

### Authenticating Users

|credential | usage
|-|-
|`InteractiveBrowserCredential`|interactively authenticates a user with the default system browser
|`DeviceCodeCredential`|interactively authenticates a user on devices with limited UI
|`UserPasswordCredential`|authenticates a user with a username and password
|`AuthorizationCodeCredential`|authenticate a user with a previously obtained authorization code
| credential | usage |
| ------------------------------ | ------------------------------------------------------------------ |
| `InteractiveBrowserCredential` | interactively authenticates a user with the default system browser |
| `DeviceCodeCredential` | interactively authenticates a user on devices with limited UI |
| `UserPasswordCredential` | authenticates a user with a username and password |
| `AuthorizationCodeCredential` | authenticate a user with a previously obtained authorization code |

### Authenticating via Development Tools


|credential | usage
|-|-
|`AzureCliCredential`|authenticate in a development environment with the Azure CLI
|`VisualStudioCodeCredential`|authenticate in a development environment with Visual Studio Code
| credential | usage |
| ---------------------------- | ----------------------------------------------------------------- |
| `AzureCliCredential` | authenticate in a development environment with the Azure CLI |
| `VisualStudioCodeCredential` | authenticate in a development environment with Visual Studio Code |

## Troubleshooting

Expand Down