Merge pull request #6628 from kjac/v15/feature/api-users-and-external-access

API Users and external access to the Management API

Author: sofietoft

15/umbraco-cms/SUMMARY.md

@@ -42,6 +42,9 @@
       * [Image Cropper](fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/image-cropper.md)
       * [Block Editors](fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/block-editor/README.md)
         * [Block Grid](fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/block-editor/block-grid-editor.md)
+* [Data](fundamentals/data/README.md)
+  * [Users](fundamentals/data/users/README.md)
+    * [API Users](fundamentals/data/users/api-users.md)
 
 ## Implementation
 
@@ -105,6 +108,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)
   * [Cache Seeding](reference/cache/cache-seeding.md)
   * [Examples](reference/cache/examples/README.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,19 @@
+---
+description: This guide will explain the API Users concept and how they differ from regular Users how to define
+---
+
+# API Users
+
+API Users allow 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 for one thing: It has no password. In fact, API Users are not allowed to log into the backoffice like regular Users.
+
+Instead, API Users hold the Client Credentials used to authorize against the Management API. When an external source authorizes using Client Credentials, it effectively assumes the identity of the API User.
+
+Since API Users are identical to regular Users their backoffice access can be controlled in the same way. This allows for imposing detailed access control on the external sources connected to the Management API.
+
+![An API User in the backoffice](../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,95 @@
+---
+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, you must use the OpenId Connect Client Credentials flow for authorization. Refer to the [API Users](../../fundamentals/data/users/api-users.md) article for details on setting up Client Credentials.
+
+With a set of Client Credentials in place, you 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 you can keep issuing new tokens for the Client Credentials, please reuse tokens within their lifespan. This will be more performant and avoid flooding the Umbraco database with tokens.
+
+{% hint style="info" %}
+The Management API does not support OpenID Connect Discovery. This is reserved for Members accessing protected content 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, and
+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 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 %}