Skip to content

Commit 7584d09

Browse files
JamesJBarnettJamesJBarnett
authored
Merge pull request #251875 from chrissmiller/chrismiller/devcenterAuth
Add DevCenter REST auth docs
2 parents 0d05ba0 + 4b30a45 commit 7584d09

File tree

4 files changed

+154
-0
lines changed

4 files changed

+154
-0
lines changed

‎articles/deployment-environments/how-to-authenticate.md

Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
1+
---
2+
title: Authenticate to Azure Deployment Environments REST APIs
3+
description: Learn how to authenticate to Azure Deployment Environments REST APIs.
4+
ms.service: deployment-environments
5+
ms.custom: ignite-2022, build-2023
6+
ms.topic: conceptual
7+
ms.author: chrismiller
8+
author: chrismiller
9+
ms.date: 09/07/2023
10+
---
11+
# Authenticating to Azure Deployment Environments REST APIs
12+
13+
> [!TIP]
14+
> Before authenticating, ensure that the user or identity has the appropriate permissions to perform the desired action. For more information, see [configuring project admins](./how-to-configure-project-admin.md) and [configuring environment users](./how-to-configure-deployment-environments-user.md).
15+
16+
17+
## Using Azure AD authentication for REST APIs
18+
19+
Use the following procedures to authenticate with Azure AD. You can follow along in [Azure Cloud Shell](../../articles/cloud-shell/quickstart.md), on an Azure virtual machine, or on your local machine.
20+
21+
### Sign in to the user's Azure subscription
22+
23+
Start by authenticating with Azure AD by using the Azure CLI. This step isn't required in Azure Cloud Shell.
24+
25+
```azurecli
26+
az login
27+
```
28+
29+
The command opens a browser window to the Azure AD authentication page. It requires you to give your Azure AD user ID and password.
30+
31+
Next, set the correct subscription context. If you authenticate from an incorrect subscription or tenant you may receive unexpected 403 Forbidden errors.
32+
33+
```azurecli
34+
az account set --subscription <subscription_id>
35+
```
36+
37+
38+
### Retrieve the Azure AD access token
39+
40+
Use the Azure CLI to acquire an access token for the Azure AD authenticated user.
41+
Note that the resource ID is different depending on if you are accessing administrator (control plane) APIs or developer (data plane) APIs.
42+
43+
For administrator APIs, use the following command:
44+
```azurecli-interactive
45+
az account get-access-token
46+
```
47+
48+
For developer APIs, use the following command:
49+
```azurecli-interactive
50+
az account get-access-token --resource https://devcenter.azure.com
51+
```
52+
53+
After authentication is successful, Azure AD returns an access token for current Azure subscription:
54+
55+
```json
56+
{
57+
"accessToken": "[TOKEN]",
58+
"expiresOn": "[expiration_date_and_time]",
59+
"subscription": "[subscription_id]",
60+
"tenant": "[tenant_id]",
61+
"tokenType": "Bearer"
62+
}
63+
```
64+
65+
The token is a Base64 string. The token is valid for at least 5 minutes with the maximum of 90 minutes. The expiresOn defines the actual token expiration time.
66+
67+
> [!TIP]
68+
> Developer API tokens for the service are encrypted and cannot be decoded using JWT decoding tools. They can only be processed by the service.
69+
70+
71+
### Using a bearer token to access REST APIs
72+
To access REST APIs, you must set the Authorization header on your request. The header value should be the string `Bearer` followed by a space and the token you received in the previous step.
73+
74+
## Next steps
75+
- Review [Azure Active Directory fundamentals](../../articles/active-directory/fundamentals/whatis.md).

‎articles/deployment-environments/toc.yml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -43,6 +43,8 @@ items:
4343
href: how-to-configure-project-admin.md
4444
- name: Provide access to developers
4545
href: how-to-configure-deployment-environments-user.md
46+
- name: Authenticate to REST APIs
47+
href: how-to-authenticate.md
4648
- name: Manage environments as a developer
4749
href: how-to-manage-environments.md
4850
- name: Install Azure CLI dev center extension

‎articles/dev-box/how-to-authenticate.md

Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
1+
---
2+
title: Authenticate to Microsoft Dev Box REST APIs
3+
description: Learn how to authenticate to Microsoft Dev Box REST APIs.
4+
ms.service: dev-box
5+
ms.custom: ignite-2022
6+
ms.topic: conceptual
7+
ms.author: chrismiller
8+
author: chrismiller
9+
ms.date: 09/07/2023
10+
---
11+
# Authenticating to Microsoft Dev Box REST APIs
12+
13+
> [!TIP]
14+
> Before authenticating, ensure that the user or identity has the appropriate permissions to perform the desired action. For more information, see [configuring project admins](./how-to-project-admin.md) and [configuring Dev Box users](./how-to-dev-box-user.md).
15+
16+
17+
## Using Azure AD authentication for REST APIs
18+
19+
Use the following procedures to authenticate with Azure AD. You can follow along in [Azure Cloud Shell](../../articles/cloud-shell/quickstart.md), on an Azure virtual machine, or on your local machine.
20+
21+
### Sign in to the user's Azure subscription
22+
23+
Start by authenticating with Azure AD by using the Azure CLI. This step isn't required in Azure Cloud Shell.
24+
25+
```azurecli
26+
az login
27+
```
28+
29+
The command opens a browser window to the Azure AD authentication page. It requires you to give your Azure AD user ID and password.
30+
31+
Next, set the correct subscription context. If you authenticate from an incorrect subscription or tenant you may receive unexpected 403 Forbidden errors.
32+
33+
```azurecli
34+
az account set --subscription <subscription_id>
35+
```
36+
37+
38+
### Retrieve the Azure AD access token
39+
40+
Use the Azure CLI to acquire an access token for the Azure AD authenticated user.
41+
Note that the resource ID is different depending on if you are accessing administrator (control plane) APIs or developer (data plane) APIs.
42+
43+
For administrator APIs, use the following command:
44+
```azurecli-interactive
45+
az account get-access-token
46+
```
47+
48+
For developer APIs, use the following command:
49+
```azurecli-interactive
50+
az account get-access-token --resource https://devcenter.azure.com
51+
```
52+
53+
After authentication is successful, Azure AD returns an access token for current Azure subscription:
54+
55+
```json
56+
{
57+
"accessToken": "[TOKEN]",
58+
"expiresOn": "[expiration_date_and_time]",
59+
"subscription": "[subscription_id]",
60+
"tenant": "[tenant_id]",
61+
"tokenType": "Bearer"
62+
}
63+
```
64+
65+
The token is a Base64 string. The token is valid for at least 5 minutes with the maximum of 90 minutes. The expiresOn defines the actual token expiration time.
66+
67+
> [!TIP]
68+
> Developer API tokens for the service are encrypted and cannot be decoded using JWT decoding tools. They can only be processed by the service.
69+
70+
71+
### Using a bearer token to access REST APIs
72+
To access REST APIs, you must set the Authorization header on your request. The header value should be the string `Bearer` followed by a space and the token you received in the previous step.
73+
74+
## Next steps
75+
- Review [Azure Active Directory fundamentals](../../articles/active-directory/fundamentals/whatis.md).

‎articles/dev-box/toc.yml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -37,6 +37,8 @@ items:
3737
href: how-to-project-admin.md
3838
- name: Provide access to dev box users
3939
href: how-to-dev-box-user.md
40+
- name: Authenticate to REST APIs
41+
href: how-to-authenticate.md
4042
- name: Configure an Azure compute gallery
4143
href: how-to-configure-azure-compute-gallery.md
4244
- name: Manage a dev center

0 commit comments

Comments
 (0)