chore: add documentation - idp configuration (#116)

*chore: add idp cofiguration --------- Co-authored-by: sr-remsha <[email protected]>
epam · Jun 6, 2024 · 480f69a · 480f69a
1 parent 02d1f82
commit 480f69a
Show file tree

Hide file tree

Showing 7 changed files with 717 additions and 59 deletions.
diff --git a/docs/Deployment/idp-configuration/auth0.md b/docs/Deployment/idp-configuration/auth0.md
@@ -0,0 +1,108 @@
+
+<!-- omit from toc -->
+# How to Set Auth0 as Identity Provider
+
+<div class="docusaurus-ignore">
+
+<!-- omit from toc -->
+# Table of Contents
+
+- [Introduction](#introduction)
+- [Configuration Guidelines](#configuration-guidelines)
+  - [Configure Auth0](#configure-auth0)
+  - [Configure AI DIAL](#configure-ai-dial)
+    - [AI DIAL Chat Settings](#ai-dial-chat-settings)
+    - [AI DIAL Core Settings](#ai-dial-core-settings)
+    - [Assignment of Roles](#assignment-of-roles)
+
+</div>
+
+## Introduction
+
+This basic tutorial demonstrates how to configure an application in [Auth0](https://auth0.com/docs/get-started) and integrate it with AI DIAL for identity and access management.
+
+In AI DIAL, you can assign roles to Models, Applications, Addons, and Assistants to restrict the number of tokens that can be transmitted in a specific time frame. These roles and their limitations can be created in external systems and then assigned in AI DIAL's configuration.
+
+## Configuration Guidelines
+
+### Configure Auth0
+
+> [!TIP]
+> Replace `<chat_url>` with the actual address of your AI DIAL Chat application.
+
+Follow these steps to configure Auth0:
+
+1. **Create Tenant:** create a new tenant and save its name. Refer to [Auth0 documentation](https://auth0.com/docs/get-started/auth0-overview/create-tenants) to learn how to do it.
+1. **Create Application:** create an [Application](https://auth0.com/docs/get-started/auth0-overview/create-applications). Set a name and choose `Regular Web Applications`.
+1. **Configure Application Settings:** in the [**Applications/Settings**](https://auth0.com/docs/get-started/applications/application-settings) section, set the following parameters:
+    - Obtain and save **Domain**,**Client ID** and **Client secrets** generated for your application.
+    - Allowed Callback URLs: `https://<chat_url>/api/auth/callback/auth0`
+1. **Create API:** in the **Applications/APIs** section, configure a new [**API**](https://auth0.com/docs/get-started/apis/api-settings).
+1. **Create Users:** in the **User Management/Users** section, create necessary [Users](https://auth0.com/docs/manage-users/user-accounts/create-users).
+1. (Optional) **Create and Assign Roles:** in the **User Management/Roles** section, create necessary [Roles](https://auth0.com/docs/manage-users/access-control/configure-core-rbac/roles/create-roles).
+1. (Optional) **Create Action:** in the **Actions/Library** section, create a necessary [Action](https://auth0.com/docs/customize/actions/write-your-first-action#create-an-action) and [Deploy](https://auth0.com/docs/customize/actions/write-your-first-action#deploy-the-action) it. Action parameters:
+   - Name: `DIAL role`
+   - Trigger: `Login/Post Login`
+   - Runtime: `Node 18`
+   - Add the following code in the Actions Code Editor:
+     ```js
+     exports.onExecutePostLogin = async (event, api) => {
+       if (event.authorization) { 
+         api.accessToken.setCustomClaim("dial_roles", event.authorization.roles);
+         api.accessToken.setCustomClaim('email', event.user.email);
+       }
+     };
+     ```   
+1. (Optional) **Configure the Login Flow:** in the **Actions/Flows** section, choose `Login`, add a custom action `DIAL role` to `Flow` and apply the change. Refer to [Auth0](https://auth0.com/docs/customize/actions/flows-and-triggers) documentation to learn more.
+
+### Configure AI DIAL
+
+By configuring both AI DIAL Chat and AI DIAL Core with the necessary environment variables, you will enable them to work together seamlessly with Identity Provider for authentication and authorization purposes.
+
+#### AI DIAL Chat Settings
+
+Add the following environment variables to AI DIAL Chat configuration. Refer to [AI DIAL Chat](https://github.com/epam/ai-dial-chat/blob/development/apps/chat/README.md#environment-variables) for more details.
+
+  ```yaml
+  AUTH_AUTH0_HOST: "<auth0_domain>"
+  AUTH_AUTH0_CLIENT_ID: "<auth0_client_id>"
+  AUTH_AUTH0_CLIENT_SECRET: "<auth0_client_secret>"
+  AUTH_AUTH0_AUDIENCE: "<auth0_api_audience>" 
+  ```
+
+#### AI DIAL Core Settings
+
+Add the following parameters to AI DIAL Core **static** settings. Refer to [AI DIAL Core](https://github.com/epam/ai-dial-core?tab=readme-ov-file#static-settings) for more details.
+
+  ```yaml
+  aidial.identityProviders.auth0.jwksUrl: "https:///<auth0_domain>/.well-known/jwks.json"
+  aidial.identityProviders.auth0.issuerPattern: '^https:\/\/${auth0_domain_name}\.eu\.auth0\.com.*$'
+  aidial.identityProviders.auth0.loggingKey: "sub"
+  aidial.identityProviders.auth0.loggingSalt: "loggingSalt"
+  aidial.identityProviders.auth0.rolePath: "dial_roles"
+  ```
+
+#### Assignment of Roles
+
+Once all the above steps are completed, including the ones marked as **Optional**, you can assign roles to Models, Applications, Addons, and Assistants.
+
+In AI DIAL Core:
+
+* [Static settings](https://github.com/epam/ai-dial-core?tab=readme-ov-file#static-settings): as value for `aidial.identityProviders.auth0.rolePath` provide a claim from Auth0.
+* [Dynamic settings](https://github.com/epam/ai-dial-core?tab=readme-ov-file#dynamic-settings): for `userRoles` provide a specific claim value. 
+
+In this example, `auth0-role-name` role from the `"dial_roles"` claim is configured for `chat-gpt-35-turbo` model:
+
+  ```yaml
+  # Dynamic settings of AI DIAL Core
+  "models": {
+      "chat-gpt-35-turbo": {
+        "type": "chat",
+        "endpoint" : "http://localhost:7001/v1/openai/deployments/gpt-35-turbo/chat/completions",
+        "upstreams": [
+          {"endpoint": "http://localhost:7001", "key": "modelKey1"}
+        ],
+        "userRoles": ["auth0-role-name"]
+      }
+  }
+  ```
diff --git a/docs/Deployment/idp-configuration/cognito.md b/docs/Deployment/idp-configuration/cognito.md
@@ -1,12 +1,7 @@
 
 <!-- omit from toc -->
-
 # How to Set AWS Cognito as Identity Provider
 
-## Introduction
-
-This basic tutorial demonstrates the steps to create a user pool in [AWS Cognito](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-identity-pools.html) and use it as an identity and access management solution for AI DIAL users.
-
 <div class="docusaurus-ignore">
 
 <!-- omit from toc -->
@@ -18,64 +13,95 @@ This basic tutorial demonstrates the steps to create a user pool in [AWS Cognito
   - [Configure AI DIAL](#configure-ai-dial)
     - [AI DIAL Chat Settings](#ai-dial-chat-settings)
     - [AI DIAL Core Settings](#ai-dial-core-settings)
+    - [Assignment of Roles](#assignment-of-roles)
 
 </div>
 
+## Introduction
+
+This basic tutorial demonstrates the steps to create a user pool in [AWS Cognito](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-identity-pools.html) and use it as an identity and access management solution for AI DIAL users.
+
+In AI DIAL, you can assign roles to Models, Applications, Addons, and Assistants to restrict the number of tokens that can be transmitted in a specific time frame. These roles and their limitations can be created in external systems and then assigned in AI DIAL's configuration.
+
 ## Configuration Guidelines
 
 ### Configure AWS Cognito
 
-To configure AWS Cognito, you can follow these steps:
+> [!TIP]
+> Replace `<chat_url>` with the actual address of your AI DIAL Chat application.
 
-1. Begin by creating a user pool. You can refer to the official AWS documentation for detailed instructions on how to create a user pool. Here is the link: [Create User Pool](https://docs.aws.amazon.com/cognito/latest/developerguide/tutorial-create-user-pool.html).
-2. Once the user pool is set up, you can proceed to create users within the pool. The AWS documentation provides guidance on how to sign up users in your application. You can find the instructions here: [Create User](https://docs.aws.amazon.com/cognito/latest/developerguide/signing-up-users-in-your-app.html).
-3. Next, you will need to create an app client specifically for this user pool. This app client will be responsible for integrating your application with the user pool. The AWS documentation offers detailed instructions on configuring app integration with user pools. You can access the instructions here: [Create App Client for User Pool](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-pools-configuring-app-integration.html).
-4. Under the **App client settings** section, set the following parameters:
-
-    - Callback URL(s): Enter the callback function URL as follows
-
-      ```
-      https://<chat_url>/api/auth/callback/cognito
-      ```
-
-      Replace `<chat_url>` with the actual address of your AI DIAL Chat application.
-
-    - OAuth 2.0 Allowed OAuth Flows: Select "Authorization code grant".
-    - OAuth 2.0 Allowed OAuth Scopes: Enable the following scopes:
-      - email
-      - openid
-      - profile
-    - Enabled Identity Providers: Select "Cognito user pool".
+Follow these steps to configure AWS Cognito:
+
+1. **Create User Pool:** refer to [AWS documentation](https://docs.aws.amazon.com/cognito/latest/developerguide/tutorial-create-user-pool.html) for detailed instructions on how to create a User Pool.
+1. **Configure Application Client:** during the creation of a user pool, navigate to the section **Integrate your app** (you can access it later under **App Integration/Create App Client**) and create the following settings. Refer to [AWS documentation](https://docs.aws.amazon.com/cognito/latest/developerguide/user-pool-settings-client-apps.html) for details.
+    - **App client name**: provide a relevant and descriptive name for the client.
+    - **Client secret**: select the option to `Generate a client secret`
+    - **Allowed callback URLs**: enter `https://<chat_url>/api/auth/callback/cognito`
+    - **Authentication flows**: enable `ALLOW_CUSTOM_AUTH` `ALLOW_REFRESH_TOKEN_AUTH` and `ALLOW_USER_SRP_AUTH`.
+    - **OpenID Connect scopes**: select `OpenID` `Email` `Profile`
+1. **Create Cognito Domain:** when setting up a user pool, navigate to the **Hosted authentication pages**. If the **Use the Cognito Hosted UI** option is enabled, you'll configure your domain here. Alternatively, you can access this configuration later by going to **App Integration/Domain/Actions**. Refer to [AWS documentation](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-userpools-server-contract-reference.html) for details.
+1. **Create Users:** in the **User polls/Users** section, create necessary [Users](https://docs.aws.amazon.com/cognito/latest/developerguide/how-to-create-user-accounts.html#creating-a-new-user-using-the-console).
+1.  **Collect Configuration Parameters:** you will need them for AI DIAL configuration.
+    - In the **Amazon Cognito/User pools/Pool name** section, record **User pool ID** and **Token signing key URL**. 
+    - In **App Integration/App client list**, click on the specific app client name to obtain the **Client ID** and**Client secret** - record them as well.
+1. (Optional) **Create and Assign Group:** in the **User polls/Groups** section, create necessary [Groups](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-pools-user-groups.html#creating-a-new-group-using-the-console) and assign to `User` created in the previous step.
 
 
 ### Configure AI DIAL
 
 By configuring both AI DIAL Chat and AI DIAL Core with the necessary AWS Cognito environment variables, you will enable them to work together seamlessly with AWS Cognito for authentication and authorization purposes.
+
 To configure AI DIAL Chat and AI DIAL Core to work with AWS Cognito, follow these steps:
 
 #### AI DIAL Chat Settings
 
 Add the following environment variables to AI DIAL Chat configuration. Refer to [AI DIAL Chat](https://github.com/epam/ai-dial-chat/blob/development/apps/chat/README.md#environment-variables) to learn more.
-
-      ```
-      AUTH_COGNITO_CLIENT_ID: "<client_id>"  # client ID of your AWS Cognito app client integration.
-      AUTH_COGNITO_HOST: "<cognito_host>" # URL consisting of the Cognito Identity endpoint and User Pool ID.
-      AUTH_COGNITO_NAME: "<cognito_client_name>" # name of your AWS Cognito app client integration
-      AUTH_COGNITO_SECRET: "<client_secret>" # client secret of your AWS Cognito app client integration
-      ```
-> `cognito_host` example: `https://cognito-idp.<region>.amazonaws.com/<my-pool-id>`
+
+  ```yaml
+  AUTH_COGNITO_CLIENT_ID: "<cognito_client_id>"
+  AUTH_COGNITO_HOST: "<cognito_host>"
+  AUTH_COGNITO_SECRET: "<cognito_client_secret>"
+  ```
+
+> [!TIP]    
+> `cognito_host` example: `https://cognito-idp.<cognito_region>.amazonaws.com/<cognito_pool-id>`
 
 #### AI DIAL Core Settings
 
-Add the following parameters to AI DIAL Core. Refer to [AI DIAL Core](https://github.com/epam/ai-dial-core?tab=readme-ov-file#configuration) configuration to learn more.
+Add the following parameters to AI DIAL Core **static** settings. Refer to [AI DIAL Core](https://github.com/epam/ai-dial-core?tab=readme-ov-file#static-settings) for more details.
+
+  ```yaml
+  aidial.identityProviders.cognito.jwksUrl: "<cognito_jwks_uri>"
+  aidial.identityProviders.cognito.rolePath: "cognito:groups"
+  aidial.identityProviders.cognito.issuerPattern: '^https:\/\/cognito-idp\.<cognito_region>\.amazonaws\.com.+$'
+  aidial.identityProviders.cognito.loggingKey: "sub"
+  aidial.identityProviders.cognito.loggingSalt: "loggingSalt"
+  ```
 
-      ```
-      aidial.identityProviders.cognito.jwksUrl: "<token_url>" # URL to jwks token
-      aidial.identityProviders.cognito.rolePath: "roles"
-      aidial.identityProviders.cognito.issuerPattern: '^https:\/\/cognito-idp\.<region>\.amazonaws\.com.+$'
-      aidial.identityProviders.cognito.loggingKey: "email"
-      aidial.identityProviders.cognito.loggingSalt: "loggingSalt"
-      ```
-      
-> `token_url` example: `https://cognito-idp.<region>.amazonaws.com/<my-pool-id>/.well-known/jwks.json`
+> [!TIP]
+> `cognito_jwks_uri` example: `https://cognito-idp.<cognito_region>.amazonaws.com/<cognito_pool-id>/.well-known/jwks.json`
+
+#### Assignment of Roles
+
+Once all the above steps are completed, including the ones marked as **Optional**, you can assign roles to Models, Applications, Addons, and Assistants.
+
+In AI DIAL Core:
+
+* [Static settings](https://github.com/epam/ai-dial-core?tab=readme-ov-file#static-settings): as value for `aidial.identityProviders.cognito.rolePath` provide a claim from Cognito.
+* [Dynamic settings](https://github.com/epam/ai-dial-core?tab=readme-ov-file#dynamic-settings): for `userRoles` provide a specific group name as a claim value. 
+
+In this example, `"cognito-group-name"` role from the `"cognito:groups"` claim is configured for `chat-gpt-35-turbo` model:
 
+  ```yaml
+    # Dynamic settings of AI DIAL Core
+  "models": {
+      "chat-gpt-35-turbo": {
+        "type": "chat",
+        "endpoint" : "http://localhost:7001/v1/openai/deployments/gpt-35-turbo/chat/completions",
+        "upstreams": [
+          {"endpoint": "http://localhost:7001", "key": "modelKey1"}
+        ],
+        "userRoles": ["cognito-group-name"]
+      }
+  }
+  ```