Cloud Credentials

Terrateam provides flexible authentication and authorization options for Terraform operations, allowing you to securely manage credentials and control access to your cloud resources. In this guide, we’ll explore advanced workflows and configurations using Terrateam’s OIDC integration, static credentials, and custom scripts for generating cloud credentials.

OIDC (OpenID Connect)

Terrateam’s OIDC integration enables secure authentication against cloud providers using short-lived, dynamically generated credentials.

Benefits of OIDC over Static Credentials

• Uses short-lived credentials that are automatically issued and expire quickly, reducing the risk of leaks.
• Improves your security posture by eliminating long-lived credentials from your environment.
• Reduces the effort needed to manage and rotate static access keys.
• Lets you define specific access scopes per workflow to keep permissions tight.

Basic OIDC Configuration

To use OIDC with Terrateam, you need to configure the oidc step type in your configuration. A step type defines a specific action in your workflow, such as authentication, initialization, or execution of Terraform commands.

Storing Sensitive Values

All sensitive values should be stored as GitHub Secrets and referenced using the ${SECRET_NAME} syntax. This ensures credentials are encrypted and only accessible during workflow execution.

Workflows Example

workflows:
  - tag_query: "dir:aws"
    plan:
      - type: oidc  # Authentication step
        provider: aws
        role_arn: ${AWS_ROLE_ARN}
      - type: init  # Terraform initialization step
      - type: plan  # Terraform plan step
    apply:
      - type: oidc
        provider: aws
        role_arn: ${AWS_ROLE_ARN}
      - type: init
      - type: apply

Hooks Example

hooks:
  all:
    pre:
      - type: oidc
        provider: aws
        role_arn: ${AWS_ROLE_ARN}

In these examples, OIDC is used to authenticate against AWS using the specified role_arn.

Difference Between Hooks and Workflows

Hooks are commands that run before or after all plan and apply steps, while workflows define the specific steps and sequence for each plan and apply operation.

Advanced OIDC Workflows

Terrateam’s OIDC integration provides flexibility and customization options to suit your specific requirements. Here are some advanced OIDC workflows with examples:

Multiple OIDC Configurations

Define multiple OIDC configurations within a single workflow to use different roles or providers for different steps.

workflows:
  - tag_query: "dir:aws"
    plan:
      - type: oidc
        provider: aws
        role_arn: ${AWS_PLAN_ROLE_ARN}
      - type: init
      - type: plan
    apply:
      - type: oidc
        provider: aws
        role_arn: ${AWS_APPLY_ROLE_ARN}
      - type: init
      - type: apply

In this example, the plan steps use a different IAM role (AWS_PLAN_ROLE_ARN) compared to the apply steps (AWS_APPLY_ROLE_ARN), allowing for granular permission control.

OIDC for Multiple Cloud Providers

Configure OIDC for different cloud providers, such as AWS and GCP, within the same workflow.

workflows:
  - tag_query: "dir:multi-cloud"
    plan:
      - type: oidc
        provider: aws
        role_arn: ${AWS_ROLE_ARN}
      - type: oidc
        provider: gcp
        service_account: ${GCP_SERVICE_ACCOUNT}
        workload_identity_provider: ${GCP_WORKLOAD_IDENTITY_PROVIDER}
      - type: init
      - type: plan
    apply:
      - type: oidc
        provider: aws
        role_arn: ${AWS_ROLE_ARN}
      - type: oidc
        provider: gcp
        service_account: ${GCP_SERVICE_ACCOUNT}
        workload_identity_provider: ${GCP_WORKLOAD_IDENTITY_PROVIDER}
      - type: init
      - type: apply

This example demonstrates how to configure OIDC for both AWS and GCP within the same workflow, enabling multi-cloud deployments.

Conditional OIDC Configuration

Use Terrateam’s tag queries and conditional expressions to selectively apply OIDC configurations based on specific criteria.

workflows:
  - tag_query: "dir:aws/production"
    plan:
      - type: oidc
        provider: aws
        role_arn: ${AWS_PRODUCTION_ROLE_ARN}
      - type: init
      - type: plan
    apply:
      - type: oidc
        provider: aws
        role_arn: ${AWS_PRODUCTION_ROLE_ARN}
      - type: init
      - type: apply
  - tag_query: "dir:aws/staging"
    plan:
      - type: oidc
        provider: aws
        role_arn: ${AWS_STAGING_ROLE_ARN}
      - type: init
      - type: plan
    apply:
      - type: oidc
        provider: aws
        role_arn: ${AWS_STAGING_ROLE_ARN}
      - type: init
      - type: apply

In this example, different OIDC configurations are applied based on the dir tag, allowing for directory-specific roles and permissions.

Static Credentials

Security Consideration

While static credentials are supported, we recommend using OIDC when possible for better security. Static credentials are long-lived and require manual rotation, increasing security risks.

Configuring Static Credentials

1. Create GitHub Secrets Store your credentials securely as GitHub Secrets:

   # Example for AWS credentials
   gh secret set AWS_ACCESS_KEY_ID --body "your-access-key"
   gh secret set AWS_SECRET_ACCESS_KEY --body "your-secret-key"

2. Apply Least Privilege Ensure the static credentials have minimal required permissions:

   # Example AWS IAM policy
   {
     "Version": "2012-10-17",
     "Statement": [
       {
         "Effect": "Allow",
         "Action": [
           "s3:ListBucket",
           "s3:GetObject"
         ],
         "Resource": [
           "arn:aws:s3:::my-terraform-state",
           "arn:aws:s3:::my-terraform-state/*"
         ]
       }
     ]
   }

Custom Credential Scripts

Tip

When using custom credential scripts, ensure they:

• Generate credentials with minimal required permissions
• Expire credentials after the shortest practical duration
• Log credential usage for audit purposes

Configuring Custom Credential Scripts

1. Create your script

   generate-aws-credentials.sh

   #!/bin/bash
   # Example script that generates temporary credentials
   environment=$1    # e.g., "production" or "staging"
   access_level=$2   # e.g., "read-only" or "read-write"
   
   # Generate credentials with appropriate permissions
   aws sts assume-role \
     --role-arn "arn:aws:iam::${AWS_ACCOUNT_ID}:role/${environment}-${access_level}" \
     --role-session-name "terrateam-${environment}"

2. Configure the Terrateam workflow

   workflows:
     - tag_query: "dir:aws/production"
       plan:
         - type: env
           method: source
           cmd: ["./generate-aws-credentials.sh", "production", "read-only"]
         - type: init
         - type: plan

3. Set required permissions Make sure your script and the credentials it generates follow the principle of least privilege:

   • The script should only be allowed to assume specific roles.
   • The assumed credentials should have only the permissions necessary for their task.
   • Use separate permission sets for plan and apply operations.

Best Practices

When implementing advanced authentication and authorization workflows with Terrateam, consider the following best practices:

• Principle of Least Privilege: Grant the minimum set of permissions required for each workflow or step, ensuring that credentials have access to only the necessary resources.
• Secure Credential Storage: Store sensitive credentials, such as static access keys or OIDC role ARNs, securely using GitHub Secrets or a secrets management system.
• Regular Credential Rotation: Implement a process to regularly rotate credentials, whether static or dynamically generated, to minimize the risk of unauthorized access.