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 allows you to authenticate and authorize Terraform operations against your cloud provider using short-lived, dynamically generated credentials. This enhances security by eliminating the need to manage long-lived static credentials.

Basic OIDC Configuration

To use OIDC with Terrateam, you need to configure the oidc step type in workflows or hooks.

Workflows Example

workflows:
  - tag_query: "dir:aws"
    plan:
      - type: oidc
        provider: aws
        role_arn: ${AWS_ROLE_ARN}
      - type: init
      - type: plan
    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.

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

In addition to OIDC, Terrateam supports using static credentials for authenticating against cloud providers. Static credentials are long-lived access keys or tokens that are securely stored and referenced in your Terrateam configuration.

Configuring Static Credentials

To use static credentials with Terrateam, you can set the relevant environment variables or configure them as GitHub Secrets. Here’s an example of using static credentials for AWS:

hooks:
  all:
    pre:
      - type: env
        name: AWS_ACCESS_KEY_ID_ACCOUNT_FOOBAR
        cmd: ["echo", "${AWS_ACCESS_KEY_ID}"]
      - type: env
        name: AWS_SECRET_ACCESS_KEY_ACCOUNT_FOOBAR
        cmd: ["echo", "${AWS_SECRET_ACCESS_KEY}"]

In this example, the AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY environment variables are set using the env hook type. The values are retrieved from GitHub Secrets.

Custom Credential Scripts

Terrateam provides the flexibility to use custom scripts for generating cloud credentials dynamically. This allows you to integrate with your organization’s existing credential management systems or implement custom authentication flows.

Configuring Custom Credential Scripts

To use a custom credential script with Terrateam, you can configure it as a env step in your workflow. Here’s an example:

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

In this example, the generate-aws-credentials.sh script is executed before the init, plan, and apply steps. The script is responsible for generating the necessary AWS credentials and exporting them as environment variables.

Conditional Credential Generation

Use Terrateam’s tag queries and conditional expressions to selectively execute custom credential scripts based on specific criteria.

workflows:
  - tag_query: "dir:aws/production"
    plan:
      - type: env
        method: source
        cmd: ["${TERRATEAM_ROOT}/scripts/environment.sh", "production", "read-only"]
      - type: init
      - type: plan
    apply:
      - type: env
        method: source
        cmd: ["${TERRATEAM_ROOT}/scripts/environment.sh", "production", "read-write"]
      - type: init
      - type: apply
  - tag_query: "dir:aws/staging"
    plan:
      - type: env
        method: source
        cmd: ["${TERRATEAM_ROOT}/scripts/environment.sh", "staging", "read-only"]
      - type: init
      - type: plan
    apply:
      - type: env
        method: source
        cmd: ["${TERRATEAM_ROOT}/scripts/environment.sh", "staging", "read-write"]
      - type: init
      - type: apply

In this example, the environment.sh script is passwd specific arguments based on the workflow specified by the dir tag. This allows for directory-specific credential generation. The script is responsible for generating the necessary AWS credentials and exporting them as environment variables.

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.