Skip to content

Commit ce71fb5

Browse files
author
Jonathan Turner
authored
[Identity] Readme updates (Azure#12310)
* Align readme with other languages * Align readme with other languages * Remove unused links
1 parent 21a0957 commit ce71fb5

File tree

1 file changed

+60
-40
lines changed

1 file changed

+60
-40
lines changed

‎sdk/identity/identity/README.md‎

Lines changed: 60 additions & 40 deletions
Original file line numberDiff line numberDiff line change
@@ -6,13 +6,25 @@ to authenticate API requests. It supports token authentication using an Azure Ac
66

77
## Getting started
88

9+
### Install the package
10+
11+
Install Azure Identity with `npm`:
12+
13+
```sh
14+
npm install --save @azure/identity
15+
```
16+
917
### Prerequisites
1018

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

24+
### Authenticate the client
25+
26+
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.
27+
1628
#### Authenticating via Visual Studio Code
1729

1830
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.
@@ -33,14 +45,6 @@ For systems without a default web browser, the `az login` command will use the d
3345

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

36-
### Install the package
37-
38-
Install Azure Identity with `npm`:
39-
40-
```sh
41-
npm install --save @azure/identity
42-
```
43-
4448
## Key concepts
4549

4650
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.
@@ -64,18 +68,35 @@ The `DefaultAzureCredential` is appropriate for most scenarios where the applica
6468
- Visual Studio Code - If the developer has authenticated via the Visual Studio Code Azure Account plugin, the `DefaultAzureCredential` will authenticate with that account.
6569
- Azure CLI - If the developer has authenticated an account via the Azure CLI `az login` command, the `DefaultAzureCredential` will authenticate with that account.
6670

67-
### Environment variables
71+
## Environment Variables
72+
73+
`DefaultAzureCredential` and `EnvironmentCredential` can be configured with environment variables. Each type of authentication requires values for specific variables:
6874

69-
`DefaultAzureCredential` and `EnvironmentCredential` are configured for service principal authentication with these environment variables:
75+
#### Service principal with secret
7076

71-
| variable name | value |
72-
| ------------------------------- | ---------------------------------------------------------------------------------------------------- |
73-
| `AZURE_CLIENT_ID` | service principal's app id |
74-
| `AZURE_TENANT_ID` | id of the principal's Azure Active Directory tenant |
75-
| `AZURE_CLIENT_SECRET` | one of the service principal's client secrets (implies `ClientSecretCredential`) |
76-
| `AZURE_CLIENT_CERTIFICATE_PATH` | path to a PEM-encoded certificate file including private key (implies `ClientCertificateCredential`) |
77-
| `AZURE_USERNAME` | the username of a user in the tenant (implies `UsernamePasswordCredential`) |
78-
| `AZURE_PASSWORD` | the password of the user specified in `AZURE_USERNAME` |
77+
| variable name | value |
78+
| --------------------- | ----------------------------------------------------- |
79+
| `AZURE_CLIENT_ID` | id of an Azure Active Directory application |
80+
| `AZURE_TENANT_ID` | id of the application's Azure Active Directory tenant |
81+
| `AZURE_CLIENT_SECRET` | one of the application's client secrets |
82+
83+
#### Service principal with certificate
84+
85+
| variable name | value |
86+
| ------------------------------- | ------------------------------------------------------------------------------------------ |
87+
| `AZURE_CLIENT_ID` | id of an Azure Active Directory application |
88+
| `AZURE_TENANT_ID` | id of the application's Azure Active Directory tenant |
89+
| `AZURE_CLIENT_CERTIFICATE_PATH` | path to a PEM-encoded certificate file including private key (without password protection) |
90+
91+
#### Username and password
92+
93+
| variable name | value |
94+
| ----------------- | ------------------------------------------- |
95+
| `AZURE_CLIENT_ID` | id of an Azure Active Directory application |
96+
| `AZURE_USERNAME` | a username (usually an email address) |
97+
| `AZURE_PASSWORD` | that user's password |
98+
99+
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.
79100

80101
## Examples
81102

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

132153
### Authenticating Azure Hosted Applications
133154

134-
|credential | usage
135-
|-|-
136-
|`DefaultAzureCredential`|provides a simplified authentication experience to quickly start developing applications run in the Azure cloud
137-
|`ChainedTokenCredential`|allows users to define custom authentication flows composing multiple credentials
138-
|`EnvironmentCredential`|authenticates a service principal or user via credential information specified in environment variables
139-
|`ManagedIdentityCredential`|authenticates the managed identity of an azure resource
155+
| credential | usage |
156+
| --------------------------- | --------------------------------------------------------------------------------------------------------------- |
157+
| `DefaultAzureCredential` | provides a simplified authentication experience to quickly start developing applications run in the Azure cloud |
158+
| `ChainedTokenCredential` | allows users to define custom authentication flows composing multiple credentials |
159+
| `EnvironmentCredential` | authenticates a service principal or user via credential information specified in environment variables |
160+
| `ManagedIdentityCredential` | authenticates the managed identity of an azure resource |
140161

141162
### Authenticating Service Principals
142163

143-
|credential | usage
144-
|-|-
145-
|`ClientSecretCredential`|authenticates a service principal using a secret
146-
|`ClientCertificateCredential`|authenticates a service principal using a certificate
164+
| credential | usage |
165+
| ----------------------------- | ----------------------------------------------------- |
166+
| `ClientSecretCredential` | authenticates a service principal using a secret |
167+
| `ClientCertificateCredential` | authenticates a service principal using a certificate |
147168

148169
### Authenticating Users
149170

150-
|credential | usage
151-
|-|-
152-
|`InteractiveBrowserCredential`|interactively authenticates a user with the default system browser
153-
|`DeviceCodeCredential`|interactively authenticates a user on devices with limited UI
154-
|`UserPasswordCredential`|authenticates a user with a username and password
155-
|`AuthorizationCodeCredential`|authenticate a user with a previously obtained authorization code
171+
| credential | usage |
172+
| ------------------------------ | ------------------------------------------------------------------ |
173+
| `InteractiveBrowserCredential` | interactively authenticates a user with the default system browser |
174+
| `DeviceCodeCredential` | interactively authenticates a user on devices with limited UI |
175+
| `UserPasswordCredential` | authenticates a user with a username and password |
176+
| `AuthorizationCodeCredential` | authenticate a user with a previously obtained authorization code |
156177

157178
### Authenticating via Development Tools
158179

159-
160-
|credential | usage
161-
|-|-
162-
|`AzureCliCredential`|authenticate in a development environment with the Azure CLI
163-
|`VisualStudioCodeCredential`|authenticate in a development environment with Visual Studio Code
180+
| credential | usage |
181+
| ---------------------------- | ----------------------------------------------------------------- |
182+
| `AzureCliCredential` | authenticate in a development environment with the Azure CLI |
183+
| `VisualStudioCodeCredential` | authenticate in a development environment with Visual Studio Code |
164184

165185
## Troubleshooting
166186

0 commit comments

Comments
 (0)