Merge pull request #734 from RizaFarheen/main

Updates

docs/access-control-and-security/applications.md

@@ -1,79 +1,86 @@
 # Enabling Security via Applications
 
-Orkes has added a security layer called Applications, enabling the connection between the workers and the Conductor instance. Every connection in/out of Orkes Conductor requires an authentication header with a JSON Web Token (JWT). This header is of the format: `'X-Authorization: <JWT Token>'`.
+Orkes has added a security layer called Applications, enabling the connection between the workers and the Orkes Conductor cluster. Every connection in/out of Orkes Conductor requires an authentication header with a JSON Web Token (JWT). This header is of the format: `'X-Authorization: <JWT Token>'`.
 
-This document will walk you through the steps to create application-based control for your workflows and tasks and the process to generate JWT tokens for each application.
+An application represents an entity interacting with the Conductor server via APIs or SDKs. Each application can have multiple access key and secret combinations, which are used to generate an authentication token for securing and controlling access to each API request.
+
+This document provides a detailed guide on creating application-based control for your metadata as well as the process for generating JWT tokens for each application.
 
 ## Prototyping​
 
-If you are looking for a quick way to test on Orkes Conductor without creating an application, you can obtain a JWT token from the Conductor dashboard. Click the account button in the top right corner, and select **Copy Token**. This token remains valid for your current session and has the same access as your user account.
+For quick testing on Orkes Conductor without creating an application, you can obtain a JWT token from the Orkes Conductor dashboard. Click the account button in the bottom left corner and select "Copy Token." This token remains valid for your current session and has the same access as your user account.
 
 ## Application
 
-Each application can generate one or more sets of keys and secrets, and these parameters are used to generate the JWT token. An application can grant access to workflows, tasks, secrets & tags.
+Each application can generate one or more sets of keys and secrets to produce a JWT token. Applications can grant access to entities such as workflows, tasks, secrets, environment variables, tags, domains, integrations, and prompts.
 
 ### Configuring Application​
 
 To create a new application,
-1. From the left menu navigation, navigate to **Access Control > Applications**.
-2. Click **Create application** and provide an app name.
-3. Once your application is created, click the edit button next to its name.
+
+1. Navigate to **Access Control > Applications** from the left menu on your Orkes Conductor console.
+2. Click **+ Create application** and provide an app name.
+3. Click **Save** to create the application.
 
 Depending upon your role, you can see two different role sections that can be granted to the application.
 
-<p align="center"><img src="/content/img/app-roles.png" alt="App roles" width="100%" height="auto"></img></p>
+* Unrestricted roles: Can be granted only by an Admin.
+* Application roles: Can be granted by anyone with access to Applications.
+
+<p align="center"><img src="/content/img/app-roles.png" alt="App roles" width="80%" height="auto"></img></p>
 
-The general application roles that can be granted include:
+General application roles include:
 
-* **Worker**: Poll and update tasks. It requires EXECUTE permissions on the tasks.
+* **Worker**: Poll and update tasks. It requires Execute permissions on the tasks.
 * **Metadata API**: Create and manage workflow and task definitions.
 * **Application API**: Create and manage applications.
 
-The application behavior depends entirely on the app role chosen. Ensure that you select the role based on your requirements. 
+The application's behavior depends on the chosen role, so select roles based on your requirements.
 
-In addition, if you are an Admin in the Orkes Conductor console, then you can see an additional set of following unrestricted roles that are to be granted carefully as they provide full access to different APIs:
+Admins have additional unrestricted roles, such as:
 
 - **Unrestricted Worker** - Poll, execute updates, maintain logs, and handle any task without any constraints
 - **Metadata Manager** - Create, update, delete, and administer Workflow or Task definitions permissions.
 - **Workflow Manager** - Responsible for managing the lifecycle of workflows within the system. Initiate, pause, resume, rerun, delete, and oversee any Workflow operation.
 - **Application Manager** - Handles the creation, modification, and deletion of applications within the system.
 
 ### Generating Access Keys​
-Once your application's permission levels are chosen, access must be granted to the application. This is done by generating an Access Key. Click **Create access key** to generate a unique **Key Id** and **Key Secret**. These values are shown only once, so ensure to copy the credentials and store them privately.
 
-Once a key has been created, you can perform two actions on the key:
+Once permissions are assigned, generate an **Access Key**:
+
+1. Click **+ Create access key** to generate a unique Key Id and Key Secret.
+2. The key secret is shown only once; copy and store it privately.
+
+Once a key has been created, you can perform three actions on the key:
 
 <p align="center"><img src="/content/img/actions-on-the-generated-key.jpg" alt="Generated Key in the Conductor" width="90%" height="auto"></img></p>
 
-* **Pause** - Use the pause button to restrict access to the application temporarily. You can resume this access by un-pausing.
-* **Delete** - Use the delete button to remove the key permanently. It is a one-time action that cannot be undone.
+* **Copy** - Use the copy button to copy the key ID.
+* **Pause** - Use the pause button to temporarily restrict access to the application. 
+* **Delete** - Use the delete button to permanently remove the key.
 
 ### Adding Permissions​
-In this section, you can provide the application with access to workflows, tasks, secrets, or tags. To add the permissions,
-1. Click **+Add Permission** from the **Workflow and Task Permissions** section.
-2. Choose the required Workflow/Task/Secret/Tag/Domain/Integration/Prompt in the pop-up window.
-<ul>
-<li><b>Domain</b> - This can be used if you have set up an external worker with a task to domain mapping. You need to provide permission for the domain for the entire application to poll and update the tasks. </li>
-</ul>
+
+In this section, you can provide the application with access to workflows, tasks, secrets, environment variables, tags, domains, integrations, and prompts. 
+
+To grant permissions to the application:
+
+1. Click **+Add Permission**.
+2. Select the required metadata to have access to selected workflows, tasks, secrets, environment variables, tags, domains, integrations, and prompts.
 3. Select all targets that the application needs access to.
 4. Choose the required permissions for the selected targets.
-* **Read** - The user can view the workflow/task/secret/tags, but cannot modify or run them.
-* **Create** - The user can create the workflow/task/secret/tags.
-* **Update** - Allows the user to update the workflow/task/secret/tags. Requires Metadata API role for this.
-* **Execute** - Allows the user to run the workflow/task/secret/tags. Requires Worker role for this.
-* **Delete** - Allows the user to delete the workflow/task/secret/tags. Requires Metadata API role for this.
-5. Once they have been added, the table will display the selection. It is possible to add, change or remove access from here.
-
-:::note 
-When providing permission for tasks, you can specify a domain. This allows you to direct all traffic to a specific task instance without specifying it in the API.
-:::
+   * **Read** - The user can view the entities, but cannot modify or run them.
+   * **Create** - The user can create the entities.
+   * **Update** - Allows the user to update the entities. Requires Metadata API role for this.
+   * **Execute** - Allows the user to run the entities. Requires Worker role for this.
+   * **Delete** - Allows the user to delete the entities. Requires Metadata API role for this.
+5. Click **Add Permissions**.
 
 ## Generating Token​
 
-The access keys created above can be used to create JWT to authenticate the user and allow a connection to the Conductor server. All of the [Conductor SDKs](/content/category/sdks) support this authentication step. When using a Conductor SDK, the Key & Secret are provided to the SDK, and the authentication is handled automatically.
-
-A JWT may be created outside of the SDK via an API call. Here's an example call to the Orkes Playground:
+Access keys can be used to create JWTs for authenticating connections to the Conductor server. All of the [Conductor SDKs](/content/category/sdks) support this authentication. When using a Conductor SDK, the key and secret are provided to the SDK, and the authentication is handled automatically.
 
+Alternatively, create a JWT via an API call. Here's an example call to the Orkes Playground:
 
 ```c
 curl -s -X "POST" "https://play.orkes.io/api/token" \
@@ -83,9 +90,10 @@ curl -s -X "POST" "https://play.orkes.io/api/token" \
  {"token":"<JWT Token>"}
  ```
 
- Sending the Key Id and Secret generates a JWT. This JWT can be used to make calls to the Conductor instance. The header for authentication is **X-Authorization:**.
+Sending the key Id and secret generates a JWT. This JWT can be used to make calls to the Orkes Conductor cluster. The header for authentication is `X-Authorization:`.
+
 
-For example, this call to the **super_weather** workflow uses a JWT token to get the weather in Beverly Hills, CA:
+For example, this call to the **_super_weather_** workflow uses a JWT token to get the weather in Beverly Hills, CA:
 
 ```c
 curl -s -X "POST" "https://play.orkes.io/api/workflow/super_weather" \
@@ -98,7 +106,7 @@ curl -s -X "POST" "https://play.orkes.io/api/workflow/super_weather" \
 
 <details><summary>Example Application Setup</summary>
 <p>
-Let’s consider that two programs have access to Conductor workflows. Both these workflows rely on a single task, i.e., Task X, which is performed by a worker application Worker X.
+Let’s consider that two programs have access to Orkes Conductor workflows. Both these workflows rely on a single task, i.e., Task X, which is performed by a worker application Worker X.
 
 One way to handle this is to create a single application with access to Workflow 1, Workflow 2, and Task X and supply keys/secrets from the application to Program 1, Program 2, and Worker X. But this violates the principle of least privilege, where applications should only have access to the endpoints they require (E.g., Here Worker X should not have access to execute the two workflows).