Skip to content

Commit cac0148

Browse files
waleedlatif1waleedlatif1
authored
feat(credentials): set up keyless credentials from the v2 API, CLI and Sim MCP (#9875)
Keyless (workload identity) credentials could only be set up in the web connect dialog. Platform teams scripting their cloud trust now get the same two steps as an API: 1. POST /api/v2/credentials/workload-identity/subjects (`sim credentials keyless-subject <providerId>`) issues a random, per-credential subject and a 24-hour proof bound to the caller, plus the keylessConfig to fill in and the provider's required fields. 2. The existing create (`sim credentials create … --credentials @keyless.json`) submits the completed config; Sim verifies the trust before saving. - The existing prepare use case now also admits personal API keys and OAuth tokens with api:write. Workspace keys and delegated callers stay refused, because the subject must belong to a person. - Every keyless refusal carries one stable `error.details.code` (WORKLOAD_IDENTITY_NOT_CONFIGURED, _PROOF_EXPIRED, _PROOF_INVALID, _SUBJECT_REQUIRED, _SUBJECT_IN_USE, _SUBJECT_UNVERIFIABLE) on a single refusal error, from create, reconnect and the subjects route alike. - The provider catalog advertises a `keyless` object (authType and required/optional config fields) only when the deployment can sign, and the CLI reads it instead of keeping its own provider table. Snowflake's keyless config is now accepted by the CLI. - Provider hints, OpenAPI, MCP tool descriptions, CLI help and the five credential docs pages describe the flow the same way. - AWS and Databricks keyless create and reconnect also refuse with WORKLOAD_IDENTITY_NOT_CONFIGURED when the deployment cannot sign, and their verification steps pass keyless refusals through unchanged. Each provider's refusal names a fallback credential type. - The Google Cloud keyless hint says it covers Cloud services (BigQuery, Vertex AI), not Google Workspace.
1 parent 9ab4e6f commit cac0148

54 files changed

Lines changed: 2579 additions & 585 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎apps/docs/content/docs/cli/credentials.mdx‎

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -87,6 +87,24 @@ sim credentials create <providerId> [options]
8787

8888
</CommandTable>
8989

90+
--credentials takes the provider's fields, or the keylessConfig from `sim credentials keyless-subject` (with the required fields filled in). Pass @path or @- to keep secrets out of shell history.
91+
92+
Keyless (workload identity) credentials take two steps.
93+
94+
Step 1: run `sim credentials keyless-subject <providerId> --output json` and configure your cloud to trust the printed issuer, audience, and subject. Its requiredConfigFields lists the values your provider's keylessConfig still needs.
95+
96+
Step 2: add those values to keylessConfig and pass it to `sim credentials create <providerId> --credentials @file`.
97+
98+
The proof expires after 24 hours and works only for the user who requested it, with the same providerId. If creation reports WORKLOAD_IDENTITY_PROOF_EXPIRED, WORKLOAD_IDENTITY_PROOF_INVALID, WORKLOAD_IDENTITY_SUBJECT_REQUIRED, WORKLOAD_IDENTITY_SUBJECT_IN_USE, run step 1 again, trust the new subject, and retry.
99+
100+
**Examples**
101+
102+
```bash
103+
sim credentials keyless-subject <providerId> --output json > subject.json
104+
jq '.keylessConfig + {"roleArn":"arn:aws:iam::123456789012:role/SimWorkflows"}' subject.json > keyless.json
105+
sim credentials create <providerId> --name "Keyless" --credentials @keyless.json
106+
```
107+
90108
API request and response schemas: [createServiceAccountCredential](/api-reference/credentials/createServiceAccountCredential).
91109

92110
### Create a short-lived link for connecting an OAuth provider
@@ -324,6 +342,44 @@ sim credentials delete <credentialId> [options]
324342

325343
API request and response schemas: [deleteCredential](/api-reference/credentials/deleteCredential).
326344

345+
## Other commands
346+
347+
### Issue the subject and proof for a new keyless (workload identity) credential
348+
349+
OAuth login or personal API key required.
350+
351+
```bash
352+
sim credentials keyless-subject <providerId>
353+
```
354+
355+
**Arguments**
356+
357+
<CommandTable>
358+
359+
| Argument | Required | Description |
360+
| --- | --- | --- |
361+
| `providerId` | Yes | Service-account provider for the keyless credential |
362+
363+
</CommandTable>
364+
365+
Keyless (workload identity) credentials take two steps.
366+
367+
Step 1: run `sim credentials keyless-subject <providerId> --output json` and configure your cloud to trust the printed issuer, audience, and subject. Its requiredConfigFields lists the values your provider's keylessConfig still needs.
368+
369+
Step 2: add those values to keylessConfig and pass it to `sim credentials create <providerId> --credentials @file`.
370+
371+
The proof expires after 24 hours and works only for the user who requested it, with the same providerId. If creation reports WORKLOAD_IDENTITY_PROOF_EXPIRED, WORKLOAD_IDENTITY_PROOF_INVALID, WORKLOAD_IDENTITY_SUBJECT_REQUIRED, WORKLOAD_IDENTITY_SUBJECT_IN_USE, run step 1 again, trust the new subject, and retry.
372+
373+
**Examples**
374+
375+
```bash
376+
sim credentials keyless-subject <providerId> --output json > subject.json
377+
jq '.keylessConfig + {"roleArn":"arn:aws:iam::123456789012:role/SimWorkflows"}' subject.json > keyless.json
378+
sim credentials create <providerId> --name "Keyless" --credentials @keyless.json
379+
```
380+
381+
API request and response schemas: [createCredentialWorkloadIdentitySubject](/api-reference/credentials/createCredentialWorkloadIdentitySubject).
382+
327383
## Related docs
328384

329385
- [Credentials](/platform/credentials)

‎apps/docs/content/docs/cli/reference.mdx‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -773,8 +773,62 @@ sim credentials create <providerId> [options]
773773

774774
</CommandTable>
775775

776+
--credentials takes the provider's fields, or the keylessConfig from `sim credentials keyless-subject` (with the required fields filled in). Pass @path or @- to keep secrets out of shell history.
777+
778+
Keyless (workload identity) credentials take two steps.
779+
780+
Step 1: run `sim credentials keyless-subject <providerId> --output json` and configure your cloud to trust the printed issuer, audience, and subject. Its requiredConfigFields lists the values your provider's keylessConfig still needs.
781+
782+
Step 2: add those values to keylessConfig and pass it to `sim credentials create <providerId> --credentials @file`.
783+
784+
The proof expires after 24 hours and works only for the user who requested it, with the same providerId. If creation reports WORKLOAD_IDENTITY_PROOF_EXPIRED, WORKLOAD_IDENTITY_PROOF_INVALID, WORKLOAD_IDENTITY_SUBJECT_REQUIRED, WORKLOAD_IDENTITY_SUBJECT_IN_USE, run step 1 again, trust the new subject, and retry.
785+
786+
**Examples**
787+
788+
```bash
789+
sim credentials keyless-subject <providerId> --output json > subject.json
790+
jq '.keylessConfig + {"roleArn":"arn:aws:iam::123456789012:role/SimWorkflows"}' subject.json > keyless.json
791+
sim credentials create <providerId> --name "Keyless" --credentials @keyless.json
792+
```
793+
776794
API request and response schemas: [createServiceAccountCredential](/api-reference/credentials/createServiceAccountCredential).
777795

796+
### sim credentials keyless-subject
797+
798+
Issue the subject and proof for a new keyless (workload identity) credential (OAuth login or personal API key required)
799+
800+
```bash
801+
sim credentials keyless-subject <providerId>
802+
```
803+
804+
**Arguments**
805+
806+
<CommandTable>
807+
808+
| Argument | Required | Description |
809+
| --- | --- | --- |
810+
| `providerId` | Yes | Service-account provider for the keyless credential |
811+
812+
</CommandTable>
813+
814+
Keyless (workload identity) credentials take two steps.
815+
816+
Step 1: run `sim credentials keyless-subject <providerId> --output json` and configure your cloud to trust the printed issuer, audience, and subject. Its requiredConfigFields lists the values your provider's keylessConfig still needs.
817+
818+
Step 2: add those values to keylessConfig and pass it to `sim credentials create <providerId> --credentials @file`.
819+
820+
The proof expires after 24 hours and works only for the user who requested it, with the same providerId. If creation reports WORKLOAD_IDENTITY_PROOF_EXPIRED, WORKLOAD_IDENTITY_PROOF_INVALID, WORKLOAD_IDENTITY_SUBJECT_REQUIRED, WORKLOAD_IDENTITY_SUBJECT_IN_USE, run step 1 again, trust the new subject, and retry.
821+
822+
**Examples**
823+
824+
```bash
825+
sim credentials keyless-subject <providerId> --output json > subject.json
826+
jq '.keylessConfig + {"roleArn":"arn:aws:iam::123456789012:role/SimWorkflows"}' subject.json > keyless.json
827+
sim credentials create <providerId> --name "Keyless" --credentials @keyless.json
828+
```
829+
830+
API request and response schemas: [createCredentialWorkloadIdentitySubject](/api-reference/credentials/createCredentialWorkloadIdentitySubject).
831+
778832
### sim credentials connect
779833

780834
Create a short-lived link for connecting an OAuth provider (OAuth login or personal API key required)

‎apps/docs/content/docs/integrations/aws-credentials.mdx‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -47,6 +47,10 @@ STS **Get Session Token** works only with an **Access keys** credential: AWS ref
4747
The subject is unique to the credential. Reconnecting a keyless credential keeps its subject by default, so the role's trust policy keeps working; choose **Issue a new subject** only if you also update the trust policy.
4848
</Callout>
4949

50+
### From the API or CLI [#keyless-api-cli]
51+
52+
Run `sim credentials keyless-subject aws-service-account`, trust the printed subject as above, then add `roleArn` (optionally `stsRegion` and `sessionDurationSeconds`) to its `keylessConfig` and pass it to `sim credentials create aws-service-account`. See [the CLI credentials reference](/cli/credentials) for the full two-step example; the proof expires after 24 hours and works only for the user who requested it.
53+
5054
## Use access keys
5155

5256
Create an IAM user (or use an existing one) with an access key, choose **Access keys** or **Access keys that assume an IAM role**, and enter the key pair. For an assumed role, add the role ARN and, if the role's trust policy requires one, the external ID. For AWS GovCloud or China keys, set the **STS region** (for example `us-gov-west-1`). Sim checks the keys with `sts:GetCallerIdentity` before saving.

‎apps/docs/content/docs/integrations/databricks-credentials.mdx‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -38,6 +38,10 @@ Every option resolves on Sim's servers at run time; tokens never appear in block
3838

3939
Reconnecting a keyless connection keeps its subject by default, so the federation policy keeps working.
4040

41+
### From the API or CLI [#keyless-api-cli]
42+
43+
Run `sim credentials keyless-subject databricks-service-account`, trust the printed subject as above, then add `host` and `clientId` to its `keylessConfig` and pass it to `sim credentials create databricks-service-account`. See [the CLI credentials reference](/cli/credentials) for the full two-step example; the proof expires after 24 hours and works only for the user who requested it.
44+
4145
## Self-hosted deployments
4246

4347
Keyless connections need `WORKLOAD_IDENTITY_SIGNING_KEY` set and an `https` issuer Databricks can reach over the public internet. See [AWS credentials](/integrations/aws-credentials#self-hosted-deployments) for the same settings and for rotating the signing key.

‎apps/docs/content/docs/integrations/google-service-account.mdx‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -231,6 +231,10 @@ Each keyless credential has its own subject; reconnecting keeps it by default so
231231

232232
Self-hosted deployments need `WORKLOAD_IDENTITY_SIGNING_KEY` set and an `https` issuer Google can reach over the public internet. See [AWS credentials](/integrations/aws-credentials#self-hosted-deployments).
233233

234+
### From the API or CLI [#keyless-api-cli]
235+
236+
Run `sim credentials keyless-subject google-service-account`, trust the printed subject as above, then add `projectNumber`, `poolId`, `providerId`, and `serviceAccountEmail` to its `keylessConfig` and pass it to `sim credentials create google-service-account`. See [the CLI credentials reference](/cli/credentials) for the full two-step example; the proof expires after 24 hours and works only for the user who requested it. As in the dialog, keyless works only for Google Cloud services such as BigQuery and Vertex AI, not Google Workspace blocks.
237+
234238
### Troubleshooting keyless access
235239

236240
- **"Google Cloud refused Sim's token for this workload identity provider":** the project number, pool ID, or provider ID doesn't match; the provider is disabled, has allowed audiences set, or uses a different issuer; or its attribute condition doesn't allow this credential's subject.

‎apps/docs/content/docs/integrations/microsoft-app-credentials.mdx‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -54,6 +54,10 @@ Every option resolves on Sim's servers at run time, and tokens never appear in b
5454

5555
An app can have up to 20 federated credentials. Each Sim credential has its own subject, and reconnecting keeps the subject by default so the federated credential keeps working. Keyless credentials are available for workspace credentials, not organization credentials.
5656

57+
### From the API or CLI [#keyless-api-cli]
58+
59+
Run `sim credentials keyless-subject microsoft-app-service-account`, trust the printed subject as above, then add `tenantId` and `clientId` (optionally `environmentUrl`) to its `keylessConfig` and pass it to `sim credentials create microsoft-app-service-account`. See [the CLI credentials reference](/cli/credentials) for the full two-step example; the proof expires after 24 hours and works only for the user who requested it.
60+
5761
## Use a client secret or certificate
5862

5963
- **Client secret:** under **Certificates & secrets** → **Client secrets** → **New client secret**, copy the secret's **Value** (not the Secret ID).

‎apps/docs/content/docs/integrations/snowflake-service-account.mdx‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -48,6 +48,10 @@ CREATE USER SIM_WORKFLOWS
4848

4949
Snowflake requires each issuer and subject pair to be unique in an account, and matches the subject exactly, so the service user trusts this connection and no other Sim credential. Reconnecting a keyless connection keeps its subject by default, so the service user keeps working; if you choose **Issue a new subject**, update the user with the new one before saving.
5050

51+
### From the API or CLI [#keyless-api-cli]
52+
53+
Run `sim credentials keyless-subject snowflake-service-account`, trust the printed subject as above, then add `host` to its `keylessConfig` and pass it to `sim credentials create snowflake-service-account`. See [the CLI credentials reference](/cli/credentials) for the full two-step example; the proof expires after 24 hours and works only for the user who requested it.
54+
5155
### Self-hosted deployments
5256

5357
Keyless connections need `WORKLOAD_IDENTITY_SIGNING_KEY` set and an `https` issuer Snowflake can reach over the public internet. See [AWS credentials](/integrations/aws-credentials#self-hosted-deployments) for the settings. Snowflake caches an issuer's signing keys for up to **60 minutes**, so when rotating the signing key, publish the new key (`WORKLOAD_IDENTITY_PREVIOUS_KEY`) at least 60 minutes before Sim starts signing with it. A shorter wait fails runs until Snowflake refreshes its cache.

0 commit comments

Comments
 (0)