🌐 Securely Access AWS Using OIDC Role in GitLab CI/CD Pipelines

By Solai Rajan

When working with cloud infrastructure as code, ensuring secure and temporary credentials for CI/CD pipelines is crucial. AWS supports OpenID Connect (OIDC) federation, which lets external identity providers like GitLab issue tokens your AWS account can trust — so no more hardcoded AWS keys in your pipelines!

In this guide, we’ll walk through how to authenticate GitLab Runner with AWS using an OIDC role, and perform operations securely within your pipeline.

📝 What We’ll Do

• Set up an OIDC provider in AWS
• Create an IAM role with trust policy for GitLab
• Configure your GitLab pipeline to authenticate using the OIDC token
• Assume the role and run AWS CLI/Terraform commands inside the pipeline

📌 Prerequisites
AWS account with admin privileges
GitLab project
A working GitLab Runner (GitLab SaaS runners also support this)

📊 Step 1: Create an OIDC Identity Provider in AWS

• Go to IAM → Identity Providers → Add Provider
• Provider URL: https://gitlab.com
• Audience: https://gitlab.com

📊 Step 2: Create IAM Role with Trust Policy

• Go to IAM →Roles →Create role
• Select Web identity in the trusted entity
• Attach policy in the Add permissions tab

Optional: Add a condition in the trust policy to restrict access by branch, project, or job if needed — for improved security.

📊 Step 3: Create AWS_ROLE_ARN variable in GitLab

• Go to Settings → CI/CD → Expand ‘Variables’
• Add variable name in the key
• Add OIDC Role arn in the value (Created in the step 2)

Note: Ensure the Protected setting for the variable is configured appropriately. If your pipelines run on unprotected branches, disable Protect for this variable — since protected variables are accessible only in protected branches.

📊 Step 4: Configure Your .gitlab-ci.yml

• Here I created template like format so that we can reuse it

aws_oidc.yml

.assume_aws_role:
  stage: test
  image: 
    # name: amazon/aws-cli:latest
    name: hashicorp/terraform:latest
    entrypoint: [""]
  id_tokens:
    GITLAB_OIDC_TOKEN:
      # GitLab's OIDC provider URL (matches your trust policy)
      aud: https://gitlab.com
  
  before_script:
    - apk update && apk add aws-cli
    
    # Verify installations
    - aws --version
    - terraform version
    - |
      # Assume role using OIDC token
      credentials=$(aws sts assume-role-with-web-identity \
          --role-arn ${AWS_ROLE_ARN} \
          --role-session-name "gitlab-ci" \
          --web-identity-token ${GITLAB_OIDC_TOKEN} \
          --region ${AWS_REGION} \
          --query 'Credentials.[AccessKeyId,SecretAccessKey,SessionToken]' \
          --output text)
      # Extract and export credentials
      export AWS_ACCESS_KEY_ID=$(echo $credentials | awk '{print $1}')
      export AWS_SECRET_ACCESS_KEY=$(echo $credentials | awk '{print $2}')
      export AWS_SESSION_TOKEN=$(echo $credentials | awk '{print $3}')
  rules:
    - if: $CI_COMMIT_REF_NAME == "solai_oidc"  # Must match branch name in trust policy

Note: We’re using the hashicorp/terraform image for Terraform commands but installing AWS CLI inside it since the base image doesn’t include AWS CLI by default.

.gitlab-ci.yml

include:
  - local: "pipeline/aws_oidc.yml"

stages:
  - test


test_oidc:
  extends: .assume_aws_role
  stage: test
  variables:
    AWS_REGION: "us-east-1"

script:
  - aws sts get-caller-identity 

📊 Step 5: Run Your Pipeline

Commit and push your changes.
Your job should now securely authenticate using GitLab OIDC token and AWS AssumeRoleWithWebIdentity, no static credentials involved.

📚 Conclusion

OpenID Connect integration in GitLab CI/CD with AWS is a clean, scalable, and secure way to handle cloud infrastructure pipelines. No need to manage static access keys — tokens are short-lived and issued just-in-time for the job.

If you found this helpful, give it a ❤️, share it with your devops crew, or drop your thoughts and improvements in the comments — I’d love to connect and learn from your experiences too!

Powered by solairajan.online

Follow me on

linkedin | linktr.ee