Entra Workload Identities
Set up Azure DevOps federation, register an organization identity, and grant deployment access across workspaces
Entra workload identities let your deployment pipeline authenticate to SteelEngine as an application. Configure the installation's trust, register the release application in its organization, then grant the actions the pipeline needs. Human SSO and SCIM are configured separately.
Preview. Qualify your actual Azure DevOps service connection, Key Vault access and deployment tasks before replacing an existing pipeline credential. Local signed-token and worker tests do not establish customer acceptance.
How Authentication Works
- Your Azure DevOps job uses its workload identity federation service connection to obtain a short-lived Entra access token for the SteelEngine resource API.
- The Python deployer or optional Node CLI sends that token as
Authorization: Bearer <token>to/api/mcp/steelengine./api/mcp/copilotremains a compatibility alias. - SteelEngine validates the signature, expiry, configured tenant, API audience, required application role and app-only token type.
- SteelEngine matches the token's tenant, calling application ID and service principal object ID to an enabled organization identity. That identity's local grants decide which workspaces and operations it can use.
- Durable workflow execution carries an internal signed identity reference. The worker checks current trust and grants before preparing queued work. The external Entra token is not placed in the execution history.
A person does not create the pipeline's token in the dashboard. The dashboard approves the application and its permissions; Entra issues the token when the job authenticates. The Entra application role is an entry requirement. It does not assign a SteelEngine organization role or grant every action.
Before You Start
Use a compatible web, worker and migration release. Apply its complete migration chain, including 0297_workload_identities.sql and 0298_workload_organization_access.sql, before starting the new web and worker readers. Enable organizations and use an authenticated human administrator for dashboard setup.
Collect these identifiers from your identity team. None is a client secret or certificate private key:
| Value | Where It Is Used |
|---|---|
| Full token-issuing tenant GUID | Installation trust; use the complete ID, not an abbreviated tenant prefix |
| SteelEngine resource API application client GUID | Installation audience; identifies the API receiving the token |
| Resource API application ID URI | Token scope, for example api://RESOURCE-API-CLIENT-GUID/.default |
| API application-role value | Installation role, for example SteelEngine.Automation |
| Release application's client GUID | Organization identity's Application (client) ID |
| Release application's service principal object GUID | Organization identity's Service principal object ID, from Enterprise applications |
| Federated service connection | Azure DevOps job authentication and permission to use the connection |
The resource API and the calling release application are separate registrations. The object ID on App registrations is also different from the service principal object ID under Enterprise applications.
1. Configure Entra and Azure DevOps
The identity team and pipeline owner configure the external connection:
- Register the SteelEngine resource API in the intended Entra tenant. Configure v2 access tokens and the
idtypoptional access-token claim. - Expose an application role such as
SteelEngine.Automationthat permits application members. Assign that API application permission to each approved release application and grant administrator consent. - Create or select the Azure DevOps workload identity federation service connection for the release application. Use the issuer, subject and audience shown by that connection when configuring its federated credential in Entra. Copy those values exactly; their federation audience is distinct from the SteelEngine API audience.
- Authorize the intended pipeline to use the service connection. Give the identity only the separate Azure permissions needed for its tasks, including Key Vault secret-get access when applicable.
Use Microsoft's workload identity service connection setup, application-claim validation, and optional access-token claims references. Configure federation using the current connection's displayed values.
2. Configure Installation Trust
The installation operator controls which Entra authority and resource API SteelEngine accepts. You can install SteelEngine with workload authentication off and configure this later. These values are runtime configuration and do not require customer identifiers to be built into an image.
| Setting | Installation Environment | Organization Dashboard |
|---|---|---|
| Enable workload authentication | WORKLOAD_AUTH_ENABLED | Operator setup status is displayed |
| Trusted tenant, API audience, URI and required role | WORKLOAD_AUTH_PROFILE | Trust is displayed; it cannot be edited here |
| Approved release application and service principal | — | Register an identity in the organization |
| Workspace/workflow permissions and automatic access | — | Edit the identity's grants |
| Enable, verify or disable the identity | — | Enable/disable in the dashboard; verify from the pipeline |
For Helm, add this to your installation values:
app:
env:
WORKLOAD_AUTH_ENABLED: "true"
WORKLOAD_AUTH_PROFILE: '{"id":"company-automation","tenantId":"FULL-TENANT-GUID","audience":"RESOURCE-API-CLIENT-GUID","applicationIdUri":"api://RESOURCE-API-CLIENT-GUID","role":"SteelEngine.Automation"}'The worker inherits both values from app.env unless you override them in worker.env. Keep web and all workers on the same trust configuration.
For the repository's Docker Compose stack, add the same settings to its .env:
WORKLOAD_AUTH_ENABLED=true
WORKLOAD_AUTH_PROFILE='{"id":"company-automation","tenantId":"FULL-TENANT-GUID","audience":"RESOURCE-API-CLIENT-GUID","applicationIdUri":"api://RESOURCE-API-CLIENT-GUID","role":"SteelEngine.Automation"}'The Compose file forwards both values to web and the worker. Redeploy both processes after changing these settings. For a custom deployment, pass both environment values to each process explicitly.
Replace every GUID placeholder. The profile accepts exactly five fields: id, tenantId, audience, applicationIdUri and role. Its id is a local trust-profile name. audience is the resource API's client GUID; applicationIdUri is its URI, without /.default. The requested token scope appends /.default to that URI.
Permit the web process to reach login.microsoftonline.com over HTTPS for signing keys. SteelEngine derives issuer/key URLs from the configured tenant and caches/refreshes those public keys. It never stores an Entra client secret, certificate private key or access token as part of the identity registration.
Current Trust Limits
| Area | Supported Behavior |
|---|---|
| Tenant | One trusted workload tenant per installation, shared by its organizations; it can differ from the human SSO tenant |
| API audience | One resource API audience per installation; many release applications can request tokens for it |
| Required Entra role | One required application-role value; other token roles can also be present. Local SteelEngine grants remain per identity |
| Applications and organizations | Multiple identities are supported. Each service principal is bound to one organization per installation |
| Cloud | Global/commercial Entra at login.microsoftonline.com; sovereign-cloud authorities are not supported |
| Trust management | Environment configuration; multiple trust profiles and dashboard editing of installation trust are not implemented |
Private AKS networking and self-hosted SteelEngine can use global Entra. This cloud limitation concerns the identity authority. Azure Government and Azure China use separate authorities.
The single-profile limit comes from this implementation's configuration model. Changing that model would require additional multi-profile support; moving the current fields to a dashboard alone would retain the limit. There is no old/new-profile overlap window. Trust changes make earlier verification stale and can reject queued work carrying the previous trust reference; already-admitted runs retain their admission.
3. Register the Organization Identity
Open Organization settings → Workload identities using a signed-in human with Manage organization workload identities permission. Organization administrators have this permission. API keys, workload tokens and anonymous disabled-auth sessions cannot manage these registrations.
- Select Add workload identity. Enter a readable release name, the release application's client GUID and its Enterprise applications service principal object GUID.
- Choose the workspace/workflow actions described below. You cannot delegate permissions beyond your own access.
- Save the identity. It starts disabled. Review its identifiers and access, then select Edit access → Enable application access when Entra is ready.
- Retain the binding ID and current configuration revision for pipeline verification. Saving or enabling does not mark the connection verified.
- Run the verification step from your pipeline. A successful workspace-read request records the current revision, trust configuration and verification time.
External identifiers and organization ownership are immutable. Register a new identity if they change. An edit increments the revision, and concurrent stale saves are rejected. Copy refreshed revision values after an edit.
Access Across Workspaces
Under Scoped permissions, select Add workspace, choose an existing workspace once, then check its workspace-wide actions. The capture, release, secrets and smoke presets add their actions to that workspace without removing custom selections. A workspace-wide workflow action applies to all workflows in that workspace.
For narrower access, use Add workflow-specific grant in that workspace's advanced section. Select an action and enter an existing workflow ID. Changing the action retains that ID; removing the ID leaves the draft incomplete rather than granting access to all workflows. Existing workflow-specific grants remain separate from workspace-wide checkboxes. To change a workspace target, remove its scoped access group and add the intended workspace.
Each selected workspace/action or workflow/action pair is saved as an individual grant. The editor counts unique grants against the limit of 200 explicit grants and prevents saving an incomplete or over-limit draft. Remove workspace access removes only that group's explicit grants; automatic access is configured separately below.
For automatic access, an organization administrator selects actions under Automatic workspace access, or adds the capture, release, secrets or smoke preset. The selected actions apply to all active current and future workspaces in that organization. New workspaces need no repeated identity setup. SteelEngine resolves current membership at admission; it does not copy grant rows when a workspace is created.
Use Exclude workspaces for absolute exclusions. Remove conflicting explicit grants before saving. Clear workspace exclusions also removes exclusions for workspaces that are no longer listed. An empty automatic action list disables inheritance. Custom deny policies can require narrower explicit grants.
This policy grants the selected workspace actions. Separate identities are needed for organizations sharing an installation. Separate installations configure their own trust and bindings.
Provision a workspace during installation
Self-hosted installation pipelines can use an existing enabled organization workload identity to create a workspace with approved Key Vault storage. The installation operator adds the existing Workload identity ID to workspaceProvisionerIds on the target organization and vault approval in Helm. The request uses the same SteelEngine API token as the existing pipeline. This approval applies to the workspace and vault provisioning endpoint. Other Admin API endpoints use their existing credential and workflow deployment uses the identity's normal grants.
Exact Actions and Minimum Grants
These are local SteelEngine permission keys. Entra issues a token for the API's application role using api://RESOURCE-API-CLIENT-GUID/.default; it does not issue one OAuth scope per row below.
| Dashboard action | SteelEngine permission | MCP operations |
|---|---|---|
| Read workspace content. | workspace:read | steelengine_workspaces.list/get, steelengine_tables.list |
| Read workflow folders. | workspace:read_workflow_folders | steelengine_workflows.list_folders |
| Create workflow folders. | workspace:create_workflow_folders | steelengine_workflows.create_folder |
| Read redacted workspace environment metadata. | workspace:read_environment | steelengine_env.list (names only) |
| Manage workspace environment variables. | workspace:manage_environment | steelengine_env.set |
| Create workflows. | workflow:create | steelengine_workflows.create |
| Read workflows and deployment history. | workflow:read | steelengine_workflows.list/get/export/check_deployment_status/list_deployment_versions/get_deployment_version |
| Update workflow drafts. | workflow:update | steelengine_workflows.import/update |
| Deploy workflows. | workflow:deploy | steelengine_workflows.deploy_api/redeploy/revert_to_version |
| Execute workflows. | workflow:execute | steelengine_workflows.run |
| Read KB configuration metadata. | knowledge_base:read | steelengine_knowledge.list/get |
| Create KB configurations. | knowledge_base:create | steelengine_knowledge.create |
| Update KB configurations. | knowledge_base:update | steelengine_knowledge.update |
| Explicitly clean up KB configurations. | knowledge_base:delete | steelengine_knowledge.delete |
| Discover/read connector configuration. | knowledge_base:read_connectors | steelengine_knowledge.connector_types/list_connectors/get_connector |
| Create/update paused connector definitions. | knowledge_base:create_connectors, knowledge_base:update_connectors respectively, plus credential:use | steelengine_knowledge.add_connector/update_connector |
| Remove connector configuration, retaining documents. | knowledge_base:delete_connectors | steelengine_knowledge.delete_connector |
| Read masked provider configuration. | workspace:read_byok | steelengine_env.list_byok |
| Create/replace workspace provider keys. | workspace:set_byok | steelengine_env.set_byok |
| Explicitly remove a workspace provider key. | workspace:delete_byok | steelengine_env.delete_byok |
| Read logical database definitions. | database:read | steelengine_tables.list_databases/get_database |
| Create/configure logical databases. | database:create, database:update | steelengine_tables.create_database/update_database respectively |
| Archive an empty logical database. | database:delete | steelengine_tables.delete_database |
| Read table definitions. | table:read | steelengine_tables.list_definitions/get |
| Create/rename tables. | table:create, table:update | steelengine_tables.create/rename respectively |
| Add compatible optional columns. | table:manage_schema | steelengine_tables.add_column |
| Archive tables. | table:delete | steelengine_tables.delete |
tools/list advertises the permitted operations and their input schemas. Each call checks the target resource and current grants. Protected operations require confirm: true.
Verify a rollback before redeploying
Call these operations on steelengine_workflows using the same workflow ID.
| Operation | Arguments | Result |
|---|---|---|
list_deployment_versions | workflowId | Versions and their isActive flags |
get_deployment_version | workflowId, versionId such as "3" | The version and its saved graph as deployedState |
revert_to_version | workflowId, versionId, confirm: true | Restored draft and requiresRedeploy: true |
export | workflowId | Current draft in data.json |
redeploy | workflowId, confirm: true | Deploys the verified draft |
If version 5 is live, read version 3's snapshot, restore it into the draft and compare the draft export with the snapshot while version 5 stays active. The snapshot returns blocks, edges, loops and parallels with the workflow export's credential redaction. Compare those same fields in the export's state. Treat omitted block triggerMode as its default false and exclude export metadata such as color and timestamps from the comparison. Admin and MCP exports can represent those fields differently.
Once the definitions match, redeploy, check the new active version and run a smoke test. Restore and redeploy require workflow:deploy. Retained version lookup and export require workflow:read for the target workflow.
Use a positive integer version number. The lookup and restore also accept the legacy numeric version. When both selectors are present, version takes precedence and must be valid. An unavailable version returns not_found after authorization, and requests outside the granted workflow scope return permission_denied.
| Stage | Minimum actions and scope |
|---|---|
| Capture source | Source workspace read + workflow read; folder read only when enumerating folders. A workflow read grant may name one workflow. |
| Update existing target | Target workspace read for the org guard; workflow update for import; deploy for deployment; read for lookup/status/versions. Scope workflow grants to its existing ID when possible. |
| Bootstrap target workflow/folders | Add workflow create and folder create only when creating those resources; folder read when looking up bindings. The release preset includes these and update/deploy/read. |
| Set environment values | Target workspace read for the guard + manage environment. Add read environment when listing variable names. A pipeline that fetches values from Azure also needs its own Key Vault secret-get permission. |
| Smoke run | Target workspace read for the guard + workflow execute, preferably a specific workflow ID. Referenced workflows can require additional execution grants. |
| Configure KBs | Grant the required KB read/create/update actions in the target workspace. Add KB delete separately for cleanup. The knowledge preset excludes delete. |
| Configure logical databases/tables | The tables preset adds database read/create/update and table read/create/update/manage-schema. Add each resource's delete action separately for cleanup. |
Presets are conveniences and can be narrowed by unchecking actions. Use separate source/target identities and service connections when stages must have different authority. A single identity has the union of its grants in every job using that identity; stage names alone do not limit it.
KB Configuration Contract
KB workload grants apply by workspace, resource type, and action. Existing workflow/environment grants gain no KB authority. The workspace owner supplies ownership metadata for new KBs; the authenticated workload remains the actor, and organization-wide exclusions still apply.
Use steelengine_knowledge with contractVersion: 1 and an explicit workspaceId. Discovery publishes the workload-specific input schema. Successful results carry data.contractVersion: 1.
| Operation | Additional inputs | Result |
|---|---|---|
list | Optional limit (1–100, default 50) and ID-based cursor; active KBs only | Safe configurations and nextCursor or null |
get | Exact knowledgeBaseId | Safe configuration with opaque revision |
create | name, stable idempotencyKey; optional description, chunkingConfig, and supported embeddingModel | New configuration, ID, and revision |
update | Exact knowledgeBaseId, expectedRevision, stable idempotencyKey, and at least one of name, description, chunkingConfig | Updated configuration and revision |
delete | Exact knowledgeBaseId, expectedRevision, stable idempotencyKey, confirm: true | Deleted target ID and status |
The supported embedding model is text-embedding-3-small with 1536 dimensions. Default chunking is { "maxSize": 1024, "minSize": 100, "overlap": 200 }; see chunk configuration for units and bounds. Definition creation does not upload documents or start ingestion. Metadata excludes document content, connector configuration, and credentials. Workload operations do not move KBs between workspaces.
Read the current revision before update/delete. A stale token returns conflict without applying the mutation. Tokens are local to this installation; reread after import or database restoration. Retry an uncertain mutation with the exact same key and input, including the original expected revision. For seven days, a committed result is replayed only after current identity, grant, workspace, and actual resource-parent checks. A changed action/target/payload with the same actor/workspace/key conflicts. Resource changes, success audit, and retry result commit together.
Receipts describe the original committed operation, not the current configuration. After the replay window, reconcile the exact known ID and revision before using a new request key. Duplicate-name protection does not adopt or overwrite an existing KB. Deletion uses the existing soft-delete lifecycle: owned documents are archived and active connectors are paused. Retained IDs prevent retries from deleting a new KB that reused the old name. Promotion-managed KB protections still apply; there is no force/cascade or permanent purge option.
Successful mutations record the workload identity/revision, action, resource, outcome, and safe requestId correlation also returned in the result. Read/discovery requests are not a complete access log. This slice needs no new application environment variables or schema migration.
The headless example e2e/workload-identity/python_kb_config.py reuses python_deployer.py and its Azure CLI token acquisition. Run it inside an authenticated AzureCLI@2 step with the approved service connection:
python3 e2e/workload-identity/python_kb_config.py create \
--origin "$SE_ORIGIN" --scope "$SE_SCOPE" --workspace "$SE_WORKSPACE" \
--name "Release KB" --request-key "release-42-kb-create" > kb-create.json
python3 e2e/workload-identity/python_kb_config.py update \
--origin "$SE_ORIGIN" --scope "$SE_SCOPE" --workspace "$SE_WORKSPACE" \
--knowledge-base "$KB_ID" --revision "$KB_REVISION" \
--description "Configuration for release 42" --request-key "release-42-kb-update"Capture data.knowledgeBase.id and revision from the JSON result for subsequent steps. get and list are also available. Cleanup uses delete --knowledge-base ... --revision ... --request-key ... --confirm-delete and requires the separate delete grant. The example emits structured JSON, exits nonzero on failure, and performs no automatic write retry or destructive cleanup.
Logical Database and Table Configuration
These grants configure existing application-managed logical databases and tables in the authorized workspace. They do not provision database servers. Existing workflow/environment grants gain no configuration authority. The existing steelengine_tables.list operation keeps its workspace:read behavior; use list_definitions for the versioned, paginated table configuration contract.
All operations below use steelengine_tables, an explicit workspaceId, and optional contractVersion: 1. Results include data.contractVersion: 1. Discovery advertises the available operation names and field hints; server validation enforces the strict per-operation contract, including rejecting unknown fields. Database/table grants are workspace-wide by resource type and action, with existing organization-wide access and exclusions.
| Operation | Fields beyond workspace/version/operation | Result |
|---|---|---|
list_databases | Optional limit (1–100, default 50), ID-based cursor | Active databases, nextCursor or null |
get_database | Exact databaseId | Safe database definition and opaque revision |
create_database | name, stable idempotencyKey; optional description, hex color | New database and revision |
update_database | databaseId, expectedRevision, idempotencyKey; at least one of name, description, color, sortOrder | Updated database and revision |
delete_database | databaseId, expectedRevision, idempotencyKey, confirm: true | Archived databaseId, deleted: true; active tables block cleanup |
list_definitions | Optional databaseId, limit (1–100, default 50), cursor | Active tables, nextCursor or null |
get | Exact tableId | Safe table definition and revision |
create | Explicit target-local databaseId, name, schema: { columns: [...] }, idempotencyKey; optional description | New table and revision |
rename | tableId, name, expectedRevision, idempotencyKey | Renamed table and revision |
add_column | tableId, column, expectedRevision, idempotencyKey | Updated table and revision |
delete | tableId, expectedRevision, idempotencyKey, confirm: true | Archived tableId, deleted: true |
Names and columns use existing limits and validation: table/column names are at most 50 characters, start with a letter or underscore, and contain only letters, numbers and underscores. Database names are at most 50 characters; descriptions are at most 500. New schemas contain 1–1,000 columns using string, number, boolean, date, or json, with optional required/unique booleans. Column names must be unique ignoring case. add_column permits only optional, nonunique columns (required and unique omitted or false); it never converts existing values or fills rows. Duplicate names and resource limits fail safely. Table creation uses existing workspace plan limits and transactional physical storage provisioning.
Safe results contain definition IDs, names, descriptions, column names/types/constraints, timestamps, revisions, and database display settings. They omit row values, arbitrary metadata, credentials and physical SQL identifiers. Row CRUD/query/import/export, arbitrary SQL, column removal/type conversion, table moves, relationship management, force/cascade and permanent purge are unavailable through this workload contract.
Use the KB contract's seven-day exact-input retry and revision rules for these mutations too. Each successful write includes a safe requestId; resource state, physical DDL, workload audit and receipt commit together. Replays require current authority and actual resource-parent checks. Read current state before resuming after receipt expiry. Each call commits separately; a sequence that creates a database then fails to create a table retains the committed database for explicit reconciliation.
Cleanup follows the existing archive lifecycle. Archiving a table retains its owned rows and physical storage for dashboard restoration. Cleanup rejects relationships and inbound linked columns, including archived definitions, instead of modifying other tables. A database can be archived only after all its active tables are archived or otherwise removed through an authorized path. Promotion-managed protections apply to create/change/cleanup. Cleanup does not purge retained data or delete infrastructure. Ordinary Chat, user/API-key MCP, scheduled tools and workflow tools retain their existing restriction on database deletion; the explicit workload-only operation uses its separate database:delete grant.
The headless example e2e/workload-identity/python_table_config.py uses the existing Azure CLI transport and returns JSON with nonzero exit status on failure. Put operation-specific fields in a JSON file and retain the returned exact IDs/revisions:
{ "name": "Release configuration", "idempotencyKey": "release-42-database" }python3 e2e/workload-identity/python_table_config.py create_database \
--origin "$SE_ORIGIN" --scope "$SE_SCOPE" --workspace "$SE_WORKSPACE" \
--arguments-file database-create.json > database-result.jsonFor table creation, the arguments file contains databaseId, name, schema, and idempotencyKey. For cleanup it contains the exact target ID, expectedRevision, and idempotencyKey; also pass --confirm-delete. The helper performs no automatic mutation retries or cleanup. It requires no new application environment variables or migrations beyond the existing workload setup.
Paused Connector Configuration
Connector configuration has separate grants from KB CRUD. The connectors preset adds metadata/create/update and workspace-local credential:use; cleanup remains a separate selection. The update grant also permits pausing an existing connector. Every call checks the actual KB/workspace, current workload grants and revision. Creating or changing OAuth configuration requires exact workspace-local hosted OAuth credential IDs, with matching provider and scopes. Personal OAuth grants, Custom App bindings, inline API keys, account-ID fallback and credential enrollment are unavailable through this contract. Pausing does not use credentials and can stop any supported existing connector type without a credential-use grant.
Use steelengine_knowledge with contractVersion: 1 and workspaceId. connector_types returns supported registered types, canonical source-field IDs, required OAuth provider/scopes and the paused creation state. Registered API-key connector types are listed as unsupported for machine creation. Other operations require the exact knowledgeBaseId:
| Operation | Fields | Result |
|---|---|---|
list_connectors | Optional limit (1–100, default 50), ID-based cursor | Safe configurations, nextCursor |
get_connector | Exact connectorId | Configuration with opaque revision |
add_connector | connectorType, credentialId, sourceConfig, idempotencyKey, confirm: true; optional syncIntervalMinutes | Paused definition, requiresActivation: true |
update_connector | connectorId, expectedRevision, idempotencyKey; at least one of credentialId, sourceConfig, syncIntervalMinutes | Updated paused definition |
pause_connector | connectorId, expectedRevision, idempotencyKey | Paused definition, next scheduled sync cleared; requires knowledge_base:update_connectors |
delete_connector | connectorId, expectedRevision, idempotencyKey, confirm: true | Removed configuration ID and documentsRetained: true |
Source fields use the connector's declared canonical IDs and string values (at most 50 fields, 2,048 characters each). Optional disabledTagIds selects declared tags; internal tag mappings cannot be supplied. The sync interval is zero or 60–525,600 minutes, default 1,440. Configuration writes make no outbound requests, resolve no token and start no ingestion. New definitions stay paused; updates require an already paused connector. Activate through the existing human-authorized path, which validates the stored source before activation. Workload manual sync, activation, document operations and arbitrary fetch/connection proxies are unavailable.
Source updates reconcile the enabled tag mappings, reusing compatible KB tag definitions. Disabling a tag stops its future mapping without deleting shared definitions or existing document values. An update returns a conflict if any selected tag cannot be mapped to an available compatible slot; the connector, tag definitions, audit and retry receipt remain unchanged.
Workloads can pause an idle active/error connector, then update its paused configuration. A running sync returns a conflict; pause does not cancel in-flight work. Queued automatic syncs respect the paused state, including a pause racing their lease claim. Activation/resume and manual sync remain unavailable to workloads. An authorized human can activate or explicitly sync through the existing human path. Pause uses the same exact-target, revision, retry, audit and managed-resource checks as other changes, without resolving a credential or altering document/tag data.
Reads omit token material, arbitrary source extensions, sync logs/errors and document content. The KB contract's exact-input seven-day retry/revision rules apply; current credential authority is rechecked before replaying creation/update results. Definition/tag changes, audit and receipt commit together. Cleanup refuses an in-flight sync, removes only the connector configuration, and preserves existing documents and shared credentials. Replays cannot retarget a reused connector ID. KB promotion guards remain effective. No new application environment variables or migrations are required.
The headless e2e/workload-identity/python_connector_config.py reuses the Azure CLI transport. Pass operation-specific fields in --arguments-file, plus --origin, --scope, and --workspace; creation/removal also require --confirm. Keep exact IDs/revisions and retry uncertain mutations with unchanged keys/input. The helper emits JSON, exits nonzero on failure and performs no automatic ingestion or cleanup. External database blocks do not establish a standalone saved-connection resource; no new database driver or infrastructure provisioning is included.
Workspace Provider Configuration
The providers preset selects metadata read and key write for supported workspace providers. Deletion uses a separate grant. Workloads can replace or remove keys stored in encrypted PostgreSQL. Vault-backed workspace keys and organization fallback appear as metadata. Set and delete return conflict for a Vault-backed workspace key, and creating a key under a Vault storage default also returns conflict. Use the Key Vault provisioning or settings flow to configure those entries. Azure Key Vault guide
Use steelengine_env, an explicit workspaceId, and optional contractVersion: 1. Discovery lists only granted operations. Server validation rejects unknown fields and unsupported providers; the existing human workspace:manage_byok behavior remains unchanged.
| Operation | Fields | Result |
|---|---|---|
list_byok | Workspace/version only | Masked workspace configuration, exact workspace keyId and revision, organization fallback presence, and effective source and storageBackend |
set_byok creation | providerId, write-only apiKey, expectedRevision: "absent", stable idempotencyKey, confirm: true | Local key metadata and revision; conflicts if a local key exists |
set_byok replacement | providerId, exact keyId, current expectedRevision, write-only apiKey, idempotencyKey, confirm: true | Same local key ID, updated revision |
delete_byok | providerId, exact keyId, current expectedRevision, idempotencyKey, confirm: true | Deleted target ID and organization-fallback presence |
Keys must be nonblank and at most 16,384 characters. Results use a fixed mask and never return key prefixes/suffixes or ciphertext. Missing local configuration reports revision: "absent"; organization fallback exposes presence/source only. Deleting a local key may immediately select the existing organization key during runtime resolution. Organization keys remain untouched. Cleanup is blocked while a nonretired managed release binding references that provider.
Exact-ID/revision checks prevent overwriting an unrelated key or deleting a replacement that reused the provider name. Retry uncertain mutations with unchanged input/key. The shared seven-day replay window requires current admission and actual key-parent checks; cleanup replay conflicts if a replacement is present. Receipts describe the original committed action, so read current configuration before reconciliation or resuming after expiry.
PostgreSQL provider changes, workload audit and retry receipt commit together. Secret-bearing retry comparison uses a keyed digest with the existing encryption key. Results and audit records contain metadata, and the audit identifies the authenticated workload actor.
The headless e2e/workload-identity/python_provider_config.py uses the existing Azure CLI transport. Supply --origin, --scope, --workspace, and operation fields through --arguments-file; writes require --confirm. For creation, the JSON object contains providerId, apiKey, expectedRevision: "absent", and a stable idempotencyKey. Keep secret-bearing files within your pipeline's secret-handling controls. The helper emits safe JSON, returns a nonzero failure status, and performs no automatic write retries or cleanup.
4. Connect the Python Deployer
The Python reference client requires Python 3.10+ and Azure CLI. It runs inside AzureCLI@2 using the federated service connection. The Node CLI is optional.
Obtain the reviewed release's python_deployer.py and ado-python.yml, or use the repository copies under e2e/workload-identity/. The template's clientEntry parameter selects the Python file's path. For example, when the template and client are checked into your pipeline repository:
steps:
- template: e2e/workload-identity/ado-python.yml
parameters:
serviceConnection: 'SteelEngine-QA-Release'
clientEntry: 'e2e/workload-identity/python_deployer.py'
origin: 'https://steelengine.example'
scope: 'api://RESOURCE-API-CLIENT-GUID/.default'
identity: 'DASHBOARD-BINDING-ID'
revision: 2
workspace: 'GRANTED-WORKSPACE-ID'
organization: 'EXPECTED-ORGANIZATION-ID'Replace the example revision with the current dashboard revision. Copy Workload identity ID and Organization ID from the identity details, and use the workspace ID from its verification command. The organization parameter is the internal ID, rather than a display name or slug. When consuming downloaded artifacts, set the template/client paths to their downloaded locations.
The client captures the output of az account get-access-token --scope 'api://RESOURCE-API-CLIENT-GUID/.default' --output json. Keep shell tracing off and do not print that response. Use the SteelEngine resource access token; ADO federation assertions and ARM/Key Vault tokens are different credentials.
The reference preflight sends a Bearer-authenticated POST to /api/automation/workload-identity/verify:
{"workspaceId":"GRANTED-WORKSPACE-ID","workloadIdentityId":"DASHBOARD-BINDING-ID","expectedRevision":2}It then initializes MCP, sends notifications/initialized, lists tools and checks steelengine_workspaces.get → organizationId against the expected organization. Successful verification proves the selected workspace read; qualify the remaining operations separately.
Import SteelEngineClient into your existing Python deployer for subsequent calls. After creating a client with the installation origin/API scope and calling initialize():
client.call("steelengine_workflows", {
"operation": "import", "workspaceId": target_workspace,
"workflowId": existing_workflow, "json": exported_workflow, "confirm": True,
})Use each operation's documented payload schema. The transport supports this server's 2025-03-26 and 2025-11-25 MCP versions and JSON/SSE responses. It refuses redirects, sanitizes failures and performs no automatic mutation retries. After an uncertain response, reconcile known workflow/deployment IDs before retrying.
See Azure CLI token acquisition and AzureCLI@2.
Optional Node Verification and Pilot
Install the reviewed SteelEngine CLI with Node.js 22 or later. In the Azure DevOps job, expose:
env:
AZURE_TENANT_ID: $(deploymentTenantId)
AZURE_CLIENT_ID: $(deploymentApplicationClientId)
AZURE_SERVICE_CONNECTION_ID: $(deploymentServiceConnectionId)
SYSTEM_ACCESSTOKEN: $(System.AccessToken)AZURE_SERVICE_CONNECTION_ID is the ADO connection identifier, not the Entra service principal object ID. The CLI uses the agent's OIDC job environment through Microsoft's AzurePipelinesCredential. Run the command copied from the dashboard:
steelengine workload-identity verify \
--base-url 'https://steelengine.example' \
--scope 'api://RESOURCE-API-CLIENT-GUID/.default' \
--identity 'DASHBOARD-BINDING-ID' \
--workspace 'GRANTED-WORKSPACE-ID' \
--revision 2The optional workload-identity pilot --base-url ... --scope ... --manifest pilot.json exercises deterministic v1, v2 and restored/deployed-v1 workflow outputs in a disposable workspace. Its manifest contains identity/workspace/revision, expected organization, unique folder/workflow names, two workflow exports and expected outputs. Resources remain available for inspection and reconciliation. The repository's e2e/workload-identity/ado-pilot.yml runs it with the reviewed CLI and publishes its redacted report.
Key Vault, Renewal and Revocation
With native Key Vault storage, the pipeline can supply secret references during approved workspace provisioning. The SteelEngine app and workers use their managed identities to access the Vault at runtime. Azure Key Vault configuration
For pipeline-side retrieval, the agent needs its own Azure resource token and Key Vault secret-get permission. Send the retrieved value directly to a confirmed steelengine_env.set call. Environment listing returns variable names only. Keep values out of logs, artifacts, workflow exports, and reported outputs.
The Node pilot's optional keyVault manifest entry supplies vaultUrl, secretName, optional version and the SteelEngine variableName. It requests https://vault.azure.net/.default separately and supports public-cloud *.vault.azure.net vaults. See Key Vault Get Secret.
The Python transport requests an access token for each HTTP call; Azure CLI can return a valid cached token or acquire a fresh one. Qualify acquisition after expiry within your actual job lifetime. Reusing an unexpired cached token is not renewal evidence. Federation avoids storing a SteelEngine API key or release-application password for this path. Certificate-only authentication and certificate renewal are not enforced by this implementation.
Entra signing-key rotation is handled through refreshed public signing keys. Upstream application disablement can leave an already-issued token valid until expiry. Use the identity's local Disable action to block subsequent requests and queued worker preparation. Local grant/exclusion changes increment the revision; they require refreshed verification evidence but no replacement API key. Already-admitted execution and deployment compensation retain admission.
To disable the installation's workload path, set WORKLOAD_AUTH_ENABLED=false and redeploy web and all workers. Dashboard administrators can still inspect and disable identities.
Audit and Troubleshooting
Audited operations record the configured workload name snapshot, actorKind and stable workloadIdentityId; workflow ownership remains separate. Recent identity activity includes configuration changes and audited operations. Enterprise audit exports can filter by workload ID. Read/discovery requests are not a complete per-request access log.
| Symptom | Check |
|---|---|
| Installation setup required | Both processes have workload auth enabled and a valid five-field profile; redeploy after editing environment values |
| 401 / token rejected | Token is for the configured tenant/API, has v2 app-only claims, the required application role and a valid signature/expiry |
| 403 / identity or access denied | Exact application/service-principal binding, enabled state, correct organization, required local action, active workspace and exclusions |
| 409 / verification or save conflict | Refresh the identity revision; trust or configuration may have changed |
| Web accepts a request but queued execution is rejected | Worker trust/profile and build match web; the binding/revision/grant is still current before preparation |
| Verification succeeds but import/deploy/secret write fails | Workspace-read verification alone does not grant those actions; inspect operation grants and confirmation fields |
| New workspace inaccessible | Check the organization-wide actions and exclusions, or add the workspace to the identity's explicit grants |
Delivery Acceptance
Before replacing existing pipeline credentials, run the complete operation inventory with genuine Entra/ADO federation, separately authorized real Key Vault retrieval, denial after local revocation, new-workspace access and token acquisition after expiry. Restore an earlier definition, redeploy it and check observed output to establish rollback. Keep the exact installed image digests/build IDs and redacted ADO evidence.
Use separate source/target identities and service connections for environment access separation, and configure approvals in your release pipeline. KB CRUD, logical database/table configuration, paused OAuth connector configuration and workspace BYOK configuration use explicit independent grants. Workspace/infrastructure provisioning, standalone document ingestion/manual sync and new connector/driver implementations remain separate capabilities. Qualify configuration, replay/revision behavior, fallback and scope denials against the customer's actual identity arrangement before relying on these paths.