You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: articles/ai-services/immersive-reader/how-to-create-immersive-reader.md
+34-40Lines changed: 34 additions & 40 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,27 +1,24 @@
1
1
---
2
-
title: "Create an Immersive Reader Resource"
2
+
title: Create an Immersive Reader resource
3
3
titleSuffix: Azure AI services
4
-
description: This article shows you how to create a new Immersive Reader resource with a custom subdomain and then configure Microsoft Entra ID in your Azure tenant.
4
+
description: Learn how to create a new Immersive Reader resource with a custom subdomain and then configure Microsoft Entra ID in your Azure tenant.
5
5
#services: cognitive-services
6
6
author: rwallerms
7
7
manager: nitinme
8
8
ms.service: azure-ai-immersive-reader
9
9
ms.custom: devx-track-azurecli
10
10
ms.topic: how-to
11
-
ms.date: 03/31/2023
11
+
ms.date: 02/12/2024
12
12
ms.author: rwaller
13
13
---
14
14
15
15
# Create an Immersive Reader resource and configure Microsoft Entra authentication
16
16
17
-
In this article, we provide a script that creates an Immersive Reader resource and configure Microsoft Entra authentication. Each time an Immersive Reader resource is created, whether with this script or in the portal, it must also be configured with Microsoft Entra permissions.
17
+
This article explains how to create an Immersive Reader resource by using the provided script. This script also configures Microsoft Entra authentication. Each time an Immersive Reader resource is created, whether with this script or in the portal, it must be configured with Microsoft Entra permissions.
18
18
19
-
The script is designed to create and configure all the necessary Immersive Reader and Microsoft Entra resources for you all in one step. However, you can also just configure Microsoft Entra authentication for an existing Immersive Reader resource, if for instance, you happen to have already created one in the Azure portal.
19
+
The script creates and configures all the necessary Immersive Reader and Microsoft Entra resources for you. However, you can also configure Microsoft Entra authentication for an existing Immersive Reader resource, if you already created one in the Azure portal. The script first looks for existing Immersive Reader and Microsoft Entra resources in your subscription, and creates them only if they don't already exist.
20
20
21
-
For some customers, it may be necessary to create multiple Immersive Reader resources, for development vs. production, or perhaps for multiple different regions your service is deployed in. For those cases, you can come back and use the script multiple times to create different Immersive Reader resources and get them configured with the Microsoft Entra permissions.
22
-
23
-
The script is designed to be flexible. It first looks for existing Immersive Reader and Microsoft Entra resources in your subscription, and creates them only as necessary if they don't already exist. If it's your first time creating an Immersive Reader resource, the script does everything you need. If you want to use it just to configure Microsoft Entra ID for an existing Immersive Reader resource that was created in the portal, it does that too.
24
-
It can also be used to create and configure multiple Immersive Reader resources.
21
+
For some customers, it might be necessary to create multiple Immersive Reader resources, for development versus production, or perhaps for different regions where your service is deployed. For those cases, you can come back and use the script multiple times to create different Immersive Reader resources and get them configured with Microsoft Entra permissions.
25
22
26
23
## Permissions
27
24
@@ -31,17 +28,17 @@ If you aren't an owner, the following scope-specific permissions are required:
31
28
32
29
***Contributor**. You need to have at least a Contributor role associated with the Azure subscription:
33
30
34
-
:::image type="content" source="media/contributor-role.png" alt-text="Screenshot of contributor built-in role description.":::
31
+
:::image type="content" source="media/contributor-role.png" alt-text="Screenshot of contributor built-in role description.":::
35
32
36
33
***Application Developer**. You need to have at least an Application Developer role associated in Microsoft Entra ID:
:::image type="content" source="media/application-developer-role.png" alt-text="Screenshot of the developer built-in role description.":::
39
36
40
-
For more information, _see_[Microsoft Entra built-in roles](../../active-directory/roles/permissions-reference.md#application-developer)
37
+
For more information, see[Microsoft Entra built-in roles](../../active-directory/roles/permissions-reference.md#application-developer).
41
38
42
-
## Set up PowerShell environment
39
+
## Set up PowerShell resources
43
40
44
-
1. Start by opening the [Azure Cloud Shell](../../cloud-shell/overview.md). Ensure that Cloud Shell is set to PowerShell in the upper-left hand dropdown or by typing `pwsh`.
41
+
1. Start by opening the [Azure Cloud Shell](../../cloud-shell/overview.md). Ensure that Cloud Shell is set to **PowerShell** in the upper-left hand dropdown or by typing `pwsh`.
45
42
46
43
1. Copy and paste the following code snippet into the shell.
47
44
@@ -101,23 +98,23 @@ For more information, _see_ [Microsoft Entra built-in roles](../../active-direct
101
98
Write-Host "Immersive Reader resource created successfully"
102
99
}
103
100
104
-
# Create an Azure Active Directory app if it doesn't already exist
101
+
# Create an Microsoft Entra app if it doesn't already exist
105
102
$clientId = az ad app show --id $AADAppIdentifierUri --query "appId" -o tsv
106
103
if (-not $clientId) {
107
-
Write-Host "Creating new Azure Active Directory app"
104
+
Write-Host "Creating new Microsoft Entra app"
108
105
$clientId = az ad app create --display-name $AADAppDisplayName --identifier-uris $AADAppIdentifierUri --query "appId" -o tsv
109
106
if (-not $clientId) {
110
-
throw "Error: Failed to create Azure Active Directory application"
107
+
throw "Error: Failed to create Microsoft Entra application"
111
108
}
112
-
Write-Host "Azure Active Directory application created successfully."
109
+
Write-Host "Microsoft Entra application created successfully."
113
110
114
111
$clientSecret = az ad app credential reset --id $clientId --end-date "$AADAppClientSecretExpiration" --query "password" | % { $_.Trim('"') }
115
112
if (-not $clientSecret) {
116
-
throw "Error: Failed to create Azure Active Directory application client secret"
113
+
throw "Error: Failed to create Microsoft Entra application client secret"
117
114
}
118
-
Write-Host "Azure Active Directory application client secret created successfully."
115
+
Write-Host "Microsoft Entra application client secret created successfully."
119
116
120
-
Write-Host "NOTE: To manage your Active Directory application client secrets after this Immersive Reader Resource has been created please visit https://portal.azure.com and go to Home -> Azure Active Directory -> App Registrations -> (your app) '$AADAppDisplayName' -> Certificates and Secrets blade -> Client Secrets section" -ForegroundColor Yellow
117
+
Write-Host "NOTE: To manage your Microsoft Entra application client secrets after this Immersive Reader Resource has been created please visit https://portal.azure.com and go to Home -> Microsoft Entra ID -> App Registrations -> (your app) '$AADAppDisplayName' -> Certificates and Secrets blade -> Client Secrets section" -ForegroundColor Yellow
121
118
}
122
119
123
120
# Create a service principal if it doesn't already exist
@@ -144,10 +141,10 @@ For more information, _see_ [Microsoft Entra built-in roles](../../active-direct
144
141
}
145
142
Write-Host "Service principal access granted successfully"
146
143
147
-
# Grab the tenant ID, which is needed when obtaining an Azure AD token
144
+
# Grab the tenant ID, which is needed when obtaining a Microsoft Entra token
148
145
$tenantId = az account show --query "tenantId" -o tsv
149
146
150
-
# Collect the information needed to obtain an Azure AD token into one object
147
+
# Collect the information needed to obtain a Microsoft Entra token into one object
151
148
$result = @{}
152
149
$result.TenantId = $tenantId
153
150
$result.ClientId = $clientId
@@ -159,11 +156,11 @@ For more information, _see_ [Microsoft Entra built-in roles](../../active-direct
159
156
Write-Host "*****"
160
157
if($clientSecret -ne $null) {
161
158
162
-
Write-Host "This function has created a client secret (password) for you. This secret is used when calling Azure Active Directory to fetch access tokens."
163
-
Write-Host "This is the only time you will ever see the client secret for your Azure Active Directory application, so save it now." -ForegroundColor Yellow
159
+
Write-Host "This function has created a client secret (password) for you. This secret is used when calling Microsoft Entra to fetch access tokens."
160
+
Write-Host "This is the only time you will ever see the client secret for your Microsoft Entra application, so save it now." -ForegroundColor Yellow
164
161
}
165
162
else{
166
-
Write-Host "You will need to retrieve the ClientSecret from your original run of this function that created it. If you don't have it, you will need to go create a new client secret for your Azure Active Directory application. Please visit https://portal.azure.com and go to Home -> Azure Active Directory -> App Registrations -> (your app) '$AADAppDisplayName' -> Certificates and Secrets blade -> Client Secrets section." -ForegroundColor Yellow
163
+
Write-Host "You will need to retrieve the ClientSecret from your original run of this function that created it. If you don't have it, you will need to go create a new client secret for your Microsoft Entra application. Please visit https://portal.azure.com and go to Home -> Microsoft Entra ID -> App Registrations -> (your app) '$AADAppDisplayName' -> Certificates and Secrets blade -> Client Secrets section." -ForegroundColor Yellow
167
164
}
168
165
Write-Host "*****`n"
169
166
Write-Output (ConvertTo-Json $result)
@@ -173,10 +170,10 @@ For more information, _see_ [Microsoft Entra built-in roles](../../active-direct
173
170
1. Run the function `Create-ImmersiveReaderResource`, supplying the '<PARAMETER_VALUES>' placeholders with your own values as appropriate.
The full command looks something like the following. Here we have put each parameter on its own line for clarity, so you can see the whole command. __Do not copy or use this command as-is.__ Copy and use the command with your own values. This example has dummy values for the '<PARAMETER_VALUES>'. Yours may be different, as you come up with your own names for these values.
176
+
The full command looks something like the following. Here we put each parameter on its own line for clarity, so you can see the whole command. __Do not copy or use this command as-is.__ Copy and use the command with your own values. This example has dummy values for the `<PARAMETER_VALUES>`. Yours might be different, as you come up with your own names for these values.
180
177
181
178
```
182
179
Create-ImmersiveReaderResource
@@ -195,19 +192,19 @@ For more information, _see_ [Microsoft Entra built-in roles](../../active-direct
195
192
| Parameter | Comments |
196
193
| --- | --- |
197
194
| SubscriptionName |Name of the Azure subscription to use for your Immersive Reader resource. You must have a subscription in order to create a resource. |
198
-
| ResourceName | Must be alphanumeric, and may contain '-', as long as the '-' isn't the first or last character. Length may not exceed 63 characters.|
199
-
| ResourceSubdomain |A custom subdomain is needed for your Immersive Reader resource. The subdomain is used by the SDK when calling the Immersive Reader service to launch the Reader. The subdomain must be globally unique. The subdomain must be alphanumeric, and may contain '-', as long as the '-' isn't the first or last character. Length may not exceed 63 characters. This parameter is optional if the resource already exists. |
200
-
| ResourceSKU |Options: `S0` (Standard tier) or `S1` (Education/Nonprofit organizations). Visit our [Azure AI services pricing page](https://azure.microsoft.com/pricing/details/cognitive-services/immersive-reader/) to learn more about each available SKU. This parameter is optional if the resource already exists. |
195
+
| ResourceName | Must be alphanumeric, and can contain `-`, as long as the `-` isn't the first or last character. Length can't exceed 63 characters.|
196
+
| ResourceSubdomain |A custom subdomain is needed for your Immersive Reader resource. The subdomain is used by the SDK when calling the Immersive Reader service to launch the Reader. The subdomain must be globally unique. The subdomain must be alphanumeric, and can contain `-`, as long as the `-` isn't the first or last character. Length can't exceed 63 characters. This parameter is optional if the resource already exists. |
197
+
| ResourceSKU |Options: `S0` (Standard tier) or `S1` (Education/Nonprofit organizations). To learn more about each available SKU, visit our [Azure AI services pricing page](https://azure.microsoft.com/pricing/details/cognitive-services/immersive-reader/). This parameter is optional if the resource already exists. |
| ResourceGroupName |Resources are created in resource groups within subscriptions. Supply the name of an existing resource group. If the resource group doesn't already exist, a new one with this name is created. |
203
200
| ResourceGroupLocation |If your resource group doesn't exist, you need to supply a location in which to create the group. To find a list of locations, run `az account list-locations`. Use the *name* property (without spaces) of the returned result. This parameter is optional if your resource group already exists. |
204
201
| AADAppDisplayName |The Microsoft Entra application display name. If an existing Microsoft Entra application isn't found, a new one with this name is created. This parameter is optional if the Microsoft Entra application already exists. |
205
202
| AADAppIdentifierUri |The URI for the Microsoft Entra application. If an existing Microsoft Entra application isn't found, a new one with this URI is created. For example, `api://MyOrganizationImmersiveReaderAADApp`. Here we're using the default Microsoft Entra URI scheme prefix of `api://` for compatibility with the [Microsoft Entra policy of using verified domains](../../active-directory/develop/reference-breaking-changes.md#appid-uri-in-single-tenant-applications-will-require-use-of-default-scheme-or-verified-domains). |
206
-
| AADAppClientSecretExpiration |The date or datetime after which your Microsoft Entra Application Client Secret (password) will expire (for example, '2020-12-31T11:59:59+00:00' or '2020-12-31'). This function creates a client secret for you. To manage Microsoft Entra application client secrets after you've created this resource, visit https://portal.azure.com and go to Home -> Microsoft Entra ID -> App Registrations -> (your app) `[AADAppDisplayName]` -> Certificates and Secrets section -> Client Secrets section (as shown in the "Manage your Microsoft Entra application secrets" screenshot).|
203
+
| AADAppClientSecretExpiration |The date or datetime after which your Microsoft Entra Application Client Secret (password) expires (for example, '2020-12-31T11:59:59+00:00' or '2020-12-31'). This function creates a client secret for you. |
207
204
208
-
Manage your Microsoft Entra application secrets
205
+
To manage your Microsoft Entra application client secrets after you create this resource, visit the [Azure portal](https://portal.azure.com) and go to **Home** -> **Microsoft Entra ID** -> **App Registrations** -> (your app) `[AADAppDisplayName]` -> **Certificates and Secrets** section -> **Client Secrets** section.
209
206
210
-
207
+
:::image type="content" source="media/client-secrets-blade.png" alt-text="Screenshot of the Azure portal Certificates and Secrets pane." lightbox="media/client-secrets-blade.png":::
211
208
212
209
1. Copy the JSON output into a text file for later use. The output should look like the following.
213
210
@@ -220,10 +217,7 @@ For more information, _see_ [Microsoft Entra built-in roles](../../active-direct
220
217
}
221
218
```
222
219
223
-
## Next steps
220
+
## Next step
224
221
225
-
* View the [Node.js quickstart](./quickstarts/client-libraries.md?pivots=programming-language-nodejs) to see what else you can do with the Immersive Reader SDK using Node.js
226
-
* View the [Android tutorial](./how-to-launch-immersive-reader.md) to see what else you can do with the Immersive Reader SDK using Java or Kotlin for Android
227
-
* View the [iOS tutorial](./how-to-launch-immersive-reader.md) to see what else you can do with the Immersive Reader SDK using Swift for iOS
228
-
* View the [Python tutorial](./how-to-launch-immersive-reader.md) to see what else you can do with the Immersive Reader SDK using Python
229
-
* Explore the [Immersive Reader SDK](https://github.com/microsoft/immersive-reader-sdk) and the [Immersive Reader SDK Reference](./reference.md)
222
+
> [!div class="nextstepaction"]
223
+
> [How to launch the Immersive Reader](how-to-launch-immersive-reader.md)
0 commit comments