Why OIDC for GitHub Actions?

For years, managing your AWS authentication within CI/CD pipelines like GitHub Actions depended on static AWS access keys. Now, if a pipeline contains these credentials, anyone with access to the CI/CD logs can easily use the echo command and retrieve them within a job itself. This made it difficult to prevent accidental exposure, especially in environments where multiple engineers had access to workflow execution.

AWS access keys stored in GitHub Secrets needed to be rotated frequently - ideally weekly or monthly - to limit the window of compromise in case of leakage of these creds. However, even with regular rotation, these credentials still remained active between deployments, increasing the risk of misuse. A misconfigured permission or an overlooked log statement could expose credentials in a CI/CD job.

To address this, AWS introduced OpenID Connect (OIDC) as an authentication method that removes the need to store static AWS credentials. Instead of embedding access keys within GitHub Actions, OIDC allows GitHub to request temporary, scoped credentials from AWS IAM during a workflow execution. This makes sure that authentication is session-based and tied directly to the job execution, preventing credentials from being exposed or misused outside of that context.

When a GitHub Actions workflow runs, GitHub generates an OIDC token containing details like the repository name, branch, and workflow file. AWS validates this token against a pre-configured IAM trust policy, making sure that only workflows from authorized repositories and branches can assume the IAM role. This eliminates the risk of leaked credentials being reused elsewhere on the Internet, as the authentication process is bound to the specific workflow that requested access.

For Terraform deployments, OIDC not only improves security but also simplifies role-based access management. Workflows can assume different IAM roles dynamically based on their repository and branch. A development branch can have access to staging resources, while production deployments are restricted to workflows running on the main branch. These IAM roles automatically expire once the workflow is complete, reducing the risk of credentials lingering within the environment.

How Identity Federation Works in GitHub Actions

Once GitHub Actions is set up to authenticate with AWS, workflows no longer need static credentials. Instead, they can request temporary credentials dynamically, reducing security risks.

This is made possible by OIDC, which establishes a trust relationship between GitHub and AWS IAM. With this setup, only authorized workflows can assume IAM roles, making sure that access is granted based on the repository, branch, and workflow context.

When a workflow runs, GitHub automatically generates an OIDC token containing metadata such as the repository name, branch, and workflow file. AWS then validates this token against its OIDC trust policy. If the request meets the required conditions, AWS issues temporary credentials that the workflow can use, which automatically expire once the workflow is complete.

The process follows these steps:

GitHub Generates an OIDC Token

GitHub Actions creates a unique, time-limited token that contains details about the workflow, including the repository, branch, and workflow name. This token cannot be reused and expires shortly after it is issued.

AWS IAM Validates the Token

AWS checks the token against GitHub’s OIDC provider (https://token.actions.githubusercontent.com) to confirm it was issued by a trusted source. IAM then verifies if the repository, branch, and workflow match the conditions set in the trust policy.

AWS Issues Temporary Credentials

If the validation is successful, AWS provides short-lived credentials that allow the workflow to assume an IAM role. These credentials automatically expire after the workflow completes, preventing long-term access risks.

This process makes sure that only authorized GitHub Actions workflows can access AWS without requiring any static credentials.

Configuring IAM Roles to Trust GitHub Actions

Now, for GitHub Actions to assume AWS IAM roles through OIDC, AWS must be set up to trust GitHub’s OIDC provider and issue credentials only to workflows that meet specific conditions.

• The trust policy must explicitly define GitHub’s OIDC provider as a valid identity source.
• Access should be restricted based on repository name, workflow name, and branch to prevent unauthorized workflows from assuming IAM roles.
• Separate roles should be created for different environments, such as staging and production, to enforce least-privilege access.

When configured correctly, GitHub Actions can authenticate securely with AWS IAM, making sure that only trusted workflows can deploy infrastructure.

Setting Up GitHub Actions to Use OIDC

Now, GitHub Actions can authenticate to AWS dynamically, but for this to work, the workflow must be configured to request and use an OIDC token. Unlike static credentials stored in GitHub Secrets, this approach allows GitHub Actions to obtain temporary, scoped access to AWS resources without ever storing long-lived access keys.

For a workflow to authenticate with AWS using OIDC, it must do three things:

• Request an OIDC token from GitHub’s identity provider.
• Use that token to assume an IAM role in AWS.
• Run Terraform or other AWS-related tasks using the temporary credentials.

Each step requires specific permissions and configurations to ensure authentication works correctly.

How GitHub Actions Requests an OIDC Token

When a GitHub Actions workflow runs, GitHub automatically generates an OIDC token for that workflow execution. This token serves as proof that the request is coming from a trusted GitHub repository and is signed by GitHub’s OIDC provider. AWS IAM then verifies this token before granting access.

To allow a workflow to request an OIDC token, the GitHub Actions configuration must explicitly enable the id-token: write permission. This permission tells GitHub that the workflow should allow the retrieval of an OIDC token during execution. Without this, AWS IAM will not be able to validate the request.

Once this is enabled, the workflow can request an OIDC token and use it to authenticate with AWS.

Permissions Required for OIDC Authentication

OIDC authentication is based on IAM roles, so it is important that only authorized workflows can assume these roles. To enforce this, IAM roles must be configured with trust policies that restrict access based on the following:

• The GitHub repository where the workflow is running.
• The specific branch that triggered the workflow.
• The workflow file name, making sure that only approved workflows can assume the role.

On the GitHub Actions side, the workflow must be configured with the correct permissions to authenticate using OIDC and assume the IAM role. This is done using the aws-actions/configure-aws-credentials action, which allows the workflow to retrieve temporary AWS credentials using the OIDC token.

Here, GitHub retrieves the OIDC token and uses it to assume the IAM role defined in AWS. Once this step runs, Terraform or any other AWS service can be executed without requiring any kind of static credentials.

How GitHub Workflows Assume AWS IAM Roles Without Credentials

Now, because these credentials expire after use, there is no risk of leaked secrets being misused later. Each workflow execution starts with a fresh, temporary session, making the entire authentication process secure and fully automated.

Configuring OIDC Authentication and Terraform in GitHub Actions

Now that GitHub Actions is set up to request an OIDC token, the next step is configuring AWS IAM to trust GitHub’s OIDC provider and defining an IAM role that Terraform can assume dynamically. Once the role is in place, we will configure a GitHub Actions workflow to authenticate with AWS using OIDC and run Terraform deployments without requiring static credentials.

Creating an OIDC Provider in AWS IAM

For AWS to trust GitHub’s OIDC tokens, an OIDC provider must be created in IAM. This acts as a bridge between GitHub Actions and AWS, allowing workflows to authenticate dynamically.

1. Navigate to AWS IAM → Identity Providers and click Add Provider.
2. Select OpenID Connect (OIDC) as the provider type.
3. Enter GitHub’s OIDC URL: https://token.actions.githubusercontent.com
4. For the audience, use: sts.amazonaws.com‍
5. Click Add Provider to save the configuration.

This OIDC provider allows AWS to verify that authentication requests are coming from GitHub Actions instead of requiring hardcoded credentials.

Creating an IAM Role for GitHub Actions

With the OIDC provider in place, we now need to create an IAM role that Terraform can assume during GitHub Actions workflows. This role ensures secure access control by restricting authentication to specific repositories and branches. However, it can also be configured to allow workflows from all branches of a repository or even from multiple repositories within an organization.

To create the IAM role:

• Navigate to AWS IAM → Roles and click Create Role.
• Select Web Identity and choose the GitHub OIDC provider created earlier.
• For the audience, enter sts.amazonaws.com.

Now, define a trust policy that limits role assumption to a specific repository and branch:

Replace <AWS_ACCOUNT_ID> with your AWS account ID.

Replace <GITHUB_ORG> and <REPO> with the GitHub organization and repository names.

This setup ensures that only workflows running on the main branch of the specified repository can assume the role.

Expanding Access to All Branches in a Repository

If you want any branch within the repository to assume the role, modify the policy as follows:

This allows workflows from any branch (*) to authenticate.

Allowing Access from All Repositories in an Organization

To grant access to all repositories within an organization, update the policy:

This setup enables role assumption from any repository under <GITHUB_ORG>, which is useful for centralized IAM management across multiple repositories.

Attaching Permissions

After defining the trust policy, attach the necessary IAM permissions to the role based on the resources Terraform needs to manage:

• S3 permissions if Terraform stores state files.
• DynamoDB permissions for state locking.
• EC2, IAM, or other AWS service permissions depending on the deployment requirements.

Once done, click Create Role and copy the Role ARN for use in GitHub Actions.

By using the IAM role’s trust policy, you can make sure that the right level of access - whether for a single branch, all branches in a repository, or across an entire organization.

Writing the GitHub Actions Workflow

With the IAM role set up, we can now write a GitHub Actions workflow that:

• Checks out the repository.
• Configures AWS credentials dynamically using OIDC.
• Initializes Terraform and generates a plan output.
• Runs Terraform to apply changes.

Create a new workflow file in your repository at .github/workflows/terraform.yml

Add the following workflow configuration:

This workflow performs the following:

• Requests an OIDC token and assumes the IAM role stored in AWS_ROLE_ARN.
• Runs Terraform init to initialize the configuration.
• Executes Terraform plan and generates a plan file (tf.plan).
• Applies the plan with Terraform apply, making infrastructure changes.

The aws sts get-caller-identity step is included to verify that the workflow assumed the IAM role correctly. If OIDC authentication is working, this step will return the assumed role details instead of failing due to missing credentials.

Running Terraform with OIDC

With everything configured, pushing changes to the main branch will trigger the workflow. The workflow will:

• Authenticate with AWS using OIDC, without requiring static credentials.
• Assume the correct IAM role and execute Terraform commands.
• Deploy infrastructure securely and dynamically.

To confirm that OIDC authentication is working correctly:

1. Push a change to the main branch.
2. Go to GitHub Actions → Workflows → Terraform Deployment.
3. Check the "Verify IAM Role Assumption" step.

• If it prints details about the IAM role, authentication is successful.
• If it fails, review IAM trust policies and permissions.

Once Terraform runs successfully, it will deploy infrastructure without any long-lived AWS credentials, ensuring a more secure CI/CD pipeline.

Best Practices for OIDC and Terraform in CI/CD

Now, to ensure security and control within these CI/CD pipelines, you need to follow some of the best practices when using OIDC.

Use Role Conditions to Restrict Repository and Branch Access

Define IAM trust policies to allow role assumption only from specific repositories and branches. This ensures that only approved workflows can authenticate with AWS, preventing unauthorized access.    

Minimize Permissions for Terraform IAM Roles

Follow least-privilege access by granting only the required permissions for Terraform operations. Restrict actions like iam:PassRole and ec2:TerminateInstances to avoid excessive privileges.

Enable OIDC Token Logging and Monitoring

Track OIDC token usage in AWS CloudTrail to detect anomalies. Set up alerts for unexpected role assumptions and investigate unauthorized workflow executions.

Avoid Hardcoding Any AWS Credentials in Workflows

Rely entirely on OIDC-based authentication to eliminate static AWS credentials. Storing long-lived access keys in GitHub Secrets or environment variables introduces unnecessary security risks.

Now, once changes are committed to a CI/CD pipeline, there’s often a lack of visibility into what is actually being deployed. Teams working with complex AWS environments struggle to track dependencies between resources, making it difficult to understand how changes will impact their infrastructure. Security and compliance are another concern - misconfigurations such as public-facing resources, weak IAM policies, or unmonitored instances can slip through, leading to security risks.

Another challenge is cost control. Terraform plan outputs give limited insight into estimated expenses, and without a way to preview the financial impact, teams may unknowingly provision costly resources. These gaps in visibility, compliance, and cost awareness make infrastructure management reactive rather than proactive.

Firefly: Bringing Control and Clarity to Terraform Workflows

Firefly integrates directly into your CI/CD pipelines to enhance Terraform workflows by providing real-time insights before infrastructure changes are applied. Instead of working with static Terraform plans, Firefly visualizes infrastructure dependencies, highlighting how resources are connected. This allows teams to understand what will be created, modified, or deleted before running terraform apply, reducing the risk of unexpected issues.

Security policies are another area where Firefly adds value. It scans Terraform plans and flags misconfigurations that could expose infrastructure to threats. A simple oversight, like an EC2 instance missing a monitoring agent or a public subnet being assigned an external IP, can lead to compliance violations. Firefly prevents these risks by enforcing predefined policies, making sure that only secure infrastructure gets deployed.

Beyond security, Firefly also provides cost visibility. By analyzing Terraform plans, it estimates expenses before deployment, helping teams make informed decisions. Instead of discovering excessive costs after resources are already running, teams can adjust configurations early to align with budget constraints.

Now, one of the biggest challenges in managing infrastructure is making sure that every deployment adheres to security and compliance requirements. Firefly introduces Guardrails, an extra layer of protection that actively blocks misconfigurations before they reach production. Instead of relying solely on post-deployment security scans, Guardrails enforce policies in real-time, preventing unsafe configurations from being deployed.

When a policy violation is detected, Firefly immediately flags the issue and halts the deployment. This makes sure that resources are not only correctly provisioned but also meet security best practices. Whether it’s preventing unauthorized public IPs, enforcing encryption standards, or restricting IAM role permissions, Firefly adds a safeguard that minimizes risk before infrastructure goes live.

Infrastructure automation is about more than just speed - it requires security, compliance, and cost awareness at every stage. By integrating Firefly into a Terraform workflow, DevOps teams gain complete visibility into their infrastructure changes, enforce security policies before deployments, and maintain control over costs as well. With Firefly’s visual representation of resources, guardrail enforcement, and continuous monitoring, infrastructure changes become more predictable and controlled.

Conclusion

Till now, you should have a clear understanding of how OIDC simplifies authentication in GitHub Actions and enhances security by eliminating long-lived credentials. Integrating OIDC with Terraform deployments ensures controlled, role-based access while reducing the risks associated with static secrets. With this setup, infrastructure deployments become more secure, manageable, and aligned with best practices for cloud automation.

Frequently Asked Questions

Is OIDC better than SAML?

OIDC is better for modern applications and API-based authentication, while SAML is more suited for enterprise SSO in traditional environments.

Does GitHub use OIDC?

Yes, GitHub provides an OIDC provider that allows workflows to authenticate with cloud platforms like AWS without storing static credentials.

What is OIDC provider for GitHub Actions?

GitHub's OIDC provider (https://token.actions.githubusercontent.com) issues tokens that workflows use to authenticate with cloud platforms.

Does OIDC use HTTP?

Yes, OIDC operates over HTTP and uses JSON Web Tokens (JWTs) for secure authentication and authorization.