From d4f2af83b4383552ab1c9fcd16579318457de7e0 Mon Sep 17 00:00:00 2001 From: Steven Hicks Date: Mon, 26 Aug 2024 10:23:50 -0500 Subject: [PATCH] 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 <84338309+christinaausley@users.noreply.github.com> --- .../tasklist-api-rest-authentication.md | 176 +++++++++++++----- .../tasklist-api-rest-authentication.md | 176 +++++++++++++----- 2 files changed, 250 insertions(+), 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 index 3bd32b3424a..30684759bb3 100644 --- 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 ` - -For example, send a request using _curl_: - -```shell -curl -X POST -H -H :accept: application/json" -H "Authorization: Bearer " -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_secret": "", - "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 + + + + +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: + + | 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` | - | + + :::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": "", + "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. + + + + + +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": "", + "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. + + + + + +## Using a token + +Include the captured token as an authorization header in each request: `Authorization: Bearer `. + +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: + + + + + +:::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}`. +::: + + + + + +:::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`. +::: + + + + ```shell -curl -X POST --header 'content-type: application/json' --data '{"client_id": "", "client_secret":"","audience":"","grant_type":"client_credentials"}' https:// +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/versioned_docs/version-8.5/apis-tools/tasklist-api-rest/tasklist-api-rest-authentication.md b/versioned_docs/version-8.5/apis-tools/tasklist-api-rest/tasklist-api-rest-authentication.md index 3bd32b3424a..30684759bb3 100644 --- a/versioned_docs/version-8.5/apis-tools/tasklist-api-rest/tasklist-api-rest-authentication.md +++ b/versioned_docs/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 ` - -For example, send a request using _curl_: - -```shell -curl -X POST -H -H :accept: application/json" -H "Authorization: Bearer " -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_secret": "", - "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 + + + + +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: + + | 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` | - | + + :::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": "", + "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. + + + + + +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": "", + "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. + + + + + +## Using a token + +Include the captured token as an authorization header in each request: `Authorization: Bearer `. + +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: + + + + + +:::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}`. +::: + + + + + +:::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`. +::: + + + + ```shell -curl -X POST --header 'content-type: application/json' --data '{"client_id": "", "client_secret":"","audience":"","grant_type":"client_credentials"}' https:// +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.