feat: rewrite Tasklist API auth guide (#4152)

* feat: rewrite Tasklist API auth guide * feedback: incorporate edits from Operate PR * feedback: sync tab sections to each other * chore: backport changes from vNext to vCurrent --------- Co-authored-by: christinaausley <[email protected]>
camunda · Aug 26, 2024 · d4f2af8 · d4f2af8
1 parent 8f818a3
commit d4f2af8
Show file tree

Hide file tree

Showing 2 changed files with 250 additions and 102 deletions.
diff --git a/docs/apis-tools/tasklist-api-rest/tasklist-api-rest-authentication.md b/docs/apis-tools/tasklist-api-rest/tasklist-api-rest-authentication.md
@@ -5,63 +5,137 @@ sidebar_position: 2
 description: "Describes authentication options that can be used to access Tasklist REST API."
 ---
 
-## Authentication in the cloud
-
-To access the API endpoint, you need an access token.
-
-Your client must send a header in each request:
-
-`Authorization: Bearer <Token>`
-
-For example, send a request using _curl_:
-
-```shell
-curl -X POST -H -H :accept: application/json" -H "Authorization: Bearer <TOKEN>" -d '' http://localhost:8080/v1/tasks/search
-```
-
-### How to obtain the access token
-
-You must obtain a token to use the Tasklist API. When you create a Tasklist [client](/guides/setup-client-connection-credentials.md), you get all the information needed to connect to Tasklist.
-
-Refer to our guide on [building your own client](../build-your-own-client.md).
-
-The following settings are needed:
-
-| Name                     | Description                                     | Default value         |
-| ------------------------ | ----------------------------------------------- | --------------------- |
-| client id                | Name of your registered client                  | -                     |
-| client secret            | Password for your registered client             | -                     |
-| audience                 | Permission name; if not given use default value | `tasklist.camunda.io` |
-| authorization server url | Token issuer server                             | -                     |
-
-Send a token issue _POST_ request to the authorization server with the following content:
-
-```json
-{
-  "client_id": "<client-id>",
-  "client_secret": "<client-secret>",
-  "audience": "<audience>",
-  "grant_type": "client_credentials"
-}
-```
-
-Refer to the following example with _curl_:
+import Tabs from "@theme/Tabs";
+import TabItem from "@theme/TabItem";
+
+All Tasklist API requests require authentication. To authenticate, generate a [JSON Web Token (JWT)](https://jwt.io/introduction/) and pass it in each request.
+
+## Generating a token
+
+<Tabs groupId="environment" defaultValue="saas" queryString values={
+[
+{label: 'SaaS', value: 'saas' },
+{label: 'Self-Managed', value: 'self-managed' },
+]}>
+<TabItem value='saas'>
+
+1. [Create client credentials](/guides/setup-client-connection-credentials.md) in the **Clusters > Cluster name > API** tab of [Camunda Console](https://console.camunda.io/).
+2. Add permissions to this client for **Tasklist**.
+3. Upon creating the client, capture the following values required to generate a token:
+   <!-- this comment convinces the markdown processor to still treat the table as a table, but without adding surrounding paragraphs. 🤷 -->
+   | Name                     | Environment variable name        | Default value                                |
+   | ------------------------ | -------------------------------- | -------------------------------------------- |
+   | Client ID                | `ZEEBE_CLIENT_ID`                | -                                            |
+   | Client Secret            | `ZEEBE_CLIENT_SECRET`            | -                                            |
+   | Authorization Server URL | `ZEEBE_AUTHORIZATION_SERVER_URL` | `https://login.cloud.camunda.io/oauth/token` |
+   | Tasklist REST Address    | `CAMUNDA_TASKLIST_BASE_URL`      | -                                            |
+   <!-- this comment convinces the markdown processor to still treat the table as a table, but without adding surrounding paragraphs. 🤷 -->
+   :::tip
+   When client credentials are created, the `Client Secret` is only shown once. Save this `Client Secret` somewhere safe.
+   :::
+4. Execute an authentication request to the token issuer:
+   ```bash
+   curl --request POST ${ZEEBE_AUTHORIZATION_SERVER_URL} \
+       --header 'Content-Type: application/x-www-form-urlencoded' \
+       --data-urlencode 'grant_type=client_credentials' \
+       --data-urlencode 'audience=tasklist.camunda.io' \
+       --data-urlencode "client_id=${ZEEBE_CLIENT_ID}" \
+       --data-urlencode "client_secret=${ZEEBE_CLIENT_SECRET}"
+   ```
+5. A successful authentication response looks like the following:
+   ```json
+   {
+     "access_token": "<TOKEN>",
+     "expires_in": 300,
+     "refresh_expires_in": 0,
+     "token_type": "Bearer",
+     "not-before-policy": 0
+   }
+   ```
+6. Capture the value of the `access_token` property and store it as your token.
+
+</TabItem>
+
+<TabItem value='self-managed'>
+
+1. [Add an M2M application in Identity](/self-managed/identity/user-guide/additional-features/incorporate-applications.md).
+2. [Add permissions to this application](/self-managed/identity/user-guide/additional-features/incorporate-applications.md) for **Tasklist API**.
+3. Capture the `Client ID` and `Client Secret` from the application in Identity.
+4. [Generate a token](/self-managed/identity/user-guide/authorizations/generating-m2m-tokens.md) to access the REST API. Provide the `client_id` and `client_secret` from the values you previously captured in Identity.
+   ```shell
+   curl --location --request POST 'http://localhost:18080/auth/realms/camunda-platform/protocol/openid-connect/token' \
+   --header 'Content-Type: application/x-www-form-urlencoded' \
+   --data-urlencode "client_id=${CLIENT_ID}" \
+   --data-urlencode "client_secret=${CLIENT_SECRET}" \
+   --data-urlencode 'grant_type=client_credentials'
+   ```
+5. A successful authentication response looks like the following:
+   ```json
+   {
+     "access_token": "<TOKEN>",
+     "expires_in": 300,
+     "refresh_expires_in": 0,
+     "token_type": "Bearer",
+     "not-before-policy": 0
+   }
+   ```
+6. Capture the value of the `access_token` property and store it as your token.
+
+See the [Tasklist Configuration - Authentication](/self-managed/tasklist-deployment/tasklist-authentication.md#identity) documentation for more information about this authentication method.
+
+</TabItem>
+
+</Tabs>
+
+## Using a token
+
+Include the captured token as an authorization header in each request: `Authorization: Bearer <TOKEN>`.
+
+For example, to call the Tasklist API's ["Search tasks" endpoint](./specifications/search-tasks.api.mdx), send the following request against the target Tasklist environment:
+
+<Tabs groupId="environment" defaultValue="saas" queryString values={
+[
+{label: 'SaaS', value: 'saas' },
+{label: 'Self-Managed', value: 'self-managed' },
+]}>
+
+<TabItem value='saas'>
+
+:::tip
+The `${CAMUNDA_TASKLIST_BASE_URL}` variable below represents the URL of the Tasklist API. You can capture this URL when creating an API client. You can also construct it as `https://${REGION}.tasklist.camunda.io/${CLUSTER_ID}`.
+:::
+
+</TabItem>
+
+<TabItem value='self-managed'>
+
+:::tip
+The `${CAMUNDA_TASKLIST_BASE_URL}` variable below represents the URL of the Tasklist API. You can configure this value in your Self-Managed installation. The default value is `http://localhost:8082`.
+:::
+
+</TabItem>
+
+</Tabs>
 
 ```shell
-curl -X POST --header 'content-type: application/json' --data '{"client_id": "<client-id>", "client_secret":"<client-secret>","audience":"<audience>","grant_type":"client_credentials"}' https://<authorization server url>
+curl --request POST ${CAMUNDA_TASKLIST_BASE_URL}/v1/tasks/search \
+   --header "Authorization: Bearer ${TOKEN}" \
+   --header 'Content-Type: application/json' \
+   --data-raw '{}'
 ```
 
-If the authentication is successful, the authorization server sends back the access token, when it expires, scope, and type:
+A successful response would include [matching tasks](./specifications/search-tasks.api.mdx). For example:
 
 ```json
-{
-  "access_token": "ey...",
-  "scope": "...",
-  "expires_in": 86400,
-  "token_type": "Bearer"
-}
+[
+  {
+    "id": "12345",
+    "name": "Do something",
+    ...
+  }
+]
 ```
 
-## Authentication for Self-Managed cluster
+## Token expiration
 
-The authentication is described in [Tasklist Configuration - Authentication](../../self-managed/tasklist-deployment/tasklist-authentication.md#use-identity-jwt-token-to-access-tasklist-api).
+Access tokens expire according to the `expires_in` property of a successful authentication response. After this duration, in seconds, you must request a new access token.
diff --git a/...cs/version-8.5/apis-tools/tasklist-api-rest/tasklist-api-rest-authentication.md b/...cs/version-8.5/apis-tools/tasklist-api-rest/tasklist-api-rest-authentication.md
@@ -5,63 +5,137 @@ sidebar_position: 2
 description: "Describes authentication options that can be used to access Tasklist REST API."
 ---
 
-## Authentication in the cloud
-
-To access the API endpoint, you need an access token.
-
-Your client must send a header in each request:
-
-`Authorization: Bearer <Token>`
-
-For example, send a request using _curl_:
-
-```shell
-curl -X POST -H -H :accept: application/json" -H "Authorization: Bearer <TOKEN>" -d '' http://localhost:8080/v1/tasks/search
-```
-
-### How to obtain the access token
-
-You must obtain a token to use the Tasklist API. When you create a Tasklist [client](/guides/setup-client-connection-credentials.md), you get all the information needed to connect to Tasklist.
-
-Refer to our guide on [building your own client](../build-your-own-client.md).
-
-The following settings are needed:
-
-| Name                     | Description                                     | Default value         |
-| ------------------------ | ----------------------------------------------- | --------------------- |
-| client id                | Name of your registered client                  | -                     |
-| client secret            | Password for your registered client             | -                     |
-| audience                 | Permission name; if not given use default value | `tasklist.camunda.io` |
-| authorization server url | Token issuer server                             | -                     |
-
-Send a token issue _POST_ request to the authorization server with the following content:
-
-```json
-{
-  "client_id": "<client-id>",
-  "client_secret": "<client-secret>",
-  "audience": "<audience>",
-  "grant_type": "client_credentials"
-}
-```
-
-Refer to the following example with _curl_:
+import Tabs from "@theme/Tabs";
+import TabItem from "@theme/TabItem";
+
+All Tasklist API requests require authentication. To authenticate, generate a [JSON Web Token (JWT)](https://jwt.io/introduction/) and pass it in each request.
+
+## Generating a token
+
+<Tabs groupId="environment" defaultValue="saas" queryString values={
+[
+{label: 'SaaS', value: 'saas' },
+{label: 'Self-Managed', value: 'self-managed' },
+]}>
+<TabItem value='saas'>
+
+1. [Create client credentials](/guides/setup-client-connection-credentials.md) in the **Clusters > Cluster name > API** tab of [Camunda Console](https://console.camunda.io/).
+2. Add permissions to this client for **Tasklist**.
+3. Upon creating the client, capture the following values required to generate a token:
+   <!-- this comment convinces the markdown processor to still treat the table as a table, but without adding surrounding paragraphs. 🤷 -->
+   | Name                     | Environment variable name        | Default value                                |
+   | ------------------------ | -------------------------------- | -------------------------------------------- |
+   | Client ID                | `ZEEBE_CLIENT_ID`                | -                                            |
+   | Client Secret            | `ZEEBE_CLIENT_SECRET`            | -                                            |
+   | Authorization Server URL | `ZEEBE_AUTHORIZATION_SERVER_URL` | `https://login.cloud.camunda.io/oauth/token` |
+   | Tasklist REST Address    | `CAMUNDA_TASKLIST_BASE_URL`      | -                                            |
+   <!-- this comment convinces the markdown processor to still treat the table as a table, but without adding surrounding paragraphs. 🤷 -->
+   :::tip
+   When client credentials are created, the `Client Secret` is only shown once. Save this `Client Secret` somewhere safe.
+   :::
+4. Execute an authentication request to the token issuer:
+   ```bash
+   curl --request POST ${ZEEBE_AUTHORIZATION_SERVER_URL} \
+       --header 'Content-Type: application/x-www-form-urlencoded' \
+       --data-urlencode 'grant_type=client_credentials' \
+       --data-urlencode 'audience=tasklist.camunda.io' \
+       --data-urlencode "client_id=${ZEEBE_CLIENT_ID}" \
+       --data-urlencode "client_secret=${ZEEBE_CLIENT_SECRET}"
+   ```
+5. A successful authentication response looks like the following:
+   ```json
+   {
+     "access_token": "<TOKEN>",
+     "expires_in": 300,
+     "refresh_expires_in": 0,
+     "token_type": "Bearer",
+     "not-before-policy": 0
+   }
+   ```
+6. Capture the value of the `access_token` property and store it as your token.
+
+</TabItem>
+
+<TabItem value='self-managed'>
+
+1. [Add an M2M application in Identity](/self-managed/identity/user-guide/additional-features/incorporate-applications.md).
+2. [Add permissions to this application](/self-managed/identity/user-guide/additional-features/incorporate-applications.md) for **Tasklist API**.
+3. Capture the `Client ID` and `Client Secret` from the application in Identity.
+4. [Generate a token](/self-managed/identity/user-guide/authorizations/generating-m2m-tokens.md) to access the REST API. Provide the `client_id` and `client_secret` from the values you previously captured in Identity.
+   ```shell
+   curl --location --request POST 'http://localhost:18080/auth/realms/camunda-platform/protocol/openid-connect/token' \
+   --header 'Content-Type: application/x-www-form-urlencoded' \
+   --data-urlencode "client_id=${CLIENT_ID}" \
+   --data-urlencode "client_secret=${CLIENT_SECRET}" \
+   --data-urlencode 'grant_type=client_credentials'
+   ```
+5. A successful authentication response looks like the following:
+   ```json
+   {
+     "access_token": "<TOKEN>",
+     "expires_in": 300,
+     "refresh_expires_in": 0,
+     "token_type": "Bearer",
+     "not-before-policy": 0
+   }
+   ```
+6. Capture the value of the `access_token` property and store it as your token.
+
+See the [Tasklist Configuration - Authentication](/self-managed/tasklist-deployment/tasklist-authentication.md#identity) documentation for more information about this authentication method.
+
+</TabItem>
+
+</Tabs>
+
+## Using a token
+
+Include the captured token as an authorization header in each request: `Authorization: Bearer <TOKEN>`.
+
+For example, to call the Tasklist API's ["Search tasks" endpoint](./specifications/search-tasks.api.mdx), send the following request against the target Tasklist environment:
+
+<Tabs groupId="environment" defaultValue="saas" queryString values={
+[
+{label: 'SaaS', value: 'saas' },
+{label: 'Self-Managed', value: 'self-managed' },
+]}>
+
+<TabItem value='saas'>
+
+:::tip
+The `${CAMUNDA_TASKLIST_BASE_URL}` variable below represents the URL of the Tasklist API. You can capture this URL when creating an API client. You can also construct it as `https://${REGION}.tasklist.camunda.io/${CLUSTER_ID}`.
+:::
+
+</TabItem>
+
+<TabItem value='self-managed'>
+
+:::tip
+The `${CAMUNDA_TASKLIST_BASE_URL}` variable below represents the URL of the Tasklist API. You can configure this value in your Self-Managed installation. The default value is `http://localhost:8082`.
+:::
+
+</TabItem>
+
+</Tabs>
 
 ```shell
-curl -X POST --header 'content-type: application/json' --data '{"client_id": "<client-id>", "client_secret":"<client-secret>","audience":"<audience>","grant_type":"client_credentials"}' https://<authorization server url>
+curl --request POST ${CAMUNDA_TASKLIST_BASE_URL}/v1/tasks/search \
+   --header "Authorization: Bearer ${TOKEN}" \
+   --header 'Content-Type: application/json' \
+   --data-raw '{}'
 ```
 
-If the authentication is successful, the authorization server sends back the access token, when it expires, scope, and type:
+A successful response would include [matching tasks](./specifications/search-tasks.api.mdx). For example:
 
 ```json
-{
-  "access_token": "ey...",
-  "scope": "...",
-  "expires_in": 86400,
-  "token_type": "Bearer"
-}
+[
+  {
+    "id": "12345",
+    "name": "Do something",
+    ...
+  }
+]
 ```
 
-## Authentication for Self-Managed cluster
+## Token expiration
 
-The authentication is described in [Tasklist Configuration - Authentication](../../self-managed/tasklist-deployment/tasklist-authentication.md#use-identity-jwt-token-to-access-tasklist-api).
+Access tokens expire according to the `expires_in` property of a successful authentication response. After this duration, in seconds, you must request a new access token.