From 6d80f251dfec69574c79df933a6f2d53663e51b9 Mon Sep 17 00:00:00 2001 From: sr-remsha <46220620+sr-remsha@users.noreply.github.com> Date: Wed, 14 Aug 2024 17:41:31 +0200 Subject: [PATCH] feat: add per-request key document (#171) * per-request key document * review * review * review --- docs/Roles and Access Control/3.API Keys.md | 57 +++++++++++++++++++++ 1 file changed, 57 insertions(+) diff --git a/docs/Roles and Access Control/3.API Keys.md b/docs/Roles and Access Control/3.API Keys.md index 04a1e2ce..0dd488ff 100644 --- a/docs/Roles and Access Control/3.API Keys.md +++ b/docs/Roles and Access Control/3.API Keys.md @@ -1,5 +1,7 @@ # Roles and Access Control for API Keys +## API Keys + API keys can be used not only for [authentication](/Auth/programmatic-auth), but also to manage access to system resources and apply restrictions on such access. This is done via assigning of **roles** to API keys. Roles must be associated with specific system resources such as models, applications, addons and assistants. @@ -33,3 +35,58 @@ To create and configure access control for API keys: ``` > In [settings](https://github.com/epam/ai-dial-core?tab=readme-ov-file#dynamic-settings), you can get familiar with the description of the configuration parameters. Refer to [configuration file](https://github.com/epam/ai-dial-core/blob/development/sample/aidial.config.json) to view the full example. + +## Per-Request Keys + +Per-request keys are used to manage access to user files for applications, enable open telemetry for tracing and realize cost control in a lifespan of a particular request. + +Per-request keys are generated by AI DIAL Core, when it is making a request to the application and is valid only during the lifetime of this particular request from the Core to the application. + +### How It Works + +* Let's consider that AI DIAL Core can receive an initial request from AI DIAL Chat or any of its clients. Such request we will call **root** requests. Example: `AI DIAL Chat --> AI DIAL Core` +* AI DIAL Core can perform a series of requests to realize the initial request - let's call them **non-root** requests. Example: `AI DIAL Chat --> AI DIAL Core --> Application A --> AI DIAL Core --> Application B...` + +**Root Request**: + +1. AI DIAL Core checks that the caller (chat user or application) has enough permissions and limits (based on the [configuration](#api-keys)) to perform the request and generates a new per-request key specifically for this request. +2. AI DIAL Core stores an additional data associated with the per-request key either in memory or in Redis. The data may include but is not limited to: JWT of the user or API key of the application, `trace-id`, `core-parent-span-id`, list of the user files attached to the request. +3. AI DIAL Core passes the per-request key to the application or model adapter in the API-key header. The application or model adapter then send the per-request key back to AI DIAL Core using the same API-key header for model requests or file storage API requests. +4. AI DIAL Core invalidates the per-request key when the request is completed. + +**Non-root Requests**: + +1. For all non-root requests, AI DIAL Core checks, that the **incoming** per-request key is valid and known (the one from the root request). +2. It checks the permissions of the caller and then generates and saves a new **outgoing** per-request key. This key is also associated with specific data: all data from the root request (its parent request) and the necessary data for the current request. +3. AI DIAL Core passes this new outgoing per-request key in the request header. The application or model adapter then send the per-request key back to AI DIAL Core using the same API-key header for model requests or file storage API requests. +4. AI DIAL Core invalidates the outgoing per-request key when the request is completed. + +### Calculating Costs & Limits + +Per-request keys can be used to attribute costs and limits incurred by a request to a model to the user or application that initiated the request. + +To attribute costs and limits to the request originator, `traceparent` should be included in the request header. `trace-id` is saved throughout the lifespan of the request in memory or in Redis. + +### Gathering Statistics + +For calculating statistics, AI DIAL Core uses `trace-id` and `core-parent-span-id` that are stored in the additional data linked to the per-request key. + +### Files Sharing + +Initially, AI DIAL Core verifies the permissions and limits of the request originator using the JWT or API Key associated with the initial request. It then generates a per-request key and links specific user files to it. Throughout the duration of the per-request key and across the entire call stack, AI DIAL Core uses this associated data to determine access rights for the application. If the application attempts to share a file which is not in the list of files associated with the per-request key or directly accessible to this application, the request results in 403 Forbidden error. + +To share the output files with the user, AI DIAL Core grants a full access to the authorized application to a specific output folder in the user's bucket. + +To provide the path of the folder for output files, we add `appdata` field to the response for the [GET /v1/bucket](https://epam-rail.com/dial_api#tag/Files/paths/~1v1~1bucket/get). If this request is made with a per-request key the response will contain `appdata` with the path to the shared folder, including the user's bucket and the correct `deployment-id` for the application as registered in the AI DIAL Core configs. + +```json +{ + "bucket": "{application-bucket-id}", + "appdata": "{user-bucket-id}/appdata/{deployment-id}", +} +``` + +### Telemetry Tracing + +For tracing open telemetry, `traceparent` should be included in the request header. The open telemetry tracing does not interfere with the limits, statistics or file sharing. +