# Sign in as Stagd

> Set up Azure, AWS or Google Cloud to trust Stagd for your workspace, so an integration needs no stored key.

Instead of making a key and pasting it into Stagd, you can tell your cloud to trust Stagd for your workspace. Stagd then stores no secret of yours, nothing expires, and removing the trust cuts Stagd off at once. [Signing in as Stagd](https://stagd.dev/docs/concepts/sign-in-as-stagd.md) explains how it works.

For each cloud below, you set up a trust for Stagd's issuer and your workspace's subject, then connect the integration in Stagd with Stagd as the way to sign in.

## Your issuer and subject

| | Where | Example |
|---|---|---|
| Issuer | Stagd's address | `https://app.stagd.dev` |
| Subject | `org:` and your workspace's id | `org:019a5c1e-…` |

Settings → General shows your workspace's id, with Copy: your subject is `org:` and that id. The connect dialog shows the whole subject, once you choose to sign in as Stagd. The subject uses the workspace's id, not its slug, and it's the same for every integration in the workspace.

In the examples below, replace `org:<workspace id>` with your subject.

## Azure

For Azure Blob Storage. Azure trusts Stagd through a federated credential on an app registration (or on a user-assigned managed identity), and that app reads the container.

### With the Azure CLI

Sign in to the tenant the storage account is in (`az login`), then make the app and its service principal:

```sh
az ad app create --display-name stagd-seeds --query appId --output tsv
az ad sp create --id <client id>
```

The first command prints the app's **client id**. Give the app a federated credential that trusts Stagd for your workspace:

```sh
az ad app federated-credential create --id <client id> --parameters '{
  "name": "stagd",
  "issuer": "https://app.stagd.dev",
  "subject": "org:<workspace id>",
  "audiences": ["api://AzureADTokenExchange"]
}'
```

Let it read the container, and nothing else:

```sh
az role assignment create --assignee <client id> --role "Storage Blob Data Reader" \
  --scope /subscriptions/<subscription>/resourceGroups/<group>/providers/Microsoft.Storage/storageAccounts/<account>/blobServices/default/containers/<container>
```

### In the Azure portal

1. **Microsoft Entra ID → App registrations → New registration.** Name it `stagd-seeds`, and leave the rest as it is.
2. In the app, **Certificates & secrets → Federated credentials → Add credential**. Choose **Other issuer**, then fill in:
   - Issuer: `https://app.stagd.dev`
   - Type: Explicit subject identifier
   - Value: `org:<workspace id>`
   - Audience: `api://AzureADTokenExchange`
   - Name: `stagd`
3. Open the container: **storage account → Containers → the container → Access control (IAM) → Add role assignment**. Choose **Storage Blob Data Reader**, then the `stagd-seeds` app.

The app's **Overview** shows its client id (Application (client) ID) and tenant id (Directory (tenant) ID).

### In Stagd

Settings → Integrations → Azure Blob Storage, then:

- **Storage account** and **Container:** as usual.
- **Sign in with:** Stagd.
- **Tenant id** and **Client id:** from above.

A role assignment can take a few minutes to apply. If Stagd says it can't read the container, try again shortly.

## AWS

For Amazon S3. AWS trusts Stagd through an OIDC identity provider in your account and a role that trusts it. Stagd assumes the role for an hour at a time.

### With the AWS CLI

Add Stagd as an identity provider, once per AWS account:

```sh
aws iam create-open-id-connect-provider --url https://app.stagd.dev --client-id-list sts.amazonaws.com
```

Write the role's trust policy to `trust.json`, with your account id and subject:

```json
{
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Allow",
    "Principal": { "Federated": "arn:aws:iam::<account id>:oidc-provider/app.stagd.dev" },
    "Action": "sts:AssumeRoleWithWebIdentity",
    "Condition": { "StringEquals": {
      "app.stagd.dev:aud": "sts.amazonaws.com",
      "app.stagd.dev:sub": "org:<workspace id>"
    } }
  }]
}
```

Make the role, and let it read the bucket and nothing else:

```sh
aws iam create-role --role-name stagd-seeds --assume-role-policy-document file://trust.json --query Role.Arn --output text
aws iam put-role-policy --role-name stagd-seeds --policy-name read-seeds --policy-document '{
  "Version": "2012-10-17",
  "Statement": [
    { "Effect": "Allow", "Action": "s3:ListBucket", "Resource": "arn:aws:s3:::<bucket>" },
    { "Effect": "Allow", "Action": "s3:GetObject", "Resource": "arn:aws:s3:::<bucket>/*" }
  ]
}'
```

The first command prints the **role ARN**.

### In the AWS console

1. **IAM → Identity providers → Add provider.** Choose OpenID Connect, with provider URL `https://app.stagd.dev` and audience `sts.amazonaws.com`.
2. **IAM → Roles → Create role.** Choose **Web identity**, the provider `app.stagd.dev` and the audience `sts.amazonaws.com`. Add a condition: `app.stagd.dev:sub` **StringEquals** `org:<workspace id>`.
3. Give the role a policy with `s3:ListBucket` on the bucket and `s3:GetObject` on its objects, as above. Name it `stagd-seeds`.

Leave out the condition on the subject, and every Stagd workspace could use the role. Keep it.

### In Stagd

Settings → Integrations → S3 and compatible, then:

- **Bucket** and **Region:** the bucket's, for example `eu-north-1`.
- **Endpoint:** empty. Only Amazon S3 takes a role.
- **Sign in with:** Stagd (an IAM role).
- **Role ARN:** from above.

## Google Cloud

For Google Cloud Storage. Google trusts Stagd through a workload identity pool, and your workspace's principal reads the bucket. You need no service account.

### With gcloud

Make a pool, and a provider in it that trusts Stagd for your workspace:

```sh
gcloud iam workload-identity-pools create stagd --location=global --display-name=Stagd

gcloud iam workload-identity-pools providers create-oidc stagd \
  --location=global --workload-identity-pool=stagd \
  --issuer-uri=https://app.stagd.dev \
  --attribute-mapping=google.subject=assertion.sub \
  --attribute-condition="assertion.sub == 'org:<workspace id>'"
```

Let your workspace's principal read the bucket, using the project's number (not its id):

```sh
gcloud projects describe <project> --format='value(projectNumber)'

gcloud storage buckets add-iam-policy-binding gs://<bucket> --role=roles/storage.objectViewer \
  --member=principal://iam.googleapis.com/projects/<project number>/locations/global/workloadIdentityPools/stagd/subject/org:<workspace id>
```

### In the Google Cloud console

1. **IAM & Admin → Workload Identity Federation → Create pool.** Name it `stagd`.
2. **Add a provider:** OpenID Connect (OIDC), named `stagd`, with issuer URL `https://app.stagd.dev` and the default audience.
3. **Attribute mapping:** `google.subject` = `assertion.sub`. **Attribute condition:** `assertion.sub == 'org:<workspace id>'`.
4. On the bucket, **Permissions → Grant access.** Give the principal above (`principal://…/subject/org:<workspace id>`) the role **Storage Object Viewer**.

### In Stagd

Settings → Integrations → Google Cloud Storage, then give the **bucket**, the **project number**, the **pool** and the **provider** (both `stagd` above).

## Check it

Stagd checks each integration when you connect it, and again with **Test** on the Integrations page or `stagd integrations test <name>`. A failure says what your cloud answered and what it should trust.

| What it says | What to fix |
|---|---|
| Azure: `AADSTS70021`, no matching federated identity record | The federated credential's issuer, subject or audience differs from the ones above. They must match exactly. |
| Azure: can't read the container | The app has no Storage Blob Data Reader on the container yet, or the role assignment hasn't applied: wait a few minutes. |
| AWS: `InvalidIdentityToken`, no OpenIDConnect provider found | The identity provider for `https://app.stagd.dev` isn't in the account the role is in. |
| AWS: `AccessDenied` on AssumeRoleWithWebIdentity | The role's trust policy doesn't allow the provider, audience or subject. |
| AWS: the role can't list or read the bucket | The role's policy lacks `s3:ListBucket` on the bucket or `s3:GetObject` on its objects. |
| Google: rejected by the attribute condition | The provider's condition names another subject. |
| Google: can't list or read the bucket | The principal has no Storage Object Viewer on the bucket. |

## Revoke it

Remove the trust, and Stagd can't reach your storage from that moment on:

- **Azure:** delete the federated credential, or the app.
- **AWS:** delete the role, or remove the subject from its trust policy.
- **Google Cloud:** delete or disable the provider.

Credentials Stagd already holds last at most an hour.
