Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
56 changes: 56 additions & 0 deletions apps/docs/content/docs/cli/credentials.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -87,6 +87,24 @@ sim credentials create <providerId> [options]

</CommandTable>

--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.

Keyless (workload identity) credentials take two steps.

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.

Step 2: add those values to keylessConfig and pass it to `sim credentials create <providerId> --credentials @file`.

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.

**Examples**

```bash
sim credentials keyless-subject <providerId> --output json > subject.json
jq '.keylessConfig + {"roleArn":"arn:aws:iam::123456789012:role/SimWorkflows"}' subject.json > keyless.json
sim credentials create <providerId> --name "Keyless" --credentials @keyless.json
```

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

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

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

## Other commands

### Issue the subject and proof for a new keyless (workload identity) credential

OAuth login or personal API key required.

```bash
sim credentials keyless-subject <providerId>
```

**Arguments**

<CommandTable>

| Argument | Required | Description |
| --- | --- | --- |
| `providerId` | Yes | Service-account provider for the keyless credential |

</CommandTable>

Keyless (workload identity) credentials take two steps.

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.

Step 2: add those values to keylessConfig and pass it to `sim credentials create <providerId> --credentials @file`.

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.

**Examples**

```bash
sim credentials keyless-subject <providerId> --output json > subject.json
jq '.keylessConfig + {"roleArn":"arn:aws:iam::123456789012:role/SimWorkflows"}' subject.json > keyless.json
sim credentials create <providerId> --name "Keyless" --credentials @keyless.json
```

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

## Related docs

- [Credentials](/platform/credentials)
54 changes: 54 additions & 0 deletions apps/docs/content/docs/cli/reference.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -773,8 +773,62 @@ sim credentials create <providerId> [options]

</CommandTable>

--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.

Keyless (workload identity) credentials take two steps.

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.

Step 2: add those values to keylessConfig and pass it to `sim credentials create <providerId> --credentials @file`.

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.

**Examples**

```bash
sim credentials keyless-subject <providerId> --output json > subject.json
jq '.keylessConfig + {"roleArn":"arn:aws:iam::123456789012:role/SimWorkflows"}' subject.json > keyless.json
sim credentials create <providerId> --name "Keyless" --credentials @keyless.json
```

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

### sim credentials keyless-subject

Issue the subject and proof for a new keyless (workload identity) credential (OAuth login or personal API key required)

```bash
sim credentials keyless-subject <providerId>
```

**Arguments**

<CommandTable>

| Argument | Required | Description |
| --- | --- | --- |
| `providerId` | Yes | Service-account provider for the keyless credential |

</CommandTable>

Keyless (workload identity) credentials take two steps.

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.

Step 2: add those values to keylessConfig and pass it to `sim credentials create <providerId> --credentials @file`.

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.

**Examples**

```bash
sim credentials keyless-subject <providerId> --output json > subject.json
jq '.keylessConfig + {"roleArn":"arn:aws:iam::123456789012:role/SimWorkflows"}' subject.json > keyless.json
sim credentials create <providerId> --name "Keyless" --credentials @keyless.json
```

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

### sim credentials connect

Create a short-lived link for connecting an OAuth provider (OAuth login or personal API key required)
Expand Down
4 changes: 4 additions & 0 deletions apps/docs/content/docs/integrations/aws-credentials.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -47,6 +47,10 @@ STS **Get Session Token** works only with an **Access keys** credential: AWS ref
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.
</Callout>

### From the API or CLI [#keyless-api-cli]

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.

## Use access keys

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.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -38,6 +38,10 @@ Every option resolves on Sim's servers at run time; tokens never appear in block

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

### From the API or CLI [#keyless-api-cli]

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.

## Self-hosted deployments

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.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -231,6 +231,10 @@ Each keyless credential has its own subject; reconnecting keeps it by default so

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).

### From the API or CLI [#keyless-api-cli]

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.

### Troubleshooting keyless access

- **"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.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -54,6 +54,10 @@ Every option resolves on Sim's servers at run time, and tokens never appear in b

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.

### From the API or CLI [#keyless-api-cli]

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.

## Use a client secret or certificate

- **Client secret:** under **Certificates & secrets** → **Client secrets** → **New client secret**, copy the secret's **Value** (not the Secret ID).
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -48,6 +48,10 @@ CREATE USER SIM_WORKFLOWS

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.

### From the API or CLI [#keyless-api-cli]

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.

### Self-hosted deployments

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.
Expand Down
Loading
Loading