Skip to content
This repository was archived by the owner on Jan 23, 2020. It is now read-only.

Commit 0372666

Browse files
author
Tiago Brenck
authored
Merge pull request #48 from Azure-Samples/tibre/updateReadme
Update readme step 2: App registrations
2 parents 537a6e7 + 670741a commit 0372666

File tree

4 files changed

+169
-63
lines changed

4 files changed

+169
-63
lines changed

‎AppCreationScripts/Cleanup.ps1

+27-11
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@ param(
55
[string] $tenantId
66
)
77

8-
if ((Get-Module -ListAvailable -Name "AzureAD") -eq $null) {
8+
if ($null -eq (Get-Module -ListAvailable -Name "AzureAD")) {
99
Install-Module "AzureAD" -Scope CurrentUser
1010
}
1111
Import-Module AzureAD
@@ -44,27 +44,43 @@ This function removes the Azure AD applications for the sample. These applicatio
4444
$tenantId = $creds.Tenant.Id
4545
}
4646
$tenant = Get-AzureADTenantDetail
47-
$tenantName = ($tenant.VerifiedDomains | Where { $_._Default -eq $True }).Name
47+
$tenantName = ($tenant.VerifiedDomains | Where-Object { $_._Default -eq $True }).Name
4848

4949
# Removes the applications
5050
Write-Host "Cleaning-up applications from tenant '$tenantName'"
5151

5252
Write-Host "Removing 'service' (TodoListService-aspnetcore) if needed"
53-
$app=Get-AzureADApplication -Filter "DisplayName eq 'TodoListService-aspnetcore'"
53+
Get-AzureADApplication -Filter "DisplayName eq 'TodoListService-aspnetcore'" | ForEach-Object {Remove-AzureADApplication -ObjectId $_.ObjectId }
54+
$apps = Get-AzureADApplication -Filter "DisplayName eq 'TodoListService-aspnetcore'"
55+
if ($apps)
56+
{
57+
Remove-AzureADApplication -ObjectId $apps.ObjectId
58+
}
5459

55-
if ($app)
60+
foreach ($app in $apps)
5661
{
5762
Remove-AzureADApplication -ObjectId $app.ObjectId
58-
Write-Host "Removed TodoListService-aspnetcore."
63+
Write-Host "Removed TodoListService-aspnetcore.."
64+
}
65+
# also remove service principals of this app
66+
Get-AzureADServicePrincipal -filter "DisplayName eq 'TodoListService-aspnetcore'" | ForEach-Object {Remove-AzureADServicePrincipal -ObjectId $_.Id -Confirm:$false}
67+
68+
Write-Host "Removing 'client' (TodoListWebApp-aspnetcore) if needed"
69+
Get-AzureADApplication -Filter "DisplayName eq 'TodoListWebApp-aspnetcore'" | ForEach-Object {Remove-AzureADApplication -ObjectId $_.ObjectId }
70+
$apps = Get-AzureADApplication -Filter "DisplayName eq 'TodoListWebApp-aspnetcore'"
71+
if ($apps)
72+
{
73+
Remove-AzureADApplication -ObjectId $apps.ObjectId
5974
}
60-
Write-Host "Removing 'client' (TodoListWebApp-aspnetcore) if needed"
61-
$app=Get-AzureADApplication -Filter "DisplayName eq 'TodoListWebApp-aspnetcore'"
6275

63-
if ($app)
76+
foreach ($app in $apps)
6477
{
6578
Remove-AzureADApplication -ObjectId $app.ObjectId
66-
Write-Host "Removed TodoListWebApp-aspnetcore."
67-
}
79+
Write-Host "Removed TodoListWebApp-aspnetcore.."
6880
}
81+
# also remove service principals of this app
82+
Get-AzureADServicePrincipal -filter "DisplayName eq 'TodoListWebApp-aspnetcore'" | ForEach-Object {Remove-AzureADServicePrincipal -ObjectId $_.Id -Confirm:$false}
83+
84+
}
6985

70-
Cleanup -Credential $Credential -tenantId $TenantId
86+
Cleanup -Credential $Credential -tenantId $TenantId

‎AppCreationScripts/Configure.ps1

+3-1
Original file line numberDiff line numberDiff line change
@@ -230,6 +230,7 @@ Function ConfigureApplications
230230
-HomePage "https://localhost:44377/" `
231231
-LogoutUrl "https://localhost:44371/Account/EndSession" `
232232
-ReplyUrls "https://localhost:44377/", "https://localhost:44377/signin-oidc" `
233+
-IdentifierUris "https://$tenantName/TodoListWebApp-aspnetcore" `
233234
-AvailableToOtherTenants $True `
234235
-PasswordCredentials $key `
235236
-Oauth2AllowImplicitFlow $true `
@@ -290,7 +291,8 @@ Function ConfigureApplications
290291
# Update config file for 'client'
291292
$configFile = $pwd.Path + "\..\TodoListWebApp\appsettings.json"
292293
Write-Host "Updating the sample code ($configFile)"
293-
$dictionary = @{ "Domain" = $tenantName;"TenantId" = $tenantId;"ClientId" = $clientAadApplication.AppId;"ClientSecret" = $clientAppKey;"TodoListResourceId" = $serviceIdentifierUri };
294+
295+
$dictionary = @{ "Domain" = $tenantName;"TenantId" = $tenantId;"ClientId" = $clientAadApplication.AppId;"TodoListResourceId" = $serviceIdentifierUri;"ClientSecret" = $clientAppKey; };
294296
UpdateTextFile -configFilePath $configFile -dictionary $dictionary
295297

296298
Add-Content -Value "</tbody></table></body></html>" -Path createdApps.html

‎README.md

+138-50
Original file line numberDiff line numberDiff line change
@@ -54,56 +54,144 @@ From your shell or command line:
5454
git clone https://github.com/Azure-Samples/active-directory-dotnet-webapp-webapi-openidconnect-aspnetcore.git
5555
```
5656

57-
### Step 2: Register the sample with the Azure Active Directory tenant
58-
59-
There are two projects in this sample. Each needs to be registered in your Azure AD tenant.
60-
61-
#### Register the **TodoListService** web API
62-
63-
1. Sign in to the [Azure portal](https://portal.azure.com).
64-
1. On the top bar, click on the signed-in account. Under **Directory**, select the Azure AD tenant where the app will be registered.
65-
1. In the navigation on the left, select **More Services >**. Scroll down and select **Azure Active Directory**.
66-
1. Select **App registrations** and then select **+ New application registration**.
67-
1. Enter *TodoListService* for **Name**. For **Application type**, select *Web app / API'. For **Sign-on URL**, enter the base URL for the sample web API project (by default `https://localhost:44351`). Select the **Create** button to create the app registration.
68-
1. From the list of app registrations, select the newly created application, select **Settings**, and then select **Properties**. Note the following information for reference in later steps:
69-
- The domain of the Azure AD tenant in **App ID URI**. Only the domain, such as `contoso.onmicrosoft.com` is required. Omit the rest of the URI.
70-
- **Application ID**
71-
1. Return to the list of app registrations. Select the **Endpoints** button. Note the GUID (formatted `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`) from any of the endpoint URLs. This is the **Tenant ID**. Omit the rest of the URL.
72-
73-
> [!NOTE]
74-
> By default, the list of app registrations is filtered to *My apps*. To see the app that was just registered, select *All apps*. in the filter dropdown near the top of the blade.
75-
76-
#### Register the TodoListWebApp web application
77-
78-
1. Return to the list of app registrations. Select **+ New application registration**.
79-
1. Enter *TodoListWebApp* for **Name**. For **Application type**, select *Web app / API*. For **Sign-on URL**, enter the base URL for the sample web app project (by default `http://localhost:17945/signin-oidc`). Select the **Create** button to create the app registration.
80-
1. From the list of app registrations, select the newly created application, select **Settings**, and then select **Properties**. Note the **Application ID** for reference in later steps.
81-
1. On the same blade, set the `Logout Url` property to `https://localhost:44371/Account/EndSession`. Select **Save**.
82-
1. From the **Settings** blade, select **Keys**. Add a new key by entering a key description and duration of either 1 year or 2 years. Select **Save**. Note the displayed key value for later steps. Be sure the key value is copied correctly, as it is will not be displayed again. Should the key value be lost, a new key must be created.
83-
4. From the **Settings** blade, select **Required permissions**. Select **+ Add**, and then select **Select an API**. Type *TodoListService* in the textbox and press **Enter**. Select the web API from the list and then select the **Select** button. Select **Select Permissions**. Tick the checkbox next to **Access TodoListService** and then select the **Select** button. Select the **Done** button.
84-
5. In the **Settings** blade, under **API Access**, select **Required permissions**. Click on the **Grant Permissions** and when prompted press **Yes**. Once the web app is granted access to the webapi you should see the following message: *Successfully granted permissions to the application for your account. To grant permissions for all users, please have an admin consent to the application.*
85-
86-
### Step 3: Configure the sample to use the Azure AD tenant
87-
88-
#### Configure the TodoListService project
89-
90-
1. Open the solution in Visual Studio.
91-
1. In the **TodoListService** project, open the `appsettings.json` file.
92-
1. Find the `Domain` property and replace the value with the AAD tenant domain.
93-
1. Find the `TenantId` property and replace the value with the **Tenant ID**.
94-
1. Find the `ClientId` property and replace the value with the **Application ID** property of the TodoListService application.
95-
96-
#### Configure the TodoListWebApp project
97-
98-
> [!WARNING]
99-
> Follow these steps carefully. The **Application ID** property of both app registrations are used below.
100-
101-
1. In the **TodoListWebApp** project, open the `appsettings.json` file.
102-
1. Find the `Domain` property and replace the value with the AAD tenant domain.
103-
1. Find the `TenantId` property and replace the value with the **Tenant ID**.
104-
1. Find the `ClientId` property and replace the value with the **Application ID** of the *TodoListWebApp* app.
105-
1. Find the `ClientSecret` and replace the value with the key value for the *TodoListWebApp* app.
106-
1. Find the `TodoListResourceId` property and replace the value with the **Application ID** of the *TodoListService* app
57+
### Step 2: Register the sample application with your Azure Active Directory tenant
58+
59+
There are two projects in this sample. Each needs to be separately registered in your Azure AD tenant. To register these projects, you can:
60+
61+
- either follow the steps [Step 2: Register the sample with your Azure Active Directory tenant](#step-2-register-the-sample-with-your-azure-active-directory-tenant) and [Step 3: Configure the sample to use your Azure AD tenant](#choose-the-azure-ad-tenant-where-you-want-to-create-your-applications)
62+
- or use PowerShell scripts that:
63+
- **automatically** creates the Azure AD applications and related objects (passwords, permissions, dependencies) for you
64+
- modify the Visual Studio projects' configuration files.
65+
66+
If you want to use this automation:
67+
68+
1. On Windows, run PowerShell and navigate to the root of the cloned directory
69+
1. In PowerShell run:
70+
71+
```PowerShell
72+
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope Process -Force
73+
```
74+
75+
1. Run the script to create your Azure AD application and configure the code of the sample application accordingly.
76+
1. In PowerShell run:
77+
78+
```PowerShell
79+
.\AppCreationScripts\Configure.ps1
80+
```
81+
82+
> Other ways of running the scripts are described in [App Creation Scripts](./AppCreationScripts/AppCreationScripts.md)
83+
84+
1. Open the Visual Studio solution and click start to run the code.
85+
86+
If you don't want to use this automation, follow the steps below.
87+
88+
#### Choose the Azure AD tenant where you want to create your applications
89+
90+
As a first step you'll need to:
91+
92+
1. Sign in to the [Azure portal](https://portal.azure.com) using either a work or school account or a personal Microsoft account.
93+
1. If your account is present in more than one Azure AD tenant, select your profile at the top right corner in the menu on top of the page, and then **switch directory**.
94+
Change your portal session to the desired Azure AD tenant.
95+
96+
#### Register the service app (TodoListService-aspnetcore)
97+
98+
1. Navigate to the Microsoft identity platform for developers [App registrations](https://go.microsoft.com/fwlink/?linkid=2083908) page.
99+
1. Select **New registration**.
100+
1. When the **Register an application page** appears, enter your application's registration information:
101+
- In the **Name** section, enter a meaningful application name that will be displayed to users of the app, for example `TodoListService-aspnetcore`.
102+
- Change **Supported account types** to **Accounts in any organizational directory**.
103+
- In the Redirect URI (optional) section, select **Web** in the combo-box and enter the following redirect URIs: `https://localhost:44351/`.
104+
1. Select **Register** to create the application.
105+
1. On the app **Overview** page, find the **Application (client) ID** value and record it for later. You'll need it to configure the Visual Studio configuration file for this project.
106+
1. Select the **API permissions** section
107+
- Click the **Add a permission** button and then,
108+
- Ensure that the **Microsoft APIs** tab is selected
109+
- In the *Commonly used Microsoft APIs* section, click on **Microsoft Graph**
110+
- In the **Delegated permissions** section, ensure that the right permissions are checked: **User.Read**. Use the search box if necessary.
111+
- Select the **Add permissions** button
112+
113+
1. Select the **Expose an API** section, and:
114+
- Select **Add a scope**
115+
- Accept the proposed Application ID URI (api://{clientId}) by selecting **Save and Continue**
116+
- Enter the following parameters
117+
- for **Scope name** use `user_impersonation`
118+
- Keep `Admins and users` for **Who can consent**
119+
- in **Admin consent display name** type `Access TodoListService-aspnetcore as a user`
120+
- in **Admin consent description** type `Accesses the TodoListService-aspnetcore Web API as a user`
121+
- in **User consent display name** type `Access TodoListService-aspnetcore as a user`
122+
- in **User consent description** type `Accesses the TodoListService-aspnetcore Web API as a user`
123+
- Keep **State** as `Enabled`
124+
- Select **Add scope**
125+
126+
#### Register the client app (TodoListWebApp-aspnetcore)
127+
128+
1. Navigate to the Microsoft identity platform for developers [App registrations](https://go.microsoft.com/fwlink/?linkid=2083908) page.
129+
1. Select **New registration**.
130+
1. When the **Register an application page** appears, enter your application's registration information:
131+
- In the **Name** section, enter a meaningful application name that will be displayed to users of the app, for example `TodoListWebApp-aspnetcore`.
132+
- Change **Supported account types** to **Accounts in any organizational directory**.
133+
> Note that there are more than one redirect URIs. You'll need to add them from the **Authentication** tab later after the app has been created successfully.
134+
1. Select **Register** to create the application.
135+
1. On the app **Overview** page, find the **Application (client) ID** value and record it for later. You'll need it to configure the Visual Studio configuration file for this project.
136+
1. From the app's Overview page, select the **Authentication** section.
137+
- In the Redirect URIs section, select **Web** in the combo-box and enter the following redirect URIs.
138+
- `https://localhost:44377/`
139+
- `https://localhost:44377/signin-oidc`
140+
- In the **Advanced settings** section set **Logout URL** to `https://localhost:44371/Account/EndSession`
141+
- In the **Advanced settings** | **Implicit grant** section, check **ID tokens** and **Access Tokens** as this sample requires
142+
the [Implicit grant flow](https://docs.microsoft.com/en-us/azure/active-directory/develop/v2-oauth2-implicit-grant-flow) to be enabled to
143+
sign-in the user, and call an API.
144+
1. Select **Save**.
145+
1. From the **Certificates & secrets** page, in the **Client secrets** section, choose **New client secret**:
146+
147+
- Type a key description (of instance `app secret`),
148+
- Select a key duration of either **In 1 year**, **In 2 years**, or **Never Expires**.
149+
- When you press the **Add** button, the key value will be displayed, copy, and save the value in a safe location.
150+
- You'll need this key later to configure the project in Visual Studio. This key value will not be displayed again, nor retrievable by any other means,
151+
so record it as soon as it is visible from the Azure portal.
152+
1. Select the **API permissions** section
153+
- Click the **Add a permission** button and then:
154+
- Ensure that the **My APIs** tab is selected
155+
- In the list of APIs, select the API `TodoListService-aspnetcore`.
156+
- In the **Delegated permissions** section, ensure that the right permissions are checked: **user_impersonation**.
157+
- Select the **Add permissions** button.
158+
159+
#### Configure authorized client applications for service (TodoListService-aspnetcore)
160+
161+
For the middle tier web API (`TodoListService-aspnetcore`) to be able to call the downstream web APIs, the user must grant the middle tier permission to do so in the form of consent.
162+
However, since the middle tier has no interactive UI of its own, you need to explicitly bind the client app registration in Azure AD, with the registration for the web API.
163+
This binding merges the consent required by both the client and middle tier into a single dialog, which will be presented to the user by the client.
164+
You can do so by adding the "Client ID" of the client app, to the manifest of the web API in the `knownClientApplications` property. Here's how:
165+
166+
1. In the [Azure portal](https://portal.azure.com), navigate to your `TodoListService-aspnetcore` app registration, and in the **Expose an API** section, click on **Add a client application**.
167+
Input the client ID of the client application (`TodoListWebApp-aspnetcore`) and check **user_impersonation** for authorized scopes.
168+
1. Click **Add application**
169+
170+
### Step 3: Configure the sample to use your Azure AD tenant
171+
172+
In the steps below, "ClientID" is the same as "Application ID" or "AppId".
173+
174+
Open the solution in Visual Studio to configure the projects
175+
176+
#### Configure the service project
177+
178+
> Note: if you used the setup scripts, the changes below will have been applied for you
179+
180+
1. Open the `TodoListService\appsettings.json` file
181+
1. Find the app key `Domain` and replace the existing value with your Azure AD tenant name.
182+
1. Find the app key `TenantId` and replace the existing value with your Azure AD tenant ID.
183+
1. Find the app key `ClientId` and replace the existing value with the application ID (clientId) of the `TodoListService-aspnetcore` application copied from the Azure portal.
184+
185+
#### Configure the client project
186+
187+
> Note: if you used the setup scripts, the changes below will have been applied for you
188+
189+
1. Open the `TodoListWebApp\appsettings.json` file
190+
1. Find the app key `Domain` and replace the existing value with your Azure AD tenant name.
191+
1. Find the app key `TenantId` and replace the existing value with your Azure AD tenant ID.
192+
1. Find the app key `ClientId` and replace the existing value with the application ID (clientId) of the `TodoListWebApp-aspnetcore` application copied from the Azure portal.
193+
1. Find the app key `ClientSecret` and replace the existing value with the key you saved during the creation of the `TodoListWebApp-aspnetcore` app, in the Azure portal.
194+
1. Find the app key `TodoListResourceId` and replace the existing value with `api://{TodoListService_ClientId}`.
107195

108196
### Step 4: Run the sample
109197

‎TodoListWebApp/appsettings.json

+1-1
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@
1111
"ClientSecret": "[Enter the Client Secret (Application password) added from the Keys section for the application in the Azure portal]",
1212

1313
// Coordinates of the TodoListService
14-
"TodoListResourceId": "[Enter the Client Id (Application ID) of the TodoListService, obtained from the Azure portal), e.g. 11111111-1111-1111-11111111111111111]", // ClientId of the TodoList Service
14+
"TodoListResourceId": "[Enter the Client Id (Application ID) of the TodoListService, obtained from the Azure portal), e.g. 11111111-1111-1111-11111111111111111]",
1515
"TodoListBaseAddress": "https://localhost:44351"
1616
},
1717
"Logging": {

0 commit comments

Comments
 (0)