Skip to content

Commit b9baea4

Browse files
ttorblettorble
authored
Merge pull request #221139 from MicrosoftDocs/main
Publish to live, Monday 4 AM PST, 12/12
2 parents efd41fe + d154c3b commit b9baea4

22 files changed

+345
-256
lines changed

‎articles/active-directory/develop/scenario-protected-web-api-app-configuration.md

Lines changed: 17 additions & 78 deletions
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ manager: CelesteDG
88
ms.service: active-directory
99
ms.subservice: develop
1010
ms.topic: conceptual
11-
ms.date: 05/12/2022
11+
ms.date: 12/09/2022
1212
ms.author: jmprieur
1313
#Customer intent: As an application developer, I want to know how to write a protected web API using the Microsoft identity platform for developers.
1414
---
@@ -23,7 +23,7 @@ To configure the code for your protected web API, understand:
2323

2424
## What defines ASP.NET and ASP.NET Core APIs as protected?
2525

26-
Like web apps, the ASP.NET and ASP.NET Core web APIs are protected because their controller actions are prefixed with the **[Authorize]** attribute. The controller actions can be called only if the API is called with an authorized identity.
26+
Like web apps, ASP.NET and ASP.NET Core web APIs are protected because their controller actions are prefixed with the **[Authorize]** attribute. The controller actions can be called only if the API is called with an authorized identity.
2727

2828
Consider the following questions:
2929

@@ -49,7 +49,7 @@ HttpResponseMessage response = await _httpClient.GetAsync(apiUri);
4949
```
5050

5151
> [!IMPORTANT]
52-
> A client application requests the bearer token to the Microsoft identity platform *for the web API*. The web API is the only application that should verify the token and view the claims it contains. Client apps should never try to inspect the claims in tokens.
52+
> A client application requests the bearer token to the Microsoft identity platform *for the web API*. The API is the only application that should verify the token and view the claims it contains. Client apps should never try to inspect the claims in tokens.
5353
>
5454
> In the future, the web API might require that the token be encrypted. This requirement would prevent access for client apps that can view access tokens.
5555
@@ -59,21 +59,17 @@ This section describes how to configure a bearer token.
5959

6060
### Config file
6161

62+
You need to specify the `TenantId` only if you want to accept access tokens from a single tenant (line-of-business app). Otherwise, it can be left as `common`. The different values can be:
63+
- A GUID (Tenant ID = Directory ID)
64+
- `common` can be any organization and personal accounts
65+
- `organizations` can be any organization
66+
- `consumers` are Microsoft personal accounts
67+
6268
```Json
6369
{
6470
"AzureAd": {
6571
"Instance": "https://login.microsoftonline.com/",
66-
"ClientId": "[Client_id-of-web-api-eg-2ec40e65-ba09-4853-bcde-bcb60029e596]",
67-
/*
68-
You need specify the TenantId only if you want to accept access tokens from a single tenant
69-
(line-of-business app).
70-
Otherwise, you can leave them set to common.
71-
This can be:
72-
- A GUID (Tenant ID = Directory ID)
73-
- 'common' (any organization and personal accounts)
74-
- 'organizations' (any organization)
75-
- 'consumers' (Microsoft personal accounts)
76-
*/
72+
"ClientId": "Enter_the_Application_(client)_ID_here"
7773
"TenantId": "common"
7874
},
7975
"Logging": {
@@ -85,19 +81,18 @@ This section describes how to configure a bearer token.
8581
}
8682
```
8783

88-
#### Case where you used a custom App ID URI for your web API
84+
#### Using a custom App ID URI for a web API
8985

90-
If you've accepted the default App ID URI proposed by the Azure portal, you don't need to specify the audience (see [Application ID URI and scopes](scenario-protected-web-api-app-registration.md#scopes-and-the-application-id-uri)). Otherwise, add an `Audience` property whose value is the App ID URI for your web API.
86+
If you've accepted the default App ID URI proposed by the Azure portal, you don't need to specify the audience (see [Application ID URI and scopes](scenario-protected-web-api-app-registration.md#scopes-and-the-application-id-uri)). Otherwise, add an `Audience` property whose value is the App ID URI for your web API. This typically starts with `api://`.
9187

9288
```Json
9389
{
9490
"AzureAd": {
9591
"Instance": "https://login.microsoftonline.com/",
96-
"ClientId": "[Client_id-of-web-api-eg-2ec40e65-ba09-4853-bcde-bcb60029e596]",
92+
"ClientId": "Enter_the_Application_(client)_ID_here",
9793
"TenantId": "common",
98-
"Audience": "custom App ID URI for your web API"
94+
"Audience": "Enter_the_Application_ID_URI_here"
9995
},
100-
// more lines
10196
}
10297
```
10398

@@ -109,7 +104,7 @@ When an app is called on a controller action that holds an **[Authorize]** attri
109104

110105
Microsoft recommends you use the [Microsoft.Identity.Web](https://www.nuget.org/packages/Microsoft.Identity.Web) NuGet package when developing a web API with ASP.NET Core.
111106

112-
_Microsoft.Identity.Web_ provides the glue between ASP.NET Core, the authentication middleware, and the [Microsoft Authentication Library (MSAL)](msal-overview.md) for .NET. It allows for a clearer, more robust developer experience and leverages the power of the Microsoft identity platform and Azure AD B2C.
107+
*Microsoft.Identity.Web* provides the glue between ASP.NET Core, the authentication middleware, and the [Microsoft Authentication Library (MSAL)](msal-overview.md) for .NET. It allows for a clearer, more robust developer experience and leverages the power of the Microsoft identity platform and Azure AD B2C.
113108

114109
#### ASP.NET for .NET 6.0
115110

@@ -124,7 +119,7 @@ dotnet new webapi --auth SingleOrg
124119

125120
**Visual Studio** - To create a web API project in Visual Studio, select **File** > **New** > **Project** > **ASP.NET Core Web API**.
126121

127-
Both the .NET CLI and Visual Studio project templates create a _Program.cs_ file that looks similar this code snippet. Notice the `Microsoft.Identity.Web` using directive and the lines containing authentication and authorization.
122+
Both the .NET CLI and Visual Studio project templates create a *Program.cs* file that looks similar to this code snippet. Notice `Microsoft.Identity.Web` using directive and the lines containing authentication and authorization.
128123

129124
```csharp
130125
using Microsoft.AspNetCore.Authentication;
@@ -161,62 +156,6 @@ app.MapControllers();
161156
app.Run();
162157
```
163158

164-
#### ASP.NET Core 3.1
165-
166-
167-
To create a new web API project by using the Microsoft.Identity.Web-enabled project templates in ASP.NET Core 3.1, see [Microsoft.Identity.Web - Web API project template](https://aka.ms/ms-id-web/webapi-project-templates).
168-
169-
To add Microsoft.Identity.Web to an existing ASP.NET Core 3.1 web API project, add this using directive to your _Program.cs_ file:
170-
171-
ASP.NET Core 3.1 uses the Microsoft.AspNetCore.Authentication.JwtBearer library. The middleware is initialized in the Startup.cs file.
172-
173-
```csharp
174-
using Microsoft.AspNetCore.Authentication.JwtBearer;
175-
```
176-
177-
The middleware is added to the web API by this instruction:
178-
179-
```csharp
180-
// This method gets called by the runtime. Use this method to add services to the container.
181-
public void ConfigureServices(IServiceCollection services)
182-
{
183-
services.AddAuthentication(AzureADDefaults.JwtBearerAuthenticationScheme)
184-
.AddAzureADBearer(options => Configuration.Bind("AzureAd", options));
185-
}
186-
```
187-
188-
Currently, the ASP.NET Core templates create Azure Active Directory (Azure AD) web APIs that sign in users within your organization or any organization. They don't sign in users with personal accounts. However, you can change the templates to use the Microsoft identity platform by using [Microsoft.Identity.Web](https://www.nuget.org/packages/Microsoft.Identity.Web) replacing the code in *Startup.cs*:
189-
190-
```csharp
191-
using Microsoft.Identity.Web;
192-
```
193-
194-
```csharp
195-
public void ConfigureServices(IServiceCollection services)
196-
{
197-
// Adds Microsoft Identity platform (AAD v2.0) support to protect this API
198-
services.AddAuthentication(AzureADDefaults.JwtBearerAuthenticationScheme)
199-
.AddMicrosoftIdentityWebApi(Configuration, "AzureAd");
200-
201-
services.AddControllers();
202-
}
203-
```
204-
205-
Make sure you have `app.UseAuthentication()` and `app.UseAuthorization()` in the `Configure` method.
206-
207-
```csharp
208-
public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
209-
{
210-
// More code here
211-
app.UseAuthentication();
212-
app.UseAuthorization();
213-
214-
// More code here
215-
```
216-
217-
> [!NOTE]
218-
> If you use Microsoft.Identity.Web and don't set the `Audience` in *appsettings.json*, `$"{ClientId}"` is automatically used if you have set the [access token accepted version](scenario-protected-web-api-app-registration.md#accepted-token-version) to `2`, or for Azure AD B2C web APIs.
219-
220159
## Token validation
221160

222161
In the preceding snippet, the JwtBearer middleware, like the OpenID Connect middleware in web apps, validates the token based on the value of `TokenValidationParameters`. The token is decrypted as needed, the claims are extracted, and the signature is verified. The middleware then validates the token by checking for this data:
@@ -246,7 +185,7 @@ This table describes the validators:
246185

247186
#### Customizing token validation
248187

249-
The validators are associated with properties of the **TokenValidationParameters** class. The properties are initialized from the ASP.NET and ASP.NET Core configuration.
188+
The validators are associated with properties of the *TokenValidationParameters* class. The properties are initialized from the ASP.NET and ASP.NET Core configuration.
250189

251190
In most cases, you don't need to change the parameters. Apps that aren't single tenants are exceptions. These web apps accept users from any organization or from personal Microsoft accounts. Issuers in this case must be validated. Microsoft.Identity.Web takes care of the issuer validation as well.
252191

‎articles/active-directory/saas-apps/toc.yml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2539,6 +2539,8 @@
25392539
href: visma-tutorial.md
25402540
- name: VMware Horizon - Unified Access Gateway
25412541
href: vmware-horizon-unified-access-gateway-tutorial.md
2542+
- name: VMware Identity Service
2543+
href: vmware-identity-service-tutorial.md
25422544
- name: Vocoli
25432545
href: vocoli-tutorial.md
25442546
- name: Vodeclic

‎articles/active-directory/saas-apps/vmware-identity-service-tutorial.md

Lines changed: 158 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,158 @@
1+
---
2+
title: Azure Active Directory SSO integration with VMware Identity Service
3+
description: Learn how to configure single sign-on between Azure Active Directory and VMware Identity Service.
4+
services: active-directory
5+
author: jeevansd
6+
manager: CelesteDG
7+
ms.reviewer: CelesteDG
8+
ms.service: active-directory
9+
ms.subservice: saas-app-tutorial
10+
ms.workload: identity
11+
ms.topic: how-to
12+
ms.date: 12/09/2022
13+
ms.author: jeedes
14+
15+
---
16+
17+
# Azure Active Directory SSO integration with VMware Identity Service
18+
19+
In this article, you'll learn how to integrate VMware Identity Service with Azure Active Directory (Azure AD). VMware Identity Service provides integration with Azure AD for VMware products. It uses the SCIM protocol for user and group provisioning and SAML for authentication. When you integrate VMware Identity Service with Azure AD, you can:
20+
21+
* Control in Azure AD who has access to VMware Identity Service.
22+
* Enable your users to be automatically signed-in to VMware Identity Service with their Azure AD accounts.
23+
* Manage your accounts in one central location - the Azure portal.
24+
25+
You'll configure and test Azure AD single sign-on for VMware Identity Service in a test environment. VMware Identity Service supports both **SP** and **IDP** initiated single sign-on and **Just In Time** user provisioning.
26+
27+
## Prerequisites
28+
29+
To integrate Azure Active Directory with VMware Identity Service, you need:
30+
31+
* An Azure AD user account. If you don't already have one, you can [Create an account for free](https://azure.microsoft.com/free/?WT.mc_id=A261C142F).
32+
* One of the following roles: Global Administrator, Cloud Application Administrator, Application Administrator, or owner of the service principal.
33+
* An Azure AD subscription. If you don't have a subscription, you can get a [free account](https://azure.microsoft.com/free/).
34+
* VMware Identity Service single sign-on (SSO) enabled subscription.
35+
36+
## Add application and assign a test user
37+
38+
Before you begin the process of configuring single sign-on, you need to add the VMware Identity Service application from the Azure AD gallery. You need a test user account to assign to the application and test the single sign-on configuration.
39+
40+
### Add VMware Identity Service from the Azure AD gallery
41+
42+
Add VMware Identity Service from the Azure AD application gallery to configure single sign-on with VMware Identity Service. For more information on how to add application from the gallery, see the [Quickstart: Add application from the gallery](../manage-apps/add-application-portal.md).
43+
44+
### Create and assign Azure AD test user
45+
46+
Follow the guidelines in the [create and assign a user account](../manage-apps/add-application-portal-assign-users.md) article to create a test user account in the Azure portal called B.Simon.
47+
48+
Alternatively, you can also use the [Enterprise App Configuration Wizard](https://portal.office.com/AdminPortal/home?Q=Docs#/azureadappintegration). In this wizard, you can add an application to your tenant, add users/groups to the app, and assign roles. The wizard also provides a link to the single sign-on configuration pane in the Azure portal. [Learn more about Microsoft 365 wizards](/microsoft-365/admin/misc/azure-ad-setup-guides).
49+
50+
## Configure Azure AD SSO
51+
52+
Complete the following steps to enable Azure AD single sign-on in the Azure portal.
53+
54+
1. In the Azure portal, on the **VMware Identity Service** application integration page, find the **Manage** section and select **single sign-on**.
55+
1. On the **Select a single sign-on method** page, select **SAML**.
56+
1. On the **Set up single sign-on with SAML** page, select the pencil icon for **Basic SAML Configuration** to edit the settings.
57+
58+
![Screenshot shows how to edit Basic SAML Configuration.](common/edit-urls.png "Basic Configuration")
59+
60+
1. On the **Basic SAML Configuration** section, perform the following steps:
61+
62+
a. In the **Identifier** textbox, type a URL using one of the following patterns:
63+
64+
| **Identifier** |
65+
|-----------|
66+
| `https://<CustomerName>.vmwareidentity.com/SAAS/API/1.0/GET/metadata/sp.xml` |
67+
| `https://<CustomerName>.workspaceoneaccess.com/SAAS/API/1.0/GET/metadata/sp.xml` |
68+
| `https://<CustomerName>.vmwareidentity.asia/SAAS/API/1.0/GET/metadata/sp.xml` |
69+
| `https://<CustomerName>.vmwareidentity.eu/SAAS/API/1.0/GET/metadata/sp.xml` |
70+
| `https://<CustomerName>.vmwareidentity.co.uk/SAAS/API/1.0/GET/metadata/sp.xml` |
71+
| `https://<CustomerName>.vmwareidentity.de/SAAS/API/1.0/GET/metadata/sp.xml` |
72+
| `https://<CustomerName>.vmwareidentity.ca/SAAS/API/1.0/GET/metadata/sp.xml` |
73+
| `https://<CustomerName>.vmwareidentity.com.au/SAAS/API/1.0/GET/metadata/sp.xml` |
74+
| `https://<CustomerName>.vidmpreview.com/SAAS/API/1.0/GET/metadata/sp.xml` |
75+
76+
b. In the **Reply URL** textbox, type a URL using one of the following patterns:
77+
78+
| **Reply URL** |
79+
|-------------|
80+
| `https://<CustomerName>.vmwareidentity.com/SAAS/auth/saml/response` |
81+
| `https://<CustomerName>.workspaceoneaccess.com/SAAS/auth/saml/response` |
82+
| `https://<CustomerName>.vmwareidentity.asia/SAAS/auth/saml/response` |
83+
| `https://<CustomerName>.vmwareidentity.eu/SAAS/auth/saml/response` |
84+
| ` https://<CustomerName>.vmwareidentity.co.uk/SAAS/auth/saml/response` |
85+
| `https://<CustomerName>.vmwareidentity.de/SAAS/auth/saml/response` |
86+
| `https://<CustomerName>.vmwareidentity.ca/SAAS/auth/saml/response` |
87+
| `https://<CustomerName>.vmwareidentity.com.au/SAAS/auth/saml/response` |
88+
| `https://<CustomerName>.vidmpreview.com/SAAS/auth/saml/response` |
89+
90+
1. If you want to configure **SP** initiated SSO, then perform the following step:
91+
92+
In the **Sign on URL** textbox, type a URL using one of the following patterns:
93+
94+
| **Sign on URL** |
95+
|-------------|
96+
| `https://<CustomerName>.vmwareidentity.com` |
97+
| `https://<CustomerName>.workspaceoneaccess.com` |
98+
| `https://<CustomerName>.vmwareidentity.asia` |
99+
| `https://<CustomerName>.vmwareidentity.eu` |
100+
| `https://<CustomerName>.vmwareidentity.co.uk` |
101+
| `https://<CustomerName>.vmwareidentity.de` |
102+
| `https://<CustomerName>.vmwareidentity.ca` |
103+
| `https://<CustomerName>.vmwareidentity.com.au` |
104+
| `https://<CustomerName>.vidmpreview.com` |
105+
106+
> [!Note]
107+
> These values are not the real. Update these values with the actual Identifier, Reply URL and Sign on URL. Contact [VMware Identity Service Client support team](mailto:[email protected]) to get these values. You can also refer to the patterns shown in the **Basic SAML Configuration** section in the Azure portal.
108+
109+
1. VMware Identity Service application expects the SAML assertions in a specific format, which requires you to add custom attribute mappings to your SAML token attributes configuration. The following screenshot shows the list of default attributes.
110+
111+
![Screenshot shows the image of token attributes.](common/default-attributes.png "Image")
112+
113+
1. In addition to above, VMware Identity Service application expects few more attributes to be passed back in SAML response, which are shown below. These attributes are also pre populated but you can review them as per your requirements.
114+
115+
| Name | Source Attribute|
116+
| ------------ | --------- |
117+
| firstName | user.givenname |
118+
| lastName | user.surname |
119+
| userName | user.userprincipalname |
120+
| externalId | user.objectid |
121+
| email | user.mail |
122+
123+
1. On the **Set up single sign-on with SAML** page, in the **SAML Signing Certificate** section, click copy button to copy **App Federation Metadata Url** and save it on your computer.
124+
125+
![Screenshot shows the Certificate download link.](common/copy-metadataurl.png "Certificate")
126+
127+
## Configure VMware Identity Service SSO
128+
129+
To configure single sign-on on **VMware Identity Service SSO** side, you need to send the **App Federation Metadata Url** to [VMware Identity Service SSO support team](mailto:[email protected]). They set this setting to have the SAML SSO connection set properly on both sides.
130+
131+
### Create VMware Identity Service test user
132+
133+
In this section, a user called B.Simon is created in VMware Identity Service. VMware Identity Service supports just-in-time user provisioning, which is enabled by default. There is no action item for you in this section. If a user doesn't already exist in VMware Identity Service, a new one is created after authentication.
134+
135+
## Test SSO
136+
137+
In this section, you test your Azure AD single sign-on configuration with following options.
138+
139+
#### SP initiated:
140+
141+
* Click on **Test this application** in Azure portal. This will redirect to VMware Identity Service Sign on URL where you can initiate the login flow.
142+
143+
* Go to VMware Identity Service Sign on URL directly and initiate the login flow from there.
144+
145+
#### IDP initiated:
146+
147+
* Click on **Test this application** in Azure portal and you should be automatically signed in to the VMware Identity Service for which you set up the SSO.
148+
149+
You can also use Microsoft My Apps to test the application in any mode. When you click the VMware Identity Service tile in the My Apps, if configured in SP mode you would be redirected to the application sign-on page for initiating the login flow and if configured in IDP mode, you should be automatically signed in to the VMware Identity Service for which you set up the SSO. For more information about the My Apps, see [Introduction to the My Apps](../user-help/my-apps-portal-end-user-access.md).
150+
151+
## Additional resources
152+
153+
* [What is single sign-on with Azure Active Directory?](../manage-apps/what-is-single-sign-on.md)
154+
* [Plan a single sign-on deployment](../manage-apps/plan-sso-deployment.md).
155+
156+
## Next steps
157+
158+
Once you configure VMware Identity Service you can enforce session control, which protects exfiltration and infiltration of your organization’s sensitive data in real time. Session control extends from Conditional Access. [Learn how to enforce session control with Microsoft Cloud App Security](/cloud-app-security/proxy-deployment-aad).

0 commit comments

Comments
 (0)