Skip to content

Commit d4bb0b8

Browse files
jmprieurjmprieur
authored
Improving the README.md for: (#82)
- 1-1-MyOrg - 1-2-AnyOrg - 1-3-AnyOrgOrPersonal Adding incremental READMEs for - 1-2-AnyOrg - 1-3-AnyOrgOrPersonal
1 parent 2186451 commit d4bb0b8

File tree

5 files changed

+271
-87
lines changed

5 files changed

+271
-87
lines changed

‎1-WebApp-OIDC/1-1-MyOrg/README.md

Lines changed: 26 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ level: 100
66
client: ASP.NET Core Web App
77
endpoint: AAD v2.0
88
---
9-
# Build an ASP.NET Core Web app signing-in users with the Microsoft identity platform
9+
# An ASP.NET Core Web app signing-in users with the Microsoft identity platform in your organization
1010

1111
> This sample is for Azure AD, not Azure AD B2C. See [active-directory-b2c-dotnetcore-webapp](https://github.com/Azure-Samples/active-directory-b2c-dotnetcore-webapp), until we incorporate the B2C variation in the tutorial.
1212
@@ -18,7 +18,8 @@ This sample shows how to build a .NET Core 2.2 MVC Web app that uses OpenID Conn
1818

1919
![Sign in with Azure AD](ReadmeFiles/sign-in.png)
2020

21-
> This is the first phase of a set of tutorials. Once you understand how to sign-in users in an ASP.NET Core Web App with Open Id Connect, can learn how to enable your [Web App to call a Web API on behalf of the signed-in user](../../2-WebApp-graph-user) in a later chapter
21+
> This is the first chapter of this ASP.NET Core Web App tutorial. Once you understand how to sign-in users in an ASP.NET Core Web App with Open Id Connect, can learn how to enable your [Web App to call a Web API on behalf of the signed-in user](../../2-WebApp-graph-user) in a later chapter.
22+
You can also sign-in users in any or several Azure Active Directory organizations, and even with Microsoft personal accounts or social identities. For more details the parent directory's [Readme.md](../Readme.md)
2223

2324
## How to run this sample
2425

@@ -35,15 +36,15 @@ There is one project in this sample. To register it, you can:
3536
1. On Windows run PowerShell and navigate to the solution's folder
3637
2. In PowerShell run:
3738

38-
```PowerShell
39-
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope Process -Force
40-
```
39+
```PowerShell
40+
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope Process -Force
41+
```
4142
4243
3. Run the script to create your Azure AD application and configure the code of the sample application accordinly
4344
44-
```PowerShell
45-
.\AppCreationScripts\Configure.ps1
46-
```
45+
```PowerShell
46+
.\AppCreationScripts\Configure.ps1
47+
```
4748
4849
> Other ways of running the scripts are described in [App Creation Scripts](./AppCreationScripts/AppCreationScripts.md)
4950
@@ -75,8 +76,8 @@ As a first step you'll need to:
7576
- `https://localhost:44321/signin-oidc`
7677
- In the **Advanced settings** section set **Logout URL** to `https://localhost:44321/signout-oidc`
7778
- In the **Advanced settings** | **Implicit grant** section, check **ID tokens** as this sample requires
78-
the [Implicit grant flow](https://docs.microsoft.com/en-us/azure/active-directory/develop/v2-oauth2-implicit-grant-flow) to be enabled to
79-
sign-in the user, and call an API.
79+
the [Implicit grant flow](https://docs.microsoft.com/azure/active-directory/develop/v2-oauth2-implicit-grant-flow) to be enabled to
80+
sign-in the user.
8081
1. Select **Save**.
8182
8283
> Note that unless the Web App calls a Web API, no certificate or secret is needed.
@@ -120,24 +121,24 @@ cd "1-WebApp-OIDC\1-1-MyOrg"
120121
121122
- at the top of the file, add the following using directive:
122123
123-
```CSharp
124-
using Microsoft.Identity.Web;
125-
```
124+
```CSharp
125+
using Microsoft.Identity.Web;
126+
```
126127
127128
- in the `ConfigureServices` method, replace the two following lines:
128129
129130
```CSharp
130-
services.AddAuthentication(AzureADDefaults.AuthenticationScheme)
131-
.AddAzureAD(options => Configuration.Bind("AzureAd", options));
131+
services.AddAuthentication(AzureADDefaults.AuthenticationScheme)
132+
.AddAzureAD(options => Configuration.Bind("AzureAd", options));
132133
```
133134
134135
by this line:
135136
136137
```CSharp
137-
services.AddAzureAdV2Authentication(Configuration);
138+
services.AddAzureAdV2Authentication(Configuration);
138139
```
139140
140-
This enables your application to use the Microsoft identity platform (fomerly Azure AD v2.0) endpoint. This endpoint is capable of signing-in users both with their Work and School and Microsoft Personal accounts.
141+
This enables your application to use the Microsoft identity platform (formerly Azure AD v2.0) endpoint. This endpoint is capable of signing-in users both with their Work and School and Microsoft Personal accounts.
141142
142143
1. Change the `Properties\launchSettings.json` file to ensure that you start your web app from <https://localhost:44321> as registered. For this:
143144
- update the `sslPort` of the `iisSettings` section to be `44321`
@@ -149,7 +150,6 @@ cd "1-WebApp-OIDC\1-1-MyOrg"
149150
150151
2. Open your web browser and make a request to the app. Accept the IIS Express SSL certificate if needed. The app immediately attempts to authenticate you via the Azure AD v2 endpoint. Sign in with your personal account or with work or school account.
151152
152-
> Did the sample not work for you as expected? Did you encounter issues trying this sample? Then please reach out to us using the [GitHub Issues](../../../../issues) page.
153153
154154
## Toubleshooting
155155
@@ -159,6 +159,8 @@ ASP.NET core applications create session cookies that represent the identity of
159159
160160
If your web site needs to be accessed from users using iOS 12, you probably want to disable the SameSite protection, but also ensure that state changes are protected with CSRF anti-forgery mecanism. See the how to fix section of [Microsoft Security Advisory: iOS12 breaks social, WSFed and OIDC logins #4647](https://github.com/aspnet/AspNetCore/issues/4647)
161161
162+
> Did the sample not work for you as expected? Did you encounter issues trying this sample? Then please reach out to us using the [GitHub Issues](../../../../issues) page.
163+
162164
## About The code
163165
164166
This sample shows how to use the OpenID Connect ASP.NET Core middleware to sign in users from a single Azure AD tenant. The middleware is initialized in the `Startup.cs` file by passing it the Client ID of the app, and the URL of the Azure AD tenant where the app is registered. These values are read from the `appsettings.json` file. The middleware takes care of:
@@ -169,18 +171,20 @@ This sample shows how to use the OpenID Connect ASP.NET Core middleware to sign
169171

170172
You can trigger the middleware to send an OpenID Connect sign-in request by decorating a class or method with the `[Authorize]` attribute or by issuing a challenge (see the [AccountController.cs](https://github.com/aspnet/AspNetCore/blob/master/src/Azure/AzureAD/Authentication.AzureAD.UI/src/Areas/AzureAD/Controllers/AccountController.cs) file which is part of ASP.NET Core):
171173

172-
173174
The middleware in this project is created as a part of the open-source [ASP.NET Core Security](https://github.com/aspnet/aspnetcore) project.
174175

175176
These steps are encapsulated in the [Microsoft.Identity.Web](..\..\Microsoft.Identity.Web) project, and in particular in the [StartupHelper.cs](..\..\Microsoft.Identity.Web\StartupHelper.cs) file
176177

177178
## Next steps
178-
179-
- Learn how to enable [any organization](../1-2-AnyOrg) or [any Microsoft accounts](../1-3-AnyOrgOrPersonal) to sign-in
180-
- Learn how to enable your [Web App to call a Web API on behalf of the signed-in user](../../2-WebApp-graph-user)
179+
Learn how to:
180+
- Change your app to sign-in users from [any organization](../1-2-AnyOrg/README-1-1-to-1-2.md) or [any Microsoft accounts](../1-3-AnyOrgOrPersonal/README-1-1-to-1-3.md)
181+
- Enable users from [National clouds](../1-4-Sovereign) to sign-in to your application
182+
- enable your [Web App to call a Web API on behalf of the signed-in user](../../2-WebApp-graph-user)
181183

182184
## Learn more
183185

186+
To understand more about token validation, see
187+
- [Validating tokens](https://github.com/AzureAD/azure-activedirectory-identitymodel-extensions-for-dotnet/wiki/ValidatingTokens)
184188
To understand more about app registration, see:
185189

186190
- [Quickstart: Register an application with the Microsoft identity platform (Preview)](https://docs.microsoft.com/azure/active-directory/develop/quickstart-register-app)

‎1-WebApp-OIDC/1-2-AnyOrg/README-1-1-to-1-2.md

Lines changed: 104 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,104 @@
1+
---
2+
services: active-directory
3+
platforms: dotnet
4+
author: jmprieur
5+
level: 100
6+
client: ASP.NET Core Web App
7+
endpoint: AAD v2.0
8+
---
9+
# Change your ASP.NET Core Web app to sign-in users in any org with the Microsoft identity platform
10+
11+
> This sample is for Azure AD, not Azure AD B2C. See [active-directory-b2c-dotnetcore-webapp](https://github.com/Azure-Samples/active-directory-b2c-dotnetcore-webapp), until we incorporate the B2C variation in the tutorial.
12+
13+
![Build badge](https://identitydivision.visualstudio.com/_apis/public/build/definitions/a7934fdd-dcde-4492-a406-7fad6ac00e17/514/badge)
14+
15+
## Scenario
16+
17+
![Sign in with Azure AD](ReadmeFiles/sign-in.png)
18+
19+
> This is the second chapter of the first phase of this ASP.NET Core Web App tutorial. You learnt previously how to build an ASP.NET Core Web app signing-in users with the Microsoft identity platform in [your organization](../1-1-MyOrg). This chapter describes how to change that application to enable users to sign-in from any organization.
20+
>
21+
> If you are not interested in the differentials, but want to understand all the steps, read the full [Readme.md](./Readme.md)
22+
23+
## Enable users from any organization to sign-in to your Web app
24+
25+
### Changes to the application registration
26+
27+
Your application was registered to sign-in users in [your organization](../1-1-MyOrg) only. To enable users signing-in from any organization, you need to change the app registration in the Azure portal
28+
29+
1. Navigate to the Microsoft identity platform for developers [App registrations](https://go.microsoft.com/fwlink/?linkid=2083908) page.
30+
1. Find your application in the list and select it.
31+
1. In the **Authentication** section for your application, in the **Supported account types** section, select **Accounts in any organizational directory**.
32+
1. Select **Save**
33+
34+
### Changes to the code
35+
36+
You will also need to change the configuration file in the code:
37+
38+
In the **appsettings.json** file, replace the `TenantId` value with `"organizations"`
39+
40+
### Remark: effective sign-in audience
41+
42+
The actual sign-in audience (accounts to sign-in) is the lowest set of what is specified in both the application registration portal and the `appsetttings.json` config file. In other words, you could also achieve the same result by:
43+
44+
- setting in the portal the **Supported account types** to **Accounts in any organizational directory and personal Microsoft accounts (e.g. Skype, Xbox, Outlook.com)** and set the `TenantId` value to `"organizations"` in the **appsettings.json** file
45+
- setting in the portal the **Supported account types** to **Accounts in any organizational directory** and set the `TenantId` value to `"common"` in the **appsettings.json** file
46+
47+
## How to restrict users from specific organizations to sign-in to your web app
48+
49+
In order to restrict users from specific organizations to sign-in to your web app, you'll need to follow the steps above, and customize a bit more the code to restrict the valid token issuers. The token issuers are really the tenanted Azure AD authority which are allowed to issue a token to access your web application.
50+
51+
In the `Startup.cs` file, in the `ConfigureServices` method, after `services.AddAzureAdV2Authentication(Configuration)` add some code to validate specific issuers by overriding the `TokenValidationParameters.IssuerValidator` delegate.
52+
53+
```CSharp
54+
public void ConfigureServices(IServiceCollection services)
55+
{
56+
...
57+
// Sign-in users with the Microsoft identity platform
58+
services.AddAzureAdV2Authentication(Configuration);
59+
60+
// Restrict users to specific belonging to specific tenants
61+
services.Configure<OpenIdConnectOptions>(AzureADDefaults.OpenIdScheme, options =>
62+
{
63+
options.TokenValidationParameters.IssuerValidator = ValidateSpecificIssuers;
64+
});
65+
...
66+
```
67+
68+
An example of code for `ValidateSpecificIssuers` is the following:
69+
70+
```CSharp
71+
private string ValidateSpecificIssuers(string issuer, SecurityToken securityToken,
72+
TokenValidationParameters validationParameters)
73+
{
74+
var validIssuers = GetAcceptedTenantIds()
75+
.Select(tid => $"https://login.microsoftonline.com/{tid}");
76+
if (validIssuers.Contains(issuer))
77+
{
78+
return issuer;
79+
}
80+
else
81+
{
82+
throw new SecurityTokenInvalidIssuerException("The accounts does not belong to one of the tenants that this Web App accepts to sign-in.");
83+
}
84+
}
85+
86+
private string[] GetAcceptedTenantIds()
87+
{
88+
// If you are an ISV who wants to make the Web app available only to certain customers who
89+
// are paying for the service, you might want to fetch this list of accepted tenant ids from
90+
// a database.
91+
// Here for simplicity we just return a hard-coded list of TenantIds.
92+
return new[]
93+
{
94+
"<GUID1>",
95+
"<GUID2>"
96+
};
97+
}
98+
```
99+
100+
## Next steps
101+
102+
- Learn how to enable [any Microsoft accounts](../1-3-AnyOrgOrPersonal) to sign-in to your application
103+
- Learn how to enable users from [National clouds](../1-4-Sovereign) to sign-in to your application
104+
- Learn how to enable your [Web App to call a Web API on behalf of the signed-in user](../../2-WebApp-graph-user)

0 commit comments

Comments
 (0)