From 7737b5e8d0ec78da832e03f999d46b8f341efb0c Mon Sep 17 00:00:00 2001 From: "pablo.sanchez" Date: Thu, 5 Feb 2026 15:29:54 +0100 Subject: [PATCH 1/2] docs(azure-oidc): update docs and added examples --- modules/azure-oidc/.terraform-docs.yml | 48 ++++++ modules/azure-oidc/README.md | 157 ++++++++++++++++++ modules/azure-oidc/_examples/basic/main.tf | 21 +++ .../azure-oidc/_examples/basic/values.yaml | 11 ++ modules/azure-oidc/docs/footer.md | 16 ++ modules/azure-oidc/docs/header.md | 98 +++++++++++ 6 files changed, 351 insertions(+) create mode 100644 modules/azure-oidc/.terraform-docs.yml create mode 100644 modules/azure-oidc/_examples/basic/main.tf create mode 100644 modules/azure-oidc/_examples/basic/values.yaml create mode 100644 modules/azure-oidc/docs/footer.md create mode 100644 modules/azure-oidc/docs/header.md diff --git a/modules/azure-oidc/.terraform-docs.yml b/modules/azure-oidc/.terraform-docs.yml new file mode 100644 index 000000000..177fda243 --- /dev/null +++ b/modules/azure-oidc/.terraform-docs.yml @@ -0,0 +1,48 @@ +formatter: "markdown" + +version: "" + +header-from: docs/header.md +footer-from: docs/footer.md + +recursive: + enabled: false + path: modules + include-main: true + +sections: + hide: [] + show: [] + +content: "" + +output: + file: "README.md" + mode: inject + template: |- + + {{ .Content }} + + +output-values: + enabled: false + from: "" + +sort: + enabled: true + by: name + +settings: + anchor: true + color: true + default: true + description: false + escape: true + hide-empty: false + html: true + indent: 2 + lockfile: true + read-comments: true + required: true + sensitive: true + type: true \ No newline at end of file diff --git a/modules/azure-oidc/README.md b/modules/azure-oidc/README.md index a3d949553..5bcb9dc5d 100644 --- a/modules/azure-oidc/README.md +++ b/modules/azure-oidc/README.md @@ -107,3 +107,160 @@ app_registrations: # scope: # - "/subscriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" # This is similar to not putting scope ``` + + +# Azure OIDC Terraform Module + +## Overview + +This Terraform module creates Azure AD applications, service principals, and role assignments for each application defined in the input data file. It supports federated credentials for GitHub Actions and other issuers. + +> Note: Not defining a scope in an application is equivalent to defining the scope of the subscription. + +## Main features +- Create multiple Azure AD applications and service principals. +- Assign custom roles and scopes to each application. +- Add federated credentials for GitHub Actions or custom issuers. +- Realistic configuration example. + +## Complete usage example + +### Module usage +```hcl +module "github-oidc" { + source = "git::https://github.com/prefapp/tfm.git//modules/azure-oidc?ref=" + data = yamldecode(file("")) +} +``` + +### Example data file +```yaml +applications: + - name: app + roles: + - role1 + - role2 + scope: + - scope1 + - scope2 + federated_credentials: + - subject: "subject_claim_foo:my_repo_foo" + issuer: "issuer_foo" + - subject: "subject_claim_bar:my_repo_bar" + issuer: "issuer_bar" + - name: app2 + roles: + - role1 + federated_credentials: + - subject: "my_repo_foo_foo" + issuer: "issuer_foo_foo" +``` + +#### Realistic example +```yaml +app_registrations: + - name: service_repositories + roles: + - AcrPush + - AcrPull + scope: + - "/subscriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/resourceGroups/foo/providers/Microsoft.ContainerRegistry/registries/foo-registries" + - "/subscriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/resourceGroups/bar/providers/Microsoft.ContainerRegistry/registries/bar-registries" + federated_credentials: + - subject: "repository_owner:prefapp" + issuer: "https://token.actions.githubusercontent.com" + - name: state_repositorie + roles: + - AcrPush + scope: + - "/subscriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/resourceGroups/foo/providers/Microsoft.ContainerRegistry/registries/foo-registries" + federated_credentials: + - subject: "repository_owner:prefapp" + issuer: "https://token.actions.githubusercontent.com" + - name: infra_repositorie + roles: + - Contributor + federated_credentials: + - subject: "my_repo_foo" + issuer: "issuer_foo" + - subject: "my_repo_bar" + issuer: "issuer_bar" + # scope: + # - "/subscriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" # This is similar to not putting scope +``` + +## Notes +- If you do not define a scope, the subscription scope will be used by default. +- Federated credentials support GitHub Actions and custom issuers. +- Each application can have multiple roles, scopes, and federated credentials. + +## File structure + +``` +. +├── main.tf +├── variables.tf +├── outputs.tf +├── README.md +├── CHANGELOG.md +└── docs/ + ├── header.md + └── footer.md +``` + +## Requirements + +| Name | Version | +|------|---------| +| [azuread](#requirement\_azuread) | ~> 2.15.0 | +| [azurerm](#requirement\_azurerm) | >3.0.0 | + +## Providers + +| Name | Version | +|------|---------| +| [azuread](#provider\_azuread) | ~> 2.15.0 | +| [azurerm](#provider\_azurerm) | >3.0.0 | + +## Modules + +No modules. + +## Resources + +| Name | Type | +|------|------| +| [azuread_application.gh_oidc_ad_app](https://registry.terraform.io/providers/hashicorp/azuread/latest/docs/resources/application) | resource | +| [azuread_application_federated_identity_credential.gh_oidc_identity_credential](https://registry.terraform.io/providers/hashicorp/azuread/latest/docs/resources/application_federated_identity_credential) | resource | +| [azuread_service_principal.gh_oidc_service_principal](https://registry.terraform.io/providers/hashicorp/azuread/latest/docs/resources/service_principal) | resource | +| [azurerm_role_assignment.gh_oidc_service_role_assignment](https://registry.terraform.io/providers/hashicorp/azurerm/latest/docs/resources/role_assignment) | resource | +| [azuread_client_config.current](https://registry.terraform.io/providers/hashicorp/azuread/latest/docs/data-sources/client_config) | data source | +| [azurerm_subscription.primary](https://registry.terraform.io/providers/hashicorp/azurerm/latest/docs/data-sources/subscription) | data source | + +## Inputs + +| Name | Description | Type | Default | Required | +|------|-------------|------|---------|:--------:| +| [data](#input\_data) | YAML data for configuring resources | `any` | n/a | yes | + +## Outputs + +No outputs. + +## Examples + +For detailed examples, refer to the [module examples](https://github.com/prefapp/tfm/tree/main/modules/azure-oidc/_examples): + +- [basic](https://github.com/prefapp/tfm/tree/main/modules/azure-oidc/_examples/basic) - OIDC and federated credentials configuration for workloads (e.g., GitHub Actions). + +## Resources and support + +- [Official Azure AD Application documentation](https://learn.microsoft.com/en-us/azure/active-directory/develop/app-objects-and-service-principals) +- [Terraform reference for azuread\_application](https://registry.terraform.io/providers/hashicorp/azuread/latest/docs/resources/application) +- [Terraform reference for azuread\_application\_federated\_identity\_credential](https://registry.terraform.io/providers/hashicorp/azuread/latest/docs/resources/application_federated_identity_credential) +- [Terraform reference for azurerm\_role\_assignment](https://registry.terraform.io/providers/hashicorp/azurerm/latest/docs/resources/role_assignment) + +## Support + +For issues, questions, or contributions related to this module, please visit the [repository's issue tracker](https://github.com/prefapp/tfm/issues). + \ No newline at end of file diff --git a/modules/azure-oidc/_examples/basic/main.tf b/modules/azure-oidc/_examples/basic/main.tf new file mode 100644 index 000000000..de6ce0e6e --- /dev/null +++ b/modules/azure-oidc/_examples/basic/main.tf @@ -0,0 +1,21 @@ +module "azure_oidc" { + source = "../../" + + data = { + app_registrations = [ + { + name = "service_repositories" + roles = ["AcrPush", "AcrPull"] + scope = [ + "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/foo/providers/Microsoft.ContainerRegistry/registries/foo-registry" + ] + federated_credentials = [ + { + subject = "repository_owner:prefapp" + issuer = "https://token.actions.githubusercontent.com" + } + ] + } + ] + } +} diff --git a/modules/azure-oidc/_examples/basic/values.yaml b/modules/azure-oidc/_examples/basic/values.yaml new file mode 100644 index 000000000..8fe9ef2b1 --- /dev/null +++ b/modules/azure-oidc/_examples/basic/values.yaml @@ -0,0 +1,11 @@ +data: + app_registrations: + - name: service_repositories + roles: + - AcrPush + - AcrPull + scope: + - /subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/foo/providers/Microsoft.ContainerRegistry/registries/foo-registry + federated_credentials: + - subject: repository_owner:prefapp + issuer: https://token.actions.githubusercontent.com \ No newline at end of file diff --git a/modules/azure-oidc/docs/footer.md b/modules/azure-oidc/docs/footer.md new file mode 100644 index 000000000..3bc0096a1 --- /dev/null +++ b/modules/azure-oidc/docs/footer.md @@ -0,0 +1,16 @@ +## Examples + +For detailed examples, refer to the [module examples](https://github.com/prefapp/tfm/tree/main/modules/azure-oidc/_examples): + +- [basic](https://github.com/prefapp/tfm/tree/main/modules/azure-oidc/_examples/basic) - OIDC and federated credentials configuration for workloads (e.g., GitHub Actions). + +## Resources and support + +- [Official Azure AD Application documentation](https://learn.microsoft.com/en-us/azure/active-directory/develop/app-objects-and-service-principals) +- [Terraform reference for azuread_application](https://registry.terraform.io/providers/hashicorp/azuread/latest/docs/resources/application) +- [Terraform reference for azuread_application_federated_identity_credential](https://registry.terraform.io/providers/hashicorp/azuread/latest/docs/resources/application_federated_identity_credential) +- [Terraform reference for azurerm_role_assignment](https://registry.terraform.io/providers/hashicorp/azurerm/latest/docs/resources/role_assignment) + +## Support + +For issues, questions, or contributions related to this module, please visit the [repository's issue tracker](https://github.com/prefapp/tfm/issues). \ No newline at end of file diff --git a/modules/azure-oidc/docs/header.md b/modules/azure-oidc/docs/header.md new file mode 100644 index 000000000..d30e0ad5d --- /dev/null +++ b/modules/azure-oidc/docs/header.md @@ -0,0 +1,98 @@ +# Azure OIDC Terraform Module + +## Overview + +This Terraform module creates Azure AD applications, service principals, and role assignments for each application defined in the input data file. It supports federated credentials for GitHub Actions and other issuers. + +> Note: Not defining a scope in an application is equivalent to defining the scope of the subscription. + +## Main features +- Create multiple Azure AD applications and service principals. +- Assign custom roles and scopes to each application. +- Add federated credentials for GitHub Actions or custom issuers. +- Realistic configuration example. + +## Complete usage example + +### Module usage +```hcl +module "github-oidc" { + source = "git::https://github.com/prefapp/tfm.git//modules/azure-oidc?ref=" + data = yamldecode(file("")) +} +``` + +### Example data file +```yaml +applications: + - name: app + roles: + - role1 + - role2 + scope: + - scope1 + - scope2 + federated_credentials: + - subject: "subject_claim_foo:my_repo_foo" + issuer: "issuer_foo" + - subject: "subject_claim_bar:my_repo_bar" + issuer: "issuer_bar" + - name: app2 + roles: + - role1 + federated_credentials: + - subject: "my_repo_foo_foo" + issuer: "issuer_foo_foo" +``` + +#### Realistic example +```yaml +app_registrations: + - name: service_repositories + roles: + - AcrPush + - AcrPull + scope: + - "/subscriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/resourceGroups/foo/providers/Microsoft.ContainerRegistry/registries/foo-registries" + - "/subscriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/resourceGroups/bar/providers/Microsoft.ContainerRegistry/registries/bar-registries" + federated_credentials: + - subject: "repository_owner:prefapp" + issuer: "https://token.actions.githubusercontent.com" + - name: state_repositorie + roles: + - AcrPush + scope: + - "/subscriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/resourceGroups/foo/providers/Microsoft.ContainerRegistry/registries/foo-registries" + federated_credentials: + - subject: "repository_owner:prefapp" + issuer: "https://token.actions.githubusercontent.com" + - name: infra_repositorie + roles: + - Contributor + federated_credentials: + - subject: "my_repo_foo" + issuer: "issuer_foo" + - subject: "my_repo_bar" + issuer: "issuer_bar" + # scope: + # - "/subscriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" # This is similar to not putting scope +``` + +## Notes +- If you do not define a scope, the subscription scope will be used by default. +- Federated credentials support GitHub Actions and custom issuers. +- Each application can have multiple roles, scopes, and federated credentials. + +## File structure + +``` +. +├── main.tf +├── variables.tf +├── outputs.tf +├── README.md +├── CHANGELOG.md +└── docs/ + ├── header.md + └── footer.md +``` \ No newline at end of file From 9803374c8b24abd98335bb48d6f092b99aa66571 Mon Sep 17 00:00:00 2001 From: "pablo.sanchez" Date: Tue, 10 Feb 2026 10:12:15 +0100 Subject: [PATCH 2/2] Update Readme --- modules/azure-oidc/README.md | 110 ----------------------------------- 1 file changed, 110 deletions(-) diff --git a/modules/azure-oidc/README.md b/modules/azure-oidc/README.md index 5bcb9dc5d..875648587 100644 --- a/modules/azure-oidc/README.md +++ b/modules/azure-oidc/README.md @@ -1,113 +1,3 @@ -# Azure OIDC - -## Overview - -This module creates an Azure AD application, service principal and role assignment for each application in the data file. - -> Note: not defining a scope in an application is equivalent to defining the scope of the subscription - -## Requirements - -| Name | Version | -|------|---------| -| [azuread](#requirement\_azuread) | ~> 2.15.0 | -| [azurerm](#requirement\_azurerm) | >3.0.0 | - -## Providers - -| Name | Version | -|------|---------| -| [azuread](#provider\_azuread) | ~> 2.15.0 | -| [azurerm](#provider\_azurerm) | >3.0.0 | - -## Resources - -| Name | Type | -|------|------| -| [azuread_application.gh_oidc_ad_app](https://registry.terraform.io/providers/hashicorp/azuread/latest/docs/resources/application) | resource | -| [azuread_application_federated_identity_credential.gh_oidc_identity_credential](https://registry.terraform.io/providers/hashicorp/azuread/latest/docs/resources/application_federated_identity_credential) | resource | -| [azuread_service_principal.gh_oidc_service_principal](https://registry.terraform.io/providers/hashicorp/azuread/latest/docs/resources/service_principal) | resource | -| [azurerm_role_assignment.gh_oidc_service_role_assignment](https://registry.terraform.io/providers/hashicorp/azurerm/latest/docs/resources/role_assignment) | resource | -| [azuread_client_config.current](https://registry.terraform.io/providers/hashicorp/azuread/latest/docs/data-sources/client_config) | data source | -| [azurerm_subscription.primary](https://registry.terraform.io/providers/hashicorp/azurerm/latest/docs/data-sources/subscription) | data source | - -## Usage - -### Set a module - -```terraform -module "githuib-oidc" { - source = "git::https://github.com/prefapp/tfm.git//modules/azure-oidc?ref=" - data = yamldecode(file("" -} -``` - -#### Example - -```terraform -module "githuib-oidc" { - source = "git::https://github.com/prefapp/tfm.git//modules/azure-oidc?ref=v1.2.3" - data = yamldecode(file("github_oidc.yaml") -``` - -### Set a data file - -```yaml -applications: - - name: app - roles: - - role1 - - role2 - scope: - - scope1 - - scope2 - federated_credentials: - - subject: "subject_claim_foo:my_repo_foo" - issuer: "issuer_foo" - - subject: "subject_claim_bar:my_repo_bar" - issuer: "issuer_bar" - - name: app2 - roles: - - role1 - federated_credentials: - - subject: "my_repo_foo_foo" - issuer: "issuer_foo_foo" -``` - -#### Example - -```yaml -app_registrations: - - name: service_repositories - roles: - - AcrPush - - AcrPull - scope: - - "/subscriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/resourceGroups/foo/providers/Microsoft.ContainerRegistry/registries/foo-registries" - - "/subscriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/resourceGroups/bar/providers/Microsoft.ContainerRegistry/registries/bar-registries" - federated_credentials: - - subject: "repository_owner:prefapp" - issuer: "https://token.actions.githubusercontent.com" - - name: state_repositorie - roles: - - AcrPush - scope: - - "/subscriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/resourceGroups/foo/providers/Microsoft.ContainerRegistry/registries/foo-registries" - federated_credentials: - - subject: "repository_owner:prefapp" - issuer: "https://token.actions.githubusercontent.com" - - name: infra_repositorie - roles: - - Contributor - federated_credentials: - - subject: "my_repo_foo" - issuer: "issuer_foo" - - subject: "my_repo_bar" - issuer: "issuer_bar" - # scope: - # - "/subscriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" # This is similar to not putting scope -``` - # Azure OIDC Terraform Module