API Users and external access to the Management API

Author: kjac

15/umbraco-cms/SUMMARY.md

@@ -30,6 +30,9 @@
   * [Property Editors](fundamentals/backoffice/property-editors/README.md)
     * [Built-in Property Editors](fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/README.md)
       * [Image Cropper](fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/image-cropper.md)
+* [Data](fundamentals/data/README.md)
+  * [Users](fundamentals/data/users/README.md)
+    * [API Users](fundamentals/data/users/api-users.md)
 
 ## Implementation
 
@@ -91,6 +94,8 @@
 * [Management](reference/management/README.md)
   * [Using Umbraco services](reference/management/using-services/README.md)
     * [Content Type Service](reference/management/using-services/contenttypeservice.md)
+* [Management API](reference/management-api/README.md)
+    * [External Access](reference/management-api/external-access.md)
 * [Cache & Distributed Cache](reference/cache/README.md)
   * [Examples](reference/cache/examples/README.md)
     * [Working with caching](reference/cache/examples/tags.md)

15/umbraco-cms/fundamentals/data/images/api-user.png

@@ -6,7 +6,7 @@ description: >-
 
 # Users
 
-Users (not to be confused with [Members](members.md)) are people who have access to the Umbraco backoffice. These could include Content Editors, Translators, Web Designers, and Developers.
+Users (not to be confused with [Members](../members.md)) are people who have access to the Umbraco backoffice. These could include Content Editors, Translators, Web Designers, and Developers.
 
 This guide will explain how to define, create, and manage users in the backoffice.
 
@@ -38,7 +38,7 @@ By default, the User Groups available to new users are **Administrators**, **Wri
 * **Editor**: Allowed to create and publish content items or nodes on the website without approval from others or restrictions (has permissions to **Public Access**, **Rollback**, **Browse Node**, **Create Content Template**, **Delete**, **Create**, **Publish**, **Unpublish**, **Update**, **Copy**, **Move** and **Sort**).
 * **Writer**: Allowed to browse nodes, create nodes, and request for publication of items. Not allowed to publish directly without someone elses approval like an Editor (has permissions to **Browse Node**, **Create**, **Send to Publish** and **Update**).
 * **Translator**: Are used for translating your website. Translators are allowed to browse and update nodes as well as grant dashboard access. Translations of site pages must be reviewed by others before publication (has permissions to **Browse Node** and **Update**).
-* **Sensitive data**: Any users added to this User group will have access to view any data marked as sensitive. Learn more about this feature in the [Sensitive Data](../../reference/security/sensitive-data-on-members.md) article.
+* **Sensitive data**: Any users added to this User group will have access to view any data marked as sensitive. Learn more about this feature in the [Sensitive Data](../../../reference/security/sensitive-data-on-members.md) article.
 
 ## Creating a User Group
 

15/umbraco-cms/fundamentals/data/users.md renamed to 15/umbraco-cms/fundamentals/data/users/README.md

@@ -0,0 +1,20 @@
+---
+description: >-
+  This guide will explain the concept of API Users and how they differ from regular Users how to define
+---
+
+# API Users
+
+API Users allows for authorizing [external access](../../../reference/management-api/external-access.md) to the Management API.
+
+An API User is identical to a [regular User](README.md) except from one thing: It has no password. In fact, API Users are not allowed to log into the back-office like regular Users.
+
+Instead, API Users hold the Client Credentials used to authorize against the Management API. When an external source authorizes with the Client Credentials, it effectively assumes the identity of the API User.
+
+Since API Users are otherwise identical to regular Users, their back-office access can be controlled in the same way. This allows for imposing very detailed access control on the external sources connected to the Management API.
+
+![An API User in the back-office](../images/api-user.png)
+
+{% hint style="info" %}
+Client IDs for API Users are explicitly prefixed with `umbraco-back-office-`. This guards against API Users accidentally taking over one of the Client IDs used by the Umbraco core.
+{% endhint %}

15/umbraco-cms/fundamentals/data/users/api-users.md

@@ -0,0 +1,93 @@
+---
+description: How external applications can consume the Management API.
+---
+
+# External access to the Management API
+
+The Management API can be used directly for integrations between Umbraco and external systems.
+
+When consuming the Management API from an external source, we must use the OpenId Connect Client Credentials flow for authorization. For details on setting up Client Credentials, please refer fo the [API Users](../../fundamentals/data/users/api-users.md) article.
+
+With a set of Client Credentials in place, we can obtain an access token from the Management API token endpoint: `/umbraco/management/api/v1/security/back-office/token`. The token endpoint response looks like this:
+
+```json
+{
+  "access_token": "ZnEAKg5YwDc7621y6xZlEdT9kwp_ULGQPc5mnY9cDw0",
+  "token_type": "Bearer",
+  "expires_in": 299
+}
+```
+
+As shown, the access token should be used as a Bearer token when consuming the Management API.
+
+Also notice that access tokens have a fixed expiry. While we can keep issuing new tokens for our Client Credentials, please reuse tokens within their lifespan. This will be more performant, and will also keep from flooding the Umbraco database with tokens.
+
+{% hint style="info" %}
+Please notice that the Management API does not support OIDC Discovery. This is reserved for accessing protected for Members via the [Delivery API](../content-delivery-api/protected-content-in-the-delivery-api.md).
+{% endhint %}
+
+The following code sample demonstrates how to consume the Management API by:
+
+1. Obtaining an access token from the token endpoint.
+2. Fetching data from the "current user" endpoint.
+
+![The "current user" endpoint in Swagger UI](images/current-user-endpoint.png)
+
+{% hint style="info" %}
+This sample requires the [`IdentityModel`](https://www.nuget.org/packages/IdentityModel) NuGet package to run.
+{% endhint %}
+
+{% code title="Program.cs" lineNumbers="true" %}
+```csharp
+using System.Net.Http.Json;
+using IdentityModel.Client;
+
+// the base URL of the Umbraco site - change this to fit your own setup
+const string host = "https://localhost:44391";
+
+var client = new HttpClient();
+
+// request a client credentials token from the Management API token endpoint
+var tokenResponse = await client.RequestClientCredentialsTokenAsync(
+    new ClientCredentialsTokenRequest
+    {
+        Address = $"{host}/umbraco/management/api/v1/security/back-office/token",
+        ClientId = "umbraco-back-office-my-client",
+        ClientSecret = "my-client-secret"
+    }
+);
+
+if (tokenResponse.IsError || tokenResponse.AccessToken is null)
+{
+    Console.WriteLine($"Error obtaining a token: {tokenResponse.ErrorDescription}");
+    return;
+}
+
+// use the access token as Bearer token
+client.SetBearerToken(tokenResponse.AccessToken);
+
+// fetch user data from the "current user" Management API endpoint
+var apiResponse = await client.GetAsync($"{host}/umbraco/management/api/v1/user/current");
+var apiUserResponse = await apiResponse
+    .EnsureSuccessStatusCode()
+    .Content
+    .ReadFromJsonAsync<ApiUserResponse>();
+
+if (apiUserResponse is null)
+{
+    Console.WriteLine("Could not parse a user from the API response.");
+    return;
+}
+
+Console.WriteLine($"Hello, {apiUserResponse.Name} ({apiUserResponse.Email})");
+
+public class ApiUserResponse
+{
+    public required Guid Id { get; set; }
+
+    public required string Name { get; set; }
+
+    public required string Email { get; set; }
+}
+```
+{% endcode %}