AWS GitLab OIDC Provider Terraform Module

This module allows you to create an AWS IAM OIDC provider that trusts GitLab and the associated IAM roles, that will help GitLab Pipelines to securely authenticate against the AWS API using an IAM role.

We recommend using GitLab's OIDC issuer to get short-lived credentials needed for your pipelines. Specifying role-to-assume without providing an aws-access-key-id or a web-identity-token-file will signal to the pipeline that you wish to use the OIDC provider. The default session duration is 1 hour when using the OIDC provider to directly assume an IAM Role. The default session duration is 6 hours when using an IAM User to assume an IAM Role (by providing an aws-access-key-id, aws-secret-access-key, and a role-to-assume) . If you would like to adjust this you can pass a duration to role-duration-seconds, but the duration cannot exceed the maximum that was defined when the IAM Role was created. The default session name is GitLabRunner-${CI_PROJECT_ID}-${CI_PIPELINE_ID}, and you can modify it by specifying the desired name in role-session-name.

Use-Cases

1. Retrieve temporary credentials from AWS to access cloud services
2. Use credentials to retrieve secrets or deploy to an environment
3. Scope role to branch or project
4. Create an AWS OIDC provider for GitLab Pipelines

Features

2. Create one or more IAM role that can be assumed by GitLab Pipelines
3. IAM roles can be scoped to :
   • One or more GitLab namespaces
   • One or more GitLab project
   • One or more branches in a project

Feature	Status
Create a role for all projects in a specific GitLab namespace	✅
Create a role specific to a project for a specific namespace	✅
Create a role specific to a branch in a project	✅
Create a role for multiple namespaces/projects/branches	✅
Create a role for namesapces/projectss/branches selected by wildcard (e.g. feature/* branches)	✅

---

---

Documentation

• TFLint Rules

Usage example

IMPORTANT: The master branch is used in source just as an example. In your code, do not pin to master because there may be breaking changes between releases. Instead pin to the release tag (e.g. ?ref=tags/x.y.z) of one of our latest releases.

module "gitlab_oidc" {
  source  = "terraform-module/gitlab-oidc-provider/aws"
  version = "~> 1"

  create_oidc_provider = true
  create_oidc_role     = true

  project_paths             = ["project_path:terraform-module/module-blueprint", "project_path:foo/bar"]
  oidc_role_attach_policies = ["arn:aws:iam::aws:policy/AmazonEC2ContainerRegistryReadOnly"]
}

Examples

See examples directory for working examples to reference

• Examples TFM Dir
• Examples Gitlab Pipeline

Assumptions

Available features

AWS Gitlab OIDC Provider Terraform Module

Purpose

This module allows you to create a Gitlab OIDC provider for your AWS account, that will allow Gitlab pipelines to securely authenticate against the AWS API using an IAM role

Requirements

Name	Version
terraform	>= 1
aws	>= 5.40
tls	>= 3.0

Providers

Name	Version
aws	>= 5.40
tls	>= 3.0

Modules

No modules.

Resources

Name	Type
aws_iam_openid_connect_provider.this	resource
aws_iam_role.this	resource
aws_iam_role_policy_attachment.attach	resource
aws_iam_policy_document.this	data source
tls_certificate.gitlab	data source

Inputs

Name	Description	Type	Default	Required
aud_value	(Required) A list of client IDs (also known as audiences). When a mobile or web app registers with an OpenID Connect provider, they establish a value that identifies the application. (This is the value that's sent as the client_id parameter on OAuth requests.)	list(string)	[ "https://gitlab.com" ]	no
create_oidc_provider	Whether or not to create the associated oidc provider. If false, variable 'oidc_provider_arn' is required	bool	true	no
create_oidc_role	Whether or not to create the OIDC attached role	bool	true	no
gitlab_tls_url	the Hashicorp TLS provider has started following redirects starting v4. so we use tls://	string	"tls://gitlab.com:443"	no
match_field	the token field the OIDC provider filter on	string	"sub"	no
max_session_duration	Maximum session duration in seconds.	number	3600	no
oidc_role_attach_policies	Attach policies to OIDC role.	list(string)	[]	no
projects	List of GitLab namesapce/project names authorized to assume the role.	list(string)	[]	no
role_description	(Optional) Description of the role.	string	"Role assumed by the Gitlab OIDC provider."	no
role_name	(Optional, Forces new resource) Friendly name of the role.	string	"gitlab-oidc-provider-aws"	no
tags	A mapping of tags to assign to all resources	map(string)	{}	no
url	GitLab OpenID TLS certificate URL. The address of your GitLab instance, such as https://gitlab.com or http://gitlab.example.com.	string	"https://gitlab.com"	no

Outputs

Name	Description
oidc_provider_arn	OIDC provider ARN
oidc_role	CICD GitHub role.
policy_document	joined IAM policy documents
thumbprint	TLS endpoint certificate SHA1 Fingerprint

📝 Guidelines

• 📝 Use a succinct title and description.
• 🐛 Bugs & feature requests can be be opened
• 📶 Support questions are better asked on Stack Overflow
• 😊 Be nice, civil and polite (as always).

License

Copyright 2019 Ivan Katliarhcuk

MIT Licensed. See LICENSE for full details.

How to Contribute

Submit a pull request

Authors

Currently maintained by Ivan Katliarchuk and these awesome contributors.

Terraform Registry

• Module

Resources

• AWS: create oidc
• Blog: OIDC with AWS and GitLab
• Blog: Gitlab OIDC
• Tfm: OIDC Gitlab

Clone Me

Create a repository using this template →