Agents

Cloud identities

A cloud identity lets a workflow step use a role in your AWS, Google Cloud or Azure account, with short-lived credentials and no long-lived keys. Your cloud account trusts your workspace, not a key. When a step that's allowed to use the identity runs, SpudSuite signs a token for that step that lasts five minutes, and your runner swaps it with the cloud for credentials. The credentials never pass through SpudSuite.

#Set one up

Open Connect › Cloud identities and choose New cloud identity:

• Provider: AWS, Google Cloud or Azure.
• Trust (AWS only): choose Web identity, which works with a runner anywhere. Ambient is for runners that already live in your AWS account. With ambient, the role trusts the runner machine's own AWS identity.
• Allow: the workflows and agents that may use the identity. Nothing can use it until a workflow is listed here.
• The provider's settings:
  • AWS role: the role ARN, and optionally the region, how long the credentials last, and policies that narrow them.
  • Google Cloud: the project number, the workload identity pool and provider, and optionally a service account to act as.
  • Azure: the tenant ID and the client ID of the app registration (or managed identity).

Then open the Setup tab. It has every step your cloud needs, with your workspace's own values already filled in. Switch between console steps, the cloud's CLI and Terraform, and use Copy on any value or script.

#What the setup guide has you do in AWS

1. Connect the account to your workspace, once per AWS account. Add an IAM identity provider:

   • Provider type: OpenID Connect.
   • Provider URL: your workspace's issuer, https://id.spudsuite.com/oidc/<your workspace id>. The guide shows the exact URL.
   • Audience: sts.amazonaws.com.

2. Let the identity assume the role. Paste the guide's trust policy into the role. The policy names your workspace's identity provider and requires two conditions:

   • aud must be sts.amazonaws.com.
   • sub must be workspace:<your workspace id>:cloud-identity:<name>, so only this identity can use the role. Choose Any identity in this workspace to trust every identity in the workspace instead.

   The policy also allows sts:TagSession and sts:SetSourceIdentity. Each session is tagged with the workspace, workflow, run, step and the person who started the run, and CloudTrail shows that person as the source identity.

3. Give the role only the permissions your workflows need.

4. Save, then choose Test. A runner gets credentials once, the way a step would, and then throws them away. If it doesn't work, Test shows what AWS said and what to check.

In Google Cloud the guide has you make a workload identity pool and provider, then give the identity access to a service account. In Azure it has you add a federated credential to an app registration.

#Use it in a workflow

Agent and script steps in an allowed workflow name the identity, and the runner gives that one step its credentials. They're for that step only, and they expire on their own:

• AWS: the usual AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY and AWS_SESSION_TOKEN.
• Google Cloud: CLOUDSDK_AUTH_ACCESS_TOKEN and GOOGLE_OAUTH_ACCESS_TOKEN.
• Azure: AZURE_ACCESS_TOKEN, with AZURE_CLIENT_ID and AZURE_TENANT_ID.

The Tokens tab lists every token SpudSuite signed for the identity: which run and step it was for, and which runner asked. The tokens themselves are never kept.