Skip to main content

Auth matrix for apps

The authorization matrix is the model DIAL Core uses to enforce user consent across application dependency chains. When applications call one another, an application deep in the chain may expose sensitive data. The authorization matrix traverses the dependency graph, identifies paths to sensitive applications, and requires explicit user consent before those paths can be used.

This page is a reference for the consent model: its concepts, the consent endpoints, and the configuration that drives it. It is intended for developers building applications that depend on other applications.

Concepts​

TermDefinition
DependencyA relationship in which one application relies on another to function. Applications form dependency chains.
ConsentAn explicit agreement from a user that allows an application to access their data or act on their behalf. Consent is captured through a consent form.

The problem​

Consider an application X that returns sensitive data based on user roles. Application B can call X directly using per-request keys. If A depends on B, then A — potentially an untrusted third-party application — could reach the sensitive data in X without the user's knowledge.

Authorization matrix across an application dependency chain

The authorization matrix addresses this by traversing the dependency chain, identifying every path that leads to a sensitive application, and requiring that each such path be authorized by the user. The following graph is the example used throughout this page:

A → B, C
B → X
C → D
D → X
X → E

The Unified API includes endpoints that client applications use to request and submit consent before invoking applications that require it.

GET /v1/consent/{deployment_id}​

Requests the consent form for a deployment. DIAL Core builds the form by traversing the dependency graph from {deployment_id} toward its leaves and marking every application that requires consent.

FieldDescription
deployment_idThe application the request targets. May be a segment path for a Custom App.
consentAll dependencies with a consentRequired flag indicating whether each requires consent. Omitted when the user has already accepted, or when no dependency requires consent.
acceptedWhether the user has already accepted the consent.

For the example graph, DIAL Core returns a form in which only X requires consent:

{
  "consent": {
    "app_A": {"consentRequired": false},
    "app_B": {"consentRequired": false},
    "app_C": {"consentRequired": false},
    "app_D": {"consentRequired": false},
    "app_E": {"consentRequired": false},
    "app_X": {"consentRequired": true}
  },
  "accepted": false
}

POST /v1/consent/{deployment_id}​

Submits an accepted consent form to DIAL Core. The request body has the same shape as the consent object returned by the GET endpoint.

{
  "consent": {
    "app_A": {"consentRequired": false},
    "app_B": {"consentRequired": false},
    "app_C": {"consentRequired": false},
    "app_D": {"consentRequired": false},
    "app_E": {"consentRequired": false},
    "app_X": {"consentRequired": true}
  }
}

DIAL Core replaces any existing consent with the new one. Accepted consent is stored permanently as a resource in Redis, backed by cloud storage, at Users/<user_subject>/user_consent/<deployment_id>.

Request flow​

The following sequence shows the consent flow with DIAL Chat as the client:

  1. The user selects an application in the Catalog.
  2. DIAL Chat calls GET /v1/consent/{deployment_id}. DIAL Core computes and returns the consent form.
  3. DIAL Chat reads the accepted flag to decide whether to proceed.
  4. DIAL Chat displays the consent form.
  5. The user accepts or rejects the form.
  6. On acceptance, DIAL Chat submits the form with POST /v1/consent/{deployment_id}, and DIAL Core stores it.
  7. DIAL Core uses the stored consent to validate future chat completion requests to deployments marked consentRequired=true.

Configuration​

Dependencies and consent requirements are declared in the DIAL Core applications configuration.

consentRequired​

applications.<application_name>.features.consentRequired indicates whether an application requires consent. The default is false. When set to true, a dependent application cannot call it through a per-request key without user consent.

{
  "applications": {
    "A": {
      "endpoint": "http://localhost:7001/openai/deployments/appA/chat/completions",
      "displayName": "Forecast",
      "iconUrl": "https://host/app.svg",
      "features": {
        "consentRequired": true
      }
    },
    "B": {
      "endpoint": "http://localhost:7001/openai/deployments/appB/chat/completions",
      "displayName": "Forecast",
      "iconUrl": "https://host/app.svg",
      "dependencies": ["A"]
    }
  }
}

dependencies​

applications.<application_name>.dependencies is an array of deployments the application relies on. It is optional and absent when an application has no dependencies.

{
  "endpoint": "http://localhost:7001/openai/deployments/10k/chat/completions",
  "displayName": "Forecast",
  "dependencies": ["appB", "appC"]
}

Further reading​