Authentication

Atmos Pro integrates GitHub's OpenID Connect (OIDC) authentication to securely obtain short-lived access tokens for interacting with the Atmos Pro API. This mechanism enhances security by eliminating the need for long-lived API tokens in CI/CD workflows.

How OIDC Authentication Works

The authentication process uses OIDC token exchange between GitHub and Atmos Pro, which is handled automatically by the Atmos CLI:

1. Token Retrieval: During a GitHub Actions workflow, Atmos Pro attempts to retrieve an OIDC token issued by GitHub. This token is a JSON Web Token (JWT) that includes claims about the GitHub Actions workflow run.

2. Token Exchange: Atmos Pro sends the GitHub-issued OIDC token to the Atmos Pro API endpoint. The API validates the token's authenticity and exchanges it for an Atmos Pro-specific access token. This token grants the workflow permissions to interact with Atmos Pro services.

This process ensures that:

• Only authorized GitHub repositories can access your Atmos Pro workspace
• No long-lived credentials need to be stored in your repository
• Each workflow run gets a fresh, short-lived token
• The authentication is fully automated and secure
• Token management is handled transparently by the Atmos CLI

Configuration

To use OIDC authentication, you'll need to:

1. Update Atmos to greater than version 1.180.0
2. Pass the Atmos Pro Workspace ID by environment variable, see Getting Your Workspace ID
3. Configure GitHub repository permissions, see Repository Permissions

Here's how to configure your workflow to use OIDC:

jobs:
  affected:
    name: Determine Affected Stacks
    runs-on:
      - "ubuntu-latest"
    permissions:
      id-token: write # Required for OIDC
      contents: read # Required for checking out code
    steps:
      - name: Determine Affected Stacks
        id: affected
        uses: cloudposse/github-action-atmos-affected-stacks@v6
        env:
          ATMOS_PRO_WORKSPACE_ID: ${{ vars.ATMOS_PRO_WORKSPACE_ID }} # Your workspace ID from Atmos Pro
        with:
          atmos-version: ${{ vars.ATMOS_VERSION }} # >= 1.180.0
          atmos-config-path: ${{ vars.ATMOS_CONFIG_PATH }}
          atmos-pro-upload: true
          head-ref: ${{ github.event.pull_request.head.sha }}