While injecting AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY through Gitlab variables is a very common practice, it is a suboptimal approach, even when using the Protected flag. Instead the OIDC protocol should be leverage to build more secure pipeline. This will be a very hands-on tutorial on how to it

Get the OIDC token

This is already well documented in the official documentation, but in short: you can ask GitLab to generate one or more tokens for job execution. The name of the token can be anything you choose—ideally, something meaningful. The audience should represent the external system the token is intended for. In this case, STS refers to AWS Secure Token Service.

Exchanging the OICD token

The next step is to exchange the OIDC token for AWS temporary credentials. This is done using STS (Secure Token Service). The syntax is a bit awkward, but it’s still fairly simple. Once complete, you’ll be able to use the AWS CLI as expected.

Configuring AWS

The part were most people struggle is to configure the AWS side. In AWS create go to IAM > Identity providers and create a new one.

If you are unsure about the URL, add /.well-known/openid-configuration to it and it should return JSON. Every OIDC provider exposes their configuration at this endpoint. For Gitlab, the url is https://gitlab.com

Note that the audience field is actually arbitrary—just make sure it matches on both GitLab and AWS, and that it has a meaningful value.

Create an IAM role

This is the fun part—you can now create an IAM role that uses the identity provider we just created as its trusted entity.

Always respect the Principle of Least Privilege when adding permissions!

GitLab includes a sub value in the OIDC token that contains the group, project, and branch information. This is extremely powerful! It means you can create IAM roles that are only usable when running from a specific branch.

For example, the IAM role that deploys to production should include a condition that restricts its usage to the prod branch. In GitLab, you can then enforce protections on the prod branch, such as requiring code reviews. By combining the granularity of IAM roles with GitLab’s branch protection features, you can build a highly secure and compliant DevOps pipeline.