# Identity Federation with RWX

Namespace provides seamless integration with [RWX](https://www.rwx.com/), allowing your RWX workflows to securely access Namespace resources such as builds, artifacts, and compute instances without managing long-lived credentials.

Using OpenID Connect (OIDC) federation, RWX can obtain short-lived access tokens to interact with your Namespace workspace. This enables powerful use cases like triggering remote builds, downloading artifacts, or accessing Bazel caches directly from your RWX pipelines.

## How it Works

RWX issues OIDC tokens that identify specific vaults within your organization. Namespace verifies these tokens and grants access to workspace resources based on the configured trust relationships.

* **Issuer**: `https://cloud.rwx.com/mint`
* **Subject Format**: `org:{org-slug}:vault:{vault-name}`

> [!NOTE]
>
> Trust relationships allow you to specify which RWX vaults can access your workspace. You can grant access to specific vaults or use wildcards to allow all vaults in your organization.

## Setup

### 1. Configure Trust Relationship

Use the Namespace CLI to establish a trust relationship with your RWX organization:

**For a specific vault:**

```bash theme={null}
nsc auth trust-relationships add \
  --issuer "https://cloud.rwx.com/mint" \
  --subject-match "org:my-org:vault:deploy-vault"
```

**For all vaults in your organization:**

```bash theme={null}
nsc auth trust-relationships add \
  --issuer "https://cloud.rwx.com/mint" \
  --subject-match "org:my-org:vault:*"
```

### 2. Verify Trust Relationship

List your configured trust relationships to confirm the setup:

```bash theme={null}
nsc auth trust-relationships list
```

You should see your RWX trust relationship with the appropriate subject pattern.

## Usage Examples

Once the trust relationship is configured, your RWX workflows can access Namespace resources using the federated identity.

### Triggering Remote Builds

```yaml theme={null}
# .rwx/main.yaml
tasks:
  - key: namespace-cli
    call: namespace/install-cli 1.0.0

- key: namespace-login
    call: namespace/login-hook 1.0.0
    with:
      workspace-id: my-namespace-workspace-id

- key: build-image
    use: [namespace-cli, namespace-login]
    run: nsc build --name my-app .
    env:
      NAMESPACE_OIDC_TOKEN:
        value: ${{ vaults.deploy-vault.oidc.namespace }}
        cache-key: excluded
```

### Downloading Artifacts

```yaml theme={null}
# .rwx/main.yaml
tasks:
  - key: namespace-cli
    call: namespace/install-cli 1.0.0

- key: namespace-login
    call: namespace/login-hook 1.0.0
    with:
      workspace-id: my-namespace-workspace-id

- key: download-artifacts
    use: [namespace-cli, namespace-login]
    run: |
      nsc artifact download \
        --name "my-app-binary" \
        --destination ./artifacts/
    env:
      NAMESPACE_OIDC_TOKEN:
        value: ${{ vaults.deploy-vault.oidc.namespace }}
        cache-key: excluded
```

### Accessing Bazel Cache

```yaml theme={null}
# .rwx/main.yaml
tasks:
  - key: namespace-cli
    call: namespace/install-cli 1.0.0

- key: namespace-login
    call: namespace/login-hook 1.0.0
    with:
      workspace-id: my-namespace-workspace-id

- key: build-with-cache
    use: [namespace-cli, namespace-login]
    run: |
      # Configure Bazel to use Namespace remote cache
      nsc bazel setup --remote=false
      bazel build //...
    env:
      NAMESPACE_OIDC_TOKEN:
        value: ${{ vaults.deploy-vault.oidc.namespace }}
        cache-key: excluded
```

## Security Considerations

* **Least Privilege**: Configure trust relationships to grant access only to the specific vaults that need it
* **Subject Patterns**: Use specific vault names rather than wildcards when possible
* **Audit Logging**: All access through federated identity is logged in Namespace audit logs

## Common Use Cases

* **CI/CD Pipelines**: Trigger Namespace builds as part of your RWX workflows
* **Artifact Management**: Upload build outputs to Namespace or download dependencies
* **Cache Sharing**: Leverage Namespace's remote caching for Bazel, Go modules, and more
* **Preview Deployments**: Create and manage preview environments from RWX

## Related Topics

* [Trust Relationships CLI Reference](/content/docs/reference/cli/auth-trust-relationships.md) - Detailed CLI documentation
* [Workspace Access Controls](/content/docs/workspaces/access.md) - Overview of authentication and access control
* [OpenID Connect Federation](/content/docs/federation/openid.md) - General OIDC federation concepts
* [Security](/content/docs/workspaces/security.md) - Security best practices and audit logging.
