feat: add support for GHES (#39)

* feat: add support for GHES

* chore: remove github-enterprise example until release is published with new variable

Author: artis3n

.github/workflows/pr.yml

@@ -15,6 +15,7 @@ jobs:
           - 'examples/simple-repo/'
           - 'examples/json-files/'
           - 'examples/additional-claims/'
+          # - 'examples/github-enterprise/'
           - 'test/prepare-server/'
           - 'test/configure-vault/'
           - 'test/configure-oidc/'

README.md

@@ -5,23 +5,24 @@
 ![GitHub contributors](https://img.shields.io/github/contributors/digitalocean/terraform-vault-github-oidc?style=flat-square)
 ![GitHub last commit](https://img.shields.io/github/last-commit/digitalocean/terraform-vault-github-oidc?style=flat-square)
 
-Terraform module to configure Vault for GitHub OIDC authentication from Action runners.
+Terraform module to configure Vault for GitHub OIDC authentication from Action runners on GitHub.com or self-hosted GitHub Enterprise Server.
 
 OIDC authentication allows us to bind GitHub repositories (and subcomponents of a repository, such as a branch, ref, or environment)
 to a Vault role without needing to manage actual credentials that require a lifecycle system, integration into repo-level
 GitHub Secrets, or other organizational glue.
 
 Reference documents that help with understanding the process:
-- <https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/configuring-openid-connect-in-hashicorp-vault>
-- <https://medium.com/hashicorp-engineering/push-button-security-for-your-github-actions-d4fffde1df20>
+- <https://docs.github.com/en/enterprise-cloud@latest/actions/deployment/security-hardening-your-deployments/configuring-openid-connect-in-hashicorp-vault>
 
 Once OIDC authentication is configured on a Vault server via this module, a GitHub repository can leverage
 [hashicorp/vault-action](https://github.com/hashicorp/vault-action) to retrieve secrets from Vault with GitHub OIDC authentication.
 No credential management needed!
 
+e.g.
+
 ```yml
 - name: Import Secrets
-  uses: hashicorp/[email protected].0
+  uses: hashicorp/[email protected].1
   id: secrets
   with:
     exportEnv: false
@@ -49,6 +50,7 @@ No credential management needed!
       - [oidc_bindings.ttl](#oidc_bindingsttl)
     - [default_ttl](#default_ttl)
     - [oidc_auth_backend_path](#oidc_auth_backend_path)
+    - [github_identity_provider](#github_identity_provider)
   - [Requirements](#requirements)
   - [Providers](#providers)
   - [Modules](#modules)
@@ -65,7 +67,7 @@ The module requires you to configure what repositories to bind to Vault roles an
 conditions the respective repository should be granted access.
 This is encapsulated by the `oidc_bindings` variable.
 
-| :exclamation: Note: This module uses the experimental Terraform feature [`module_variable_optional_attrs`](https://www.terraform.io/language/expressions/type-constraints#experimental-optional-object-type-attributes). |
+| :exclamation: Note: This module uses the experimental Terraform feature [`module_variable_optional_attrs`](https://www.terraform.io/language/expressions/type-constraints#experimental-optional-object-type-attributes) first introduced in v0.14. |
 |---|
 
 You will need to opt-in to this experiment in your `terraform` block:
@@ -260,6 +262,18 @@ Do **not** include a leading `/` in the variable content.
 At this time, this module expects to create and manage the JWT backend leveraged for GitHub OIDC auth.
 You cannot pass in a Terraform reference to an existing backend.
 
+### github_identity_provider
+
+**Optional**
+
+By default, this role will communicate with github.com for an OIDC JWT (`https://token.actions.githubusercontent.com`).
+If you run GitHub Enterprise Server, you will need to configure your instance of GitHub as the identity provider and should modify this variable.
+This requires GitHub Enterprise Server version 3.5 or higher.
+
+The format is: `https://HOSTNAME/_services/token`.
+
+See <https://docs.github.com/en/enterprise-server@latest/actions/deployment/security-hardening-your-deployments/configuring-openid-connect-in-hashicorp-vault#adding-the-identity-provider-to-hashicorp-vault>.
+
 <!-- BEGINNING OF PRE-COMMIT-TERRAFORM DOCS HOOK -->
 ## Requirements
 
@@ -292,6 +306,7 @@ No modules.
 | <a name="input_oidc_bindings"></a> [oidc\_bindings](#input\_oidc\_bindings) | A list of OIDC JWT bindings between GitHub repos and Vault roles. For each entry, you must include:<br><br>  `audience`: By default, this must be the URL of the repository owner (e.g. `https://github.com/digitalocean`). This can be customized with the `jwtGithubAudience` parameter in [hashicorp/vault-action](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/configuring-openid-connect-in-hashicorp-vault#requesting-the-access-token) . This is the bound audience (`aud`) field from [GitHub's OIDC token](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect#understanding-the-oidc-token) .<br><br>  `vault_role_name`: The name of the Vault role to generate under the OIDC auth backend.<br><br>  `bound_subject`: This is what is set in the `sub` field from [GitHub's OIDC token](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect#understanding-the-oidc-token) . The bound subject can be constructed from various filters, such as a branch, tag, or specific [environment](https://docs.github.com/en/actions/deployment/targeting-different-environments/using-environments-for-deployment) . See [GitHub's documentation](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect#example-subject-claims) for examples.<br><br>  `vault_policies`: A list of Vault policies you wish to grant to the generated token.<br><br>  `user_claim`: **Optional**. This is how you want Vault to [uniquely identify](https://www.vaultproject.io/api/auth/jwt#user_claim) this client. This will be used as the name for the Identity entity alias created due to a successful login. This must be a field present in the [GitHub JWT token](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect#understanding-the-oidc-token) . Defaults to the `default_user_claim` variable if not provided. Consider the impact on [reusable workflows](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/using-openid-connect-with-reusable-workflows#how-the-token-works-with-reusable-workflows) if you are thinking of changing this value from the default.<br><br>  `additional_claims`: **Optional**. Any additional `bound_claims` to configure for this role. Claim keys must match a value in [GitHub's OIDC token](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect#understanding-the-oidc-token) . Do not use this field for the `sub` claim. Use the `bound_subject` parameter instead.<br><br>  `ttl`: **Optional**. The default incremental time-to-live for the generated token, in seconds. Defaults to the `default_ttl` value but can be individually specified per binding with this value. | <pre>list(object({<br>    audience          = string,<br>    vault_role_name   = string,<br>    bound_subject     = string,<br>    vault_policies    = set(string),<br>    user_claim        = optional(string),<br>    additional_claims = optional(map(string)),<br>    ttl               = optional(number),<br>  }))</pre> | n/a | yes |
 | <a name="input_default_ttl"></a> [default\_ttl](#input\_default\_ttl) | The default incremental time-to-live for generated tokens, in seconds. | `number` | `60` | no |
 | <a name="input_default_user_claim"></a> [default\_user\_claim](#input\_default\_user\_claim) | This is how you want Vault to [uniquely identify](https://www.vaultproject.io/api/auth/jwt#user_claim) this client. This will be used as the name for the Identity entity alias created due to a successful login. This must be a field present in the [GitHub OIDC token](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect#understanding-the-oidc-token) . Consider the impact on [reusable workflows](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/using-openid-connect-with-reusable-workflows#how-the-token-works-with-reusable-workflows) if you are thinking of changing this value from the default. | `string` | `"job_workflow_ref"` | no |
+| <a name="input_github_identity_provider"></a> [github\_identity\_provider](#input\_github\_identity\_provider) | The JWT authentication URL used for the GitHub OIDC trust configuration. This should not be modified unless you are running GitHub Enterprise Server, in which case you should provide a URL in the format: `https://HOSTNAME/_services/token`. This requires GitHub Enterprise Server version 3.5 or higher. See <https://docs.github.com/en/enterprise-server@latest/actions/deployment/security-hardening-your-deployments/configuring-openid-connect-in-hashicorp-vault#adding-the-identity-provider-to-hashicorp-vault>. | `string` | `"https://token.actions.githubusercontent.com"` | no |
 | <a name="input_oidc_auth_backend_path"></a> [oidc\_auth\_backend\_path](#input\_oidc\_auth\_backend\_path) | The path to mount the OIDC auth backend. | `string` | `"github-actions"` | no |
 
 ## Outputs

examples/additional-claims/README.md

@@ -23,7 +23,7 @@ to an `oidc-binding` via this module.
 
 | Name | Source | Version |
 |------|--------|---------|
-| <a name="module_github_oidc"></a> [github\_oidc](#module\_github\_oidc) | digitalocean/github-oidc/vault | ~> 1.0.1 |
+| <a name="module_github_oidc"></a> [github\_oidc](#module\_github\_oidc) | digitalocean/github-oidc/vault | ~> 1.0.2 |
 
 ## Resources
 

examples/additional-claims/main.tf

@@ -5,7 +5,7 @@ provider "vault" {
 
 module "github_oidc" {
   source  = "digitalocean/github-oidc/vault"
-  version = "~> 1.0.1"
+  version = "~> 1.0.2"
 
   oidc_bindings = [
     {

examples/github-enterprise/README.md

@@ -0,0 +1,49 @@
+# GitHub Enterprise Server Example
+
+Example configuration in this directory binds multiple Vault roles to one GitHub repository with GitHub OIDC.
+When using GitHub Enterprise Server, configure this module as normal and update the `github_identity_provider` variable [as applicable](https://github.com/digitalocean/terraform-vault-github-oidc#github_identity_provider) for your GitHub server.
+
+# Usage
+
+<!-- BEGINNING OF PRE-COMMIT-TERRAFORM DOCS HOOK -->
+## Requirements
+
+| Name | Version |
+|------|---------|
+| <a name="requirement_terraform"></a> [terraform](#requirement\_terraform) | >= 1.1.0 |
+| <a name="requirement_vault"></a> [vault](#requirement\_vault) | >= 3.4.1 |
+
+## Providers
+
+| Name | Version |
+|------|---------|
+| <a name="provider_vault"></a> [vault](#provider\_vault) | >= 3.4.1 |
+
+## Modules
+
+| Name | Source | Version |
+|------|--------|---------|
+| <a name="module_github_oidc"></a> [github\_oidc](#module\_github\_oidc) | digitalocean/github-oidc/vault | ~> 1.0.2 |
+
+## Resources
+
+| Name | Type |
+|------|------|
+| [vault_policy.example](https://registry.terraform.io/providers/hashicorp/vault/latest/docs/resources/policy) | resource |
+| [vault_auth_backend.generated_backend](https://registry.terraform.io/providers/hashicorp/vault/latest/docs/data-sources/auth_backend) | data source |
+| [vault_policy_document.example](https://registry.terraform.io/providers/hashicorp/vault/latest/docs/data-sources/policy_document) | data source |
+
+## Inputs
+
+| Name | Description | Type | Default | Required |
+|------|-------------|------|---------|:--------:|
+| <a name="input_vault_address"></a> [vault\_address](#input\_vault\_address) | The origin URL of the Vault server. This is a URL with a scheme, a hostname, and a port but with no path. | `string` | n/a | yes |
+
+## Outputs
+
+| Name | Description |
+|------|-------------|
+| <a name="output_auth_backend_accessor"></a> [auth\_backend\_accessor](#output\_auth\_backend\_accessor) | The generated accessor ID for the auth backend. Outputting as demonstration of using a data source with the module. |
+| <a name="output_backend"></a> [backend](#output\_backend) | Exposing the auth backend path as an example. |
+| <a name="output_roles"></a> [roles](#output\_roles) | The list of Vault role names created by the module. This is a reflection of the `vault_role_name` value of each input item in `oidc-bindings`. |
+<!-- END OF PRE-COMMIT-TERRAFORM DOCS HOOK -->

examples/github-enterprise/main.tf

@@ -0,0 +1,46 @@
+// Vault token should be provided in VAULT_TOKEN env var
+provider "vault" {
+  address = var.vault_address
+}
+
+module "github_oidc" {
+  source  = "digitalocean/github-oidc/vault"
+  version = "~> 1.0.2"
+
+  github_identity_provider = "https://github.fakeexample.digitalocean.com/_services/token"
+
+  oidc_bindings = [
+    {
+      audience : "https://github.com/artis3n",
+      vault_role_name : "oidc-test",
+      bound_subject : "repo:artis3n/github-oidc-vault-example:environment:nonprod",
+      vault_policies : [
+        vault_policy.example.name,
+      ],
+    },
+    {
+      audience : "https://github.com/artis3n",
+      vault_role_name : "oidc-prod-test",
+      bound_subject : "repo:artis3n/github-oidc-vault-example:ref:refs/heads/main",
+      vault_policies : [
+        vault_policy.example.name,
+      ],
+    },
+  ]
+}
+
+resource "vault_policy" "example" {
+  name   = "oidc-example"
+  policy = data.vault_policy_document.example.hcl
+}
+
+data "vault_policy_document" "example" {
+  rule {
+    path         = "secret/data/foo/bar"
+    capabilities = ["list", "read"]
+  }
+}
+
+data "vault_auth_backend" "generated_backend" {
+  path = module.github_oidc.auth_backend_path
+}

examples/github-enterprise/outputs.tf

@@ -0,0 +1,14 @@
+output "backend" {
+  description = "Exposing the auth backend path as an example."
+  value       = module.github_oidc.auth_backend_path
+}
+
+output "auth_backend_accessor" {
+  description = "The generated accessor ID for the auth backend. Outputting as demonstration of using a data source with the module."
+  value       = data.vault_auth_backend.generated_backend.accessor
+}
+
+output "roles" {
+  description = "The list of Vault role names created by the module. This is a reflection of the `vault_role_name` value of each input item in `oidc-bindings`."
+  value       = module.github_oidc.oidc_bindings_names
+}

examples/github-enterprise/variables.tf

@@ -0,0 +1,4 @@
+variable "vault_address" {
+  type        = string
+  description = "The origin URL of the Vault server. This is a URL with a scheme, a hostname, and a port but with no path."
+}

examples/github-enterprise/versions.tf

@@ -0,0 +1,11 @@
+terraform {
+  required_version = ">= 1.1.0"
+  experiments      = [module_variable_optional_attrs]
+
+  required_providers {
+    vault = {
+      source  = "hashicorp/vault"
+      version = ">= 3.4.1"
+    }
+  }
+}

examples/json-files/README.md

@@ -30,7 +30,7 @@ Dev teams create their own JSON files representing repos they own and wish to bi
 
 | Name | Source | Version |
 |------|--------|---------|
-| <a name="module_github_oidc"></a> [github\_oidc](#module\_github\_oidc) | digitalocean/github-oidc/vault | ~> 1.0.1 |
+| <a name="module_github_oidc"></a> [github\_oidc](#module\_github\_oidc) | digitalocean/github-oidc/vault | ~> 1.0.2 |
 
 ## Resources