OIDC Tokens

You can use OIDC to authenticate Mint with third-party services. In general, you should use OIDC when it's available as it is more secure than generating access tokens which could be lost or stolen.

To use OIDC, you will need to configure the token in the Mint Vault UI. After setting the name and audience in the UI you will be able to reference the token in workflows like this:

${{ vaults.your_vault.oidc.your_token_name }}

If you're using OIDC for deployment, you'll most likely want to configure the OIDC token in a locked vault. For more details, see the documentation on vaults.

OIDC with AWS

When configuring the token in the Mint Vault UI, it's customary to name the token aws and set the audience to sts.amazonaws.com. You can then reference the token in your Mint run with:

${{ vaults.your_vault.oidc.aws }}

After configuring AWS to accept the token, you can use the aws/assume-role leaf and pass the token in via the oidc-token parameter. See the documentation for the aws/assume-role leaf.

OIDC Provider

See the AWS documentation on Creating OpenID Connect (OIDC) identity providers.

Set the provider URL to https://cloud.rwx.com/mint

Set the audience to the value that you configured in the Mint Vault UI, which is customarily sts.amazonaws.com

OIDC Role

Follow the AWS documentation on creating a role for OpenID Connect Federation.

You'll want to add a condition based on the aud and sub claims of the OIDC token.

You can find the vault that you should set for sub in the Vaults UI for the token that you configured.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Federated": "arn:aws:iam::012345678910:oidc-provider/cloud.rwx.com/mint"
      },
      "Action": "sts:AssumeRoleWithWebIdentity",
      "Condition": {
        "StringEquals": {
          "cloud.rwx.com/mint:aud": "sts.amazonaws.com",
          "cloud.rwx.com/mint:sub": "mint:your-org-uuid:your_vault_name"
        }
      }
    }
  ]
}

OIDC with Google Cloud

When configuring the token in the Mint Vault UI, it's customary to name the token gcp. You can then reference the token in your Mint run with:

${{ vaults.your_vault.oidc.gcp }}

After configuring Google Cloud to accept the token, you can use the google-cloud/auth-oidc leaf and pass the token in via the oidc-token parameter. See the documentation for the google-cloud/auth-oidc leaf.

The Mint OIDC token subject takes the form mint:{organization uuid}:{vault name} and is provided by Mint Vaults for the token that you configured. Use this value for <SUBJECT_ATTRIBUTE_VALUE> below, and replace <PROJECT_ID> with your appropriate Google Cloud project ID.

The vault name is included in the token subject. If you use multiple vaults, perhaps one for development resources and another for production resources, create multiple Workload Identity Providers.

OIDC Provider

Configure a workload provider and pool by following Google's Workload Identity Federation documentation.

When prompted for the new workload provider and pool settings, use the following values:

  • Issuer (URL): https://cloud.rwx.com/mint
  • Map the google.subject attribute to the assertion.sub claim
  • Add an attribute condition: google.subject == '<SUBJECT_ATTRIBUTE_VALUE>'

When using the gcloud CLI, a Workload Identity Pool can be created with:

gcloud iam workload-identity-pools create "mint-pool" \
  --project="<PROJECT_ID>" \
  --location="global" \
  --display-name="Mint Pool"

Get the full ID of the Workload Identity Pool with:

gcloud iam workload-identity-pools describe "mint-pool" \
  --project="<PROJECT_ID>" \
  --location="global" \
  --format="value(name)"

The Workload Identity Pool ID is in the format:

projects/123456789/locations/global/workloadIdentityPools/mint-pool

Replace <WORKLOAD_IDENTITY_POOL_ID> below with this value.

Create a Workload Identity Provider in the pool:

gcloud iam workload-identity-pools providers create-oidc "mint" \
  --project="<PROJECT_ID>" \
  --location="global" \
  --workload-identity-pool="mint-pool" \
  --display-name="Mint OIDC Provider" \
  --attribute-mapping="google.subject=assertion.sub" \
  --attribute-condition="google.subject == '<SUBJECT_ATTRIBUTE_VALUE>'" \
  --issuer-uri="https://cloud.rwx.com/mint"

Get the full Workload Identity Provider ID:

gcloud iam workload-identity-pools providers describe "mint" \
  --project="<PROJECT_ID>" \
  --location="global" \
  --workload-identity-pool="mint-pool" \
  --format="value(name)"

The Workload Identity Provider ID is in the format:

projects/123456789/locations/global/workloadIdentityPools/mint-pool/providers/mint

Use this value for the workload-identity-provider in the google-cloud/auth-oidc leaf.

The Workload Identity Provider ID can be used to generate the default audience when setting up the OIDC token in your Mint vault by prefixing it with //iam.googleapis.com. It can be found using the gcloud CLI:

echo "//iam.googleapis.com/$(gcloud iam workload-identity-pools providers describe 'mint' \
  --project='<PROJECT_ID>' \
  --location='global' \
  --workload-identity-pool='mint-pool' \
  --format='value(name)')"

//iam.googleapis.com/<WORKLOAD_IDENTITY_POOL_ID>/providers/mint

If you've configured your provider to use a different audience, provide it to the google-cloud/auth-oidc leaf and as the audience for the Mint Vault OIDC token.

If not using a Google Cloud Service Account, you may add permissions directly to the provider. For example, access is provided to the secret my-secret here:

gcloud secrets add-iam-policy-binding "my-secret" \
  --project="<PROJECT_ID>" \
  --role="roles/secretmanager.secretAccessor" \
  --member="principalSet://iam.googleapis.com/<WORKLOAD_IDENTITY_POOL_ID>/subject/<SUBJECT_ATTRIBUTE_VALUE>"

Authenticating as a Service Account (optional)

When authenticating as a Google Cloud Service Account, access must be granted to allow the Mint OIDC provider to impersonate the account:

gcloud iam service-accounts add-iam-policy-binding "my-service-account@<PROJECT_ID>.iam.gserviceaccount.com" \
  --project="<PROJECT_ID>" \
  --role="roles/iam.workloadIdentityUser" \
  --member="principal://iam.googleapis.com/<WORKLOAD_IDENTITY_POOL>/subject/<SUBJECT_ATTRIBUTE_VALUE>"

Use the service account email address ID value for the service-account in the google-cloud/auth-oidc leaf.

Claims

claimnamedescription
ississuerWill always be https://cloud.rwx.com/mint
subsubjectIdentifies the vault, in the format of mint:{organization uuid}:{vault name}
audaudienceThe audience configured for the token in the Vault
expexpiration timeThe time that the token expires as an integer
iatissued timeThe time that the token was issued as an integer
run_idrun idThe ID of the Mint run that generated the token
run_urlrun urlThe URL for the Mint run that generated the token
task_idtask idThe ID of the Mint task that generated the token
task_urltask urlthe URL for the Mint task that generated the token