|
| 1 | +--- |
| 2 | +type: "docs" |
| 3 | +title: "Configure Identity Providers" |
| 4 | +linkTitle: "Configure Identity Providers" |
| 5 | +weight: 35 |
| 6 | +no_list: true |
| 7 | +hide_readingtime: true |
| 8 | +description: "Declare reusable identity providers and reference them from sources and reactions" |
| 9 | +--- |
| 10 | + |
| 11 | +**Identity providers** let {{< term "Source" "sources" >}} and {{< term "Reaction" "reactions" >}} authenticate with databases and external services without hardcoding credentials in each component. They are declared once at the top of the Drasi Server config and referenced by `id` from any source or reaction that needs to authenticate. |
| 12 | + |
| 13 | +This page covers how to define identity providers and reference them. Per-provider configuration (auth methods, plugin-specific fields) is documented below. |
| 14 | + |
| 15 | +## Define Identity Providers |
| 16 | + |
| 17 | +Identity providers live in a top-level `identityProviders` array, alongside `sources`, `queries`, and `reactions`: |
| 18 | + |
| 19 | +```yaml |
| 20 | +# server.yaml |
| 21 | +host: 0.0.0.0 |
| 22 | +port: 8080 |
| 23 | + |
| 24 | +identityProviders: |
| 25 | + - kind: <provider-kind> |
| 26 | + id: <unique-id> |
| 27 | + # ...provider-specific fields... |
| 28 | + |
| 29 | +sources: |
| 30 | + - kind: postgres |
| 31 | + id: orders-db |
| 32 | + # ... |
| 33 | + identityProvider: <unique-id> # references the entry above |
| 34 | + |
| 35 | +reactions: |
| 36 | + - kind: storedproc-postgres |
| 37 | + id: writer |
| 38 | + # ... |
| 39 | + identityProvider: <unique-id> # references the entry above |
| 40 | +``` |
| 41 | +
|
| 42 | +In **multi-instance mode**, `identityProviders` can also be declared per-instance under `instances[].identityProviders`. References from a source or reaction resolve against the providers declared on the **same instance** — providers are not shared across instances. |
| 43 | + |
| 44 | +## Supported identity provider kinds |
| 45 | + |
| 46 | +| Kind | Type | Description | |
| 47 | +|---|---|---| |
| 48 | +| [`password`](#password-provider) | Built-in | Static username/password credentials. No plugin install required. | |
| 49 | +| [`azure`](#azure-provider) | Plugin (`identity-azure`) | Azure Entra ID authentication. Supports managed identity, workload identity, and developer-tools credentials. | |
| 50 | +| [`aws`](#aws-provider) | Plugin (`identity-aws`) | AWS IAM authentication for RDS/Aurora. Supports role assumption (`roleArn`) and IRSA on EKS. | |
| 51 | +| `application` | Programmatic only | Delegates to a host-supplied Rust closure. Not configurable via YAML — only usable when embedding DrasiLib as a library. See [example](https://github.com/drasi-project/drasi-core/tree/main/examples/lib/application-identity-provider). | |
| 52 | + |
| 53 | +### Password Provider |
| 54 | + |
| 55 | +The `password` provider is built into `drasi-lib` and works in every Drasi Server build — no plugin install is needed. |
| 56 | + |
| 57 | +```yaml |
| 58 | +identityProviders: |
| 59 | + - kind: password |
| 60 | + id: pg-password |
| 61 | + username: drasi |
| 62 | + password: ${PG_PASSWORD} |
| 63 | +``` |
| 64 | + |
| 65 | +**Fields:** |
| 66 | + |
| 67 | +| Field | Type | Required | Description | |
| 68 | +|---|---|---:|---| |
| 69 | +| `username` | string \| ConfigValue | Yes | Username returned as part of the credentials. | |
| 70 | +| `password` | string \| ConfigValue | Yes | Password returned as part of the credentials. | |
| 71 | + |
| 72 | +The provider returns the same `UsernamePassword` credentials on every call. Use it for development, testing, and any deployment where short-lived cloud tokens are not required. For production against cloud-managed databases, prefer the [Azure](#azure-provider) or [AWS](#aws-provider) providers, which fetch fresh tokens on every call. |
| 73 | + |
| 74 | +### Azure Provider |
| 75 | + |
| 76 | +The `azure` provider (plugin `identity-azure`) authenticates against Azure Entra ID (formerly Azure AD) and returns short-lived OAuth tokens. It supports four authentication methods, selected via the `authMethod` field. Fresh tokens are acquired on every credential request. |
| 77 | + |
| 78 | +Typical targets: Azure Database for PostgreSQL / MySQL with Entra auth enabled, and other Azure services that accept Entra tokens. |
| 79 | + |
| 80 | +**Common fields:** |
| 81 | + |
| 82 | +| Field | Type | Required | Description | |
| 83 | +|---|---|---:|---| |
| 84 | +| `authMethod` | enum | No | One of `managed_identity` (default), `managed_identity_user_assigned`, `workload_identity`, `developer_tools`. | |
| 85 | +| `identityName` | string \| ConfigValue | Yes | Identity name used for authentication. For database scenarios this must match the PostgreSQL/MySQL role name (for example `my-app-identity` or `user@tenant.onmicrosoft.com`). | |
| 86 | +| `clientId` | string \| ConfigValue | Conditional | **Required** when `authMethod` is `managed_identity_user_assigned`. Client ID of the user-assigned managed identity. | |
| 87 | +| `scope` | string \| ConfigValue | No | Custom token scope. Defaults to the Azure OSSRDBMS scope (`https://ossrdbms-aad.database.windows.net/.default`). Override for non-PostgreSQL targets (for example `https://graph.microsoft.com/.default`). | |
| 88 | + |
| 89 | +#### `managed_identity` (default) |
| 90 | + |
| 91 | +For Azure VMs, App Service, Functions, or Container Apps with a **system-assigned** managed identity enabled. The token is fetched from the platform's IMDS endpoint; no client ID is needed. |
| 92 | + |
| 93 | +**Needs:** `identityName` matching the database role mapped to this managed identity. |
| 94 | + |
| 95 | +```yaml |
| 96 | +identityProviders: |
| 97 | + - kind: azure |
| 98 | + id: aca-identity |
| 99 | + identityName: my-aca-app |
| 100 | + authMethod: managed_identity |
| 101 | +``` |
| 102 | + |
| 103 | +#### `managed_identity_user_assigned` |
| 104 | + |
| 105 | +For compute resources with a **user-assigned** managed identity attached. The `clientId` selects which identity to use when more than one is available. |
| 106 | + |
| 107 | +**Needs:** `identityName` matching the database role; `clientId` of the user-assigned identity. |
| 108 | + |
| 109 | +```yaml |
| 110 | +identityProviders: |
| 111 | + - kind: azure |
| 112 | + id: assigned-identity |
| 113 | + identityName: my-app-identity |
| 114 | + authMethod: managed_identity_user_assigned |
| 115 | + clientId: ${AZURE_CLIENT_ID} |
| 116 | +``` |
| 117 | + |
| 118 | +#### `workload_identity` |
| 119 | + |
| 120 | +For AKS clusters configured with Entra Workload Identity. The provider reads the federated token from the file path injected by AKS. |
| 121 | + |
| 122 | +**Needs:** `identityName` matching the database role; the following environment variables set by AKS on the pod: `AZURE_TENANT_ID`, `AZURE_CLIENT_ID`, `AZURE_FEDERATED_TOKEN_FILE`. |
| 123 | + |
| 124 | +```yaml |
| 125 | +identityProviders: |
| 126 | + - kind: azure |
| 127 | + id: aks-workload |
| 128 | + identityName: my-app-identity |
| 129 | + authMethod: workload_identity |
| 130 | +``` |
| 131 | + |
| 132 | +#### `developer_tools` |
| 133 | + |
| 134 | +Uses the credential chain from `az login`, Visual Studio, or other Azure developer tools. Intended for local development. |
| 135 | + |
| 136 | +**Needs:** `identityName` set to your Entra principal name (typically the email used with `az login`), and a matching database role with an AAD security label. |
| 137 | + |
| 138 | +```yaml |
| 139 | +identityProviders: |
| 140 | + - kind: azure |
| 141 | + id: local-dev |
| 142 | + identityName: "user@example.com" |
| 143 | + authMethod: developer_tools |
| 144 | +``` |
| 145 | + |
| 146 | +For full plugin details (database setup, troubleshooting), see the [`drasi-identity-azure` README](https://github.com/drasi-project/drasi-core/blob/main/components/identity/azure/README.md). |
| 147 | + |
| 148 | +### AWS Provider |
| 149 | + |
| 150 | +The `aws` provider (plugin `identity-aws`) authenticates against AWS IAM and generates IAM auth tokens for RDS/Aurora. It picks up credentials from the standard AWS credential chain (instance metadata, environment variables, shared profiles, IRSA on EKS) and optionally assumes a role via STS before issuing tokens. |
| 151 | + |
| 152 | +The configured "variant" is determined by which optional fields are present. |
| 153 | + |
| 154 | +**Common fields:** |
| 155 | + |
| 156 | +| Field | Type | Required | Description | |
| 157 | +|---|---|---:|---| |
| 158 | +| `username` | string \| ConfigValue | Yes | IAM-authenticated database user (must be granted `rds_iam` on PostgreSQL / `AWSAuthenticationPlugin` on MySQL). | |
| 159 | +| `region` | string \| ConfigValue | No | AWS region (for example `us-west-2`). If omitted, the AWS SDK resolves it from `AWS_REGION` or the shared config. | |
| 160 | +| `roleArn` | string \| ConfigValue | No | IAM role ARN to assume via STS before generating tokens (for example `arn:aws:iam::123456789012:role/MyAccessRole`). | |
| 161 | +| `sessionName` | string \| ConfigValue | No | STS session name used when assuming `roleArn`. Defaults to `drasi-session`. | |
| 162 | + |
| 163 | +#### Ambient credentials |
| 164 | + |
| 165 | +Uses the AWS credential chain as-is. Works on EC2 / ECS / EKS with an attached role, or locally with `aws sso login` / a configured profile. |
| 166 | + |
| 167 | +**Needs:** ambient AWS credentials reachable by the AWS SDK; an RDS user granted `rds_iam`; the IAM principal must hold `rds-db:connect` on the user resource ARN. |
| 168 | + |
| 169 | +```yaml |
| 170 | +identityProviders: |
| 171 | + - kind: aws |
| 172 | + id: rds-iam |
| 173 | + username: drasi_app |
| 174 | + region: us-east-1 |
| 175 | +``` |
| 176 | + |
| 177 | +#### Assumed role (`roleArn`) |
| 178 | + |
| 179 | +Assumes a different IAM role via STS before generating database tokens. Use when the runtime principal must hop into a role that holds the actual `rds-db:connect` permission. |
| 180 | + |
| 181 | +**Needs:** ambient credentials with `sts:AssumeRole` on the target role; the assumed role granted `rds-db:connect`. |
| 182 | + |
| 183 | +```yaml |
| 184 | +identityProviders: |
| 185 | + - kind: aws |
| 186 | + id: rds-iam-prod |
| 187 | + username: drasi_app |
| 188 | + region: us-east-1 |
| 189 | + roleArn: arn:aws:iam::123456789012:role/DrasiRdsAccess |
| 190 | + sessionName: drasi-prod-session |
| 191 | +``` |
| 192 | + |
| 193 | +#### IRSA on EKS |
| 194 | + |
| 195 | +IRSA (IAM Roles for Service Accounts) is handled transparently by the AWS SDK — there is no IRSA-specific field. Configure as for ambient credentials; the SDK picks up the projected service-account token automatically. |
| 196 | + |
| 197 | +**Needs:** the EKS service account annotated for IRSA with a role that holds `rds-db:connect`. |
| 198 | + |
| 199 | +```yaml |
| 200 | +identityProviders: |
| 201 | + - kind: aws |
| 202 | + id: rds-iam |
| 203 | + username: drasi_app |
| 204 | + region: ${AWS_REGION} |
| 205 | +``` |
| 206 | + |
| 207 | +For full plugin details, see the [`drasi-identity-aws` source](https://github.com/drasi-project/drasi-core/tree/main/components/identity/aws). |
| 208 | + |
| 209 | +## Validation rules |
| 210 | + |
| 211 | +- `kind` and `id` are required on every entry. |
| 212 | +- `id` values must be unique within the `identityProviders` array. |
| 213 | +- Every `identityProvider: <id>` reference on a source or reaction must match an entry in `identityProviders`. |
| 214 | +- Non-`password` kinds must be registered (installed plugin) before server startup; otherwise startup fails with `Unknown identity provider kind: '<kind>'`. |
| 215 | +- The reference field on sources and reactions is `identityProvider` (camelCase). `identity_provider` is rejected. |
0 commit comments