languages | page_type | name | description | products | urlFragment | |||||
---|---|---|---|---|---|---|---|---|---|---|
|
sample |
ASP.NET Core minimal web API that both protects its own endpoints and accesses Microsoft Graph. |
This ASP.NET Core minimal web API protects an API endpoint that access on behalf of the user another protected API. The code in this sample is used by one or more articles on docs.microsoft.com. |
|
ms-identity-docs-code-obo-user-csharp |
ASP.NET Core minimal web API | web api | access control (protected routes), protected web API access (Microsoft Graph) | Microsoft identity platform
This ASP.NET Core minimal web API uses the Microsoft identity platform to protect an endpoint (require authorized access), and also accesses Microsoft Graph on behalf of the user. The API uses ASP.NET Core Identity interacting with the Microsoft Authentication Library (MSAL) to protect its endpoint.
$ curl https://localhost:5001/api/me -H "Authorization: Bearer {valid-access-token}"
{
"@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users/$entity",
"businessPhones": [],
"displayName": "Maui",
"givenName": null,
"jobTitle": "dev",
"mail": null,
"mobilePhone": null,
"officeLocation": null,
"preferredLanguage": null,
"surname": null,
"id": "cff40dac-17ea-4183-9caf-65f2ee90c562"
}
📃 This sample application backs one or more technical articles on docs.microsoft.com.
- An Azure Active Directory (Azure AD) tenant. You can open an Azure account for free to get an Azure AD instance.
- .NET 6.0 SDK
First, complete the steps in Configure an application to expose a web API to register the sample API and expose a scope.
Use the following settings for your app registration:
App registration setting |
Value for this sample app | Notes |
---|---|---|
Name | active-directory-protected-api-access-protected-api |
Suggested value for this sample. You can change the app name at any time. |
Supported account types | Accounts in this organizational directory only (Single tenant) | Required for this sample. Support for the Single tenant. |
Identifier URI | api://{clientId} |
Suggested value for this sample. You must change the client id using the Value shown in Azure portal. |
Expose an API | Scope name: user_impersonation Who can consent?: Admins and users Admin consent display name: Act on behalf of the user Admin consent description: Allows the API to act on behalf of the user. User consent display name: Act on your behalf User consent description: Allows the API to act on your behalf. State: Enabled |
Add a new scope that reads as follows api://{clientId}/user_impersonation . Required value for this sample. |
API Permissions | https://graph.microsoft.com/User.Read |
Add a new delegated permission for Microsoft Graph User.Read . Required value for this sample. |
Client secret | Value shown in Azure portal | It's shown only once (when you create it). |
ℹ️ Bold text in the table matches (or is similar to) a UI element in the Azure portal, while
code formatting
indicates a value you enter into a text box or select in the Azure portal.
Second, complete the steps in Register an application with the Microsoft identity platform to register the client sample app.
Use the following settings for your app registration:
App registration setting |
Value for this sample app | Notes |
---|---|---|
Name | active-directory-curl-app |
Suggested value for this sample. You can change the app name at any time. |
Supported account types | Accounts in this organizational directory only (Single tenant) | Required for this sample. Support for the Single tenant. |
Platform type | Web | Required value for this sample. Enables the required and optional settings for the app type. |
API Permissions | api://{clientId}/user_impersonation |
Add a delegated type permission by searching within the APIs using the new Application (client) ID from the previous step. Then select the user_impersonation . Required value for this sample. |
Client secret | Value shown in Azure portal | It's shown only once (when you create it). |
ℹ️ Bold text in the table matches (or is similar to) a UI element in the Azure portal, while
code formatting
indicates a value you enter into a text box or select in the Azure portal.
Third, modify the web API application to update the following settings to reference the cUrl app
App registration setting |
Value for this sample app | Notes |
---|---|---|
knownClientApplications | Client ID (UUID) of the application created in step 2. | Required value for this sample. |
-
Open the protected-api-access-protected-api/appsettings.json file in your code editor and modify the following code:
"ClientId": "Enter_the_Application_Id_here", "TenantId": "Enter_the_Tenant_Info_here", "ClientSecret": "Enter_the_Client_Secret_here"
Execute the following command to get the app up and running:
dotnet run
-
Once the web API is listening, execute the following to send a request to its protected endpoint.
curl -X GET https://localhost:5001/api/me -ki
ℹ️ The expected response is
401 Unauthorized
because you've sent a request to the protected endpoint without including an access token (as a bearer token). -
Use Postman, curl, or similar to send an HTTP GET request to https://localhost:5001/me, this time including an
Authorization
header ofBearer {valid-access-token}
.If everything worked, your protected web API should return a response similar to this:
curl -X GET https://localhost:5001/api/me -ki -H "Authorization: Bearer {valid-access-token}" { "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users/$entity", "businessPhones": [], "displayName": "Maui", "givenName": null, "jobTitle": "dev", "mail": null, "mobilePhone": null, "officeLocation": null, "preferredLanguage": null, "surname": null, "id": "cff40dac-17ea-4183-9caf-65f2ee90c562" }
ℹ️ The expected response code is
200 OK
if you included a valid access token as bearer token in the request.
This ASP.NET Core minimal web API has a single protected route, (/api/me), that requires callers (client applications making requests to the endpoint) present a valid access token issued by the Microsoft identity platform.
Acting as a middle-tier API, this minimal web API then uses that access token to acquire a second access token from the Microsoft identity platform, this time for Microsoft Graph, on behalf of the user.
Finally, the web API requests data from the Microsoft Graph /me
endpoint and includes the response data in its response to the original caller.
This project uses the Microsoft.Identity.Web apis to interface with Microsoft Authentication Library (MSAL) for .NET. It acquires access tokens on behalf of the user, caching the resulting token in memory. Provided an access token was previously cached, the subsequent calls against /api/me will attempt to reuse the cached access token, refreshing it if nearing expiration. The MSAL is logging informational entries that state when a new access token is being acquired, cached, and re-used.
If you can't get the sample working, you've checked Stack Overflow, and you've already searched the issues in this sample's repository, open an issue report the problem.
- Search the GitHub issues in the repository - your problem might already have been reported or have an answer.
- Nothing similar? Open an issue that clearly explains the problem you're having running the sample app.
⚠️ WARNING: Any issue not limited to running this or another sample app will be closed without being addressed.
For all other requests, see Support and help options for developers | Microsoft identity platform.
If you'd like to contribute to this sample, see CONTRIBUTING.MD.
This project has adopted the Microsoft Open Source Code of Conduct. For more information, see the Code of Conduct FAQ or contact [email protected] with any additional questions or comments.