diff --git a/modules/azure-application/README.md b/modules/azure-application/README.md index d787b678e..69f0178a5 100644 --- a/modules/azure-application/README.md +++ b/modules/azure-application/README.md @@ -1,9 +1,70 @@ + +# Azure Application Registration Terraform Module + +## Overview + +Este módulo de Terraform permite crear y gestionar un registro de aplicación en Azure Active Directory (Azure AD), incluyendo: +- Creación de la aplicación y service principal. +- Asignación de roles y permisos (incluyendo Microsoft Graph). +- Configuración de credenciales federadas y secretos. +- Soporte para redirecciones y miembros. +- Integración opcional con Azure Key Vault para almacenar secretos. + +## Características principales +- Registro de aplicación y service principal en Azure AD. +- Asignación de roles personalizados y de Microsoft Graph. +- Soporte para credenciales federadas (OIDC, GitHub Actions, etc). +- Gestión de secretos con rotación y almacenamiento seguro en Key Vault. +- Configuración flexible de redirecciones y miembros. + +## Ejemplo básico de uso + +```hcl +module "azure_application" { + source = "./modules/azure-application" + name = "my-app" + members = ["user1@dominio.com", "user2@dominio.com"] + msgraph_roles = [ + { + id = "User.Read.All" + delegated = true + } + ] + redirects = [{ + platform = "web" + redirect_uris = ["https://myapp.com/auth/callback"] + }] + client_secret = { + enabled = true + rotation_days = 90 + keyvault = { + id = azurerm_key_vault.example.id + key_name = "my-app-secret" + } + } +} +``` + +## Estructura de archivos + +``` +. +├── main.tf +├── variables.tf +├── outputs.tf +├── versions.tf +├── README.md +├── CHANGELOG.md +└── docs/ + ├── header.md + └── footer.md +``` + ## Requirements | Name | Version | |------|---------| | [terraform](#requirement\_terraform) | >= 1.7.0 | -| [azapi](#requirement\_azapi) | ~> 2.3.0 | | [azuread](#requirement\_azuread) | ~> 3.3.0 | | [azurerm](#requirement\_azurerm) | ~> 4.16.0 | @@ -11,9 +72,9 @@ | Name | Version | |------|---------| -| [azuread](#provider\_azuread) | 3.3.0 | -| [azurerm](#provider\_azurerm) | 4.16.0 | -| [time](#provider\_time) | 0.13.1 | +| [azuread](#provider\_azuread) | ~> 3.3.0 | +| [azurerm](#provider\_azurerm) | ~> 4.16.0 | +| [time](#provider\_time) | n/a | ## Modules @@ -45,7 +106,7 @@ No modules. | [extra\_role\_assignments](#input\_extra\_role\_assignments) | The list of extra role assignments to be added to the Azure App Registration. |
list(object({
role_definition_name = string
scope = string
})) | `[]` | no |
| [federated\_credentials](#input\_federated\_credentials) | The federated credentials configuration for the Azure App Registration. | list(object({
display_name = string
audiences = list(string)
issuer = string
subject = string
description = optional(string)
})) | `[]` | no |
| [members](#input\_members) | The list of members to be added to the Azure App Registration. | `list(string)` | n/a | yes |
-| [msgraph\_roles](#input\_msgraph\_roles) | The list of Microsoft Graph roles to be assigned to the Azure App Registration. e.g. User.Read.All | `list(string)` | n/a | yes |
+| [msgraph\_roles](#input\_msgraph\_roles) | The list of Microsoft Graph roles to be assigned to the Azure App Registration. Each role includes a name and whether it is delegated. | list(object({
id = string
delegated = bool
})) | n/a | yes |
| [name](#input\_name) | The name of the Azure App Registration. | `string` | n/a | yes |
| [redirects](#input\_redirects) | The redirect configuration for the Azure App Registration. | list(object({
platform = string
redirect_uris = list(string)
})) | n/a | yes |
@@ -55,3 +116,23 @@ No modules.
|------|-------------|
| [application\_client\_id](#output\_application\_client\_id) | The client ID of the Azure application |
| [application\_object\_id](#output\_application\_object\_id) | The object ID of the Azure application |
+
+---
+
+## Examples
+
+For detailed examples, refer to the [module examples](https://github.com/prefapp/tfm/tree/main/modules/azure-application/_examples):
+
+- [basic](https://github.com/prefapp/tfm/tree/main/modules/azure-application/_examples/basic) - Azure AD App Registration with members, redirects, Microsoft Graph roles and client secret stored in Key Vault.
+
+## Recursos adicionales
+
+- [Azure Active Directory App Registration](https://learn.microsoft.com/en-us/azure/active-directory/develop/quickstart-register-app)
+- [Proveedor Terraform AzureAD](https://registry.terraform.io/providers/hashicorp/azuread/latest/docs/resources/application)
+- [Proveedor Terraform AzureRM](https://registry.terraform.io/providers/hashicorp/azurerm/latest/docs)
+- [Documentación oficial de Terraform](https://www.terraform.io/docs)
+
+## Soporte
+
+Para dudas, incidencias o contribuciones, utiliza el issue tracker del repositorio: [https://github.com/prefapp/tfm/issues](https://github.com/prefapp/tfm/issues)
+
\ No newline at end of file
diff --git a/modules/azure-application/_examples/basic/example.tf b/modules/azure-application/_examples/basic/example.tf
new file mode 100644
index 000000000..33c1cb0c7
--- /dev/null
+++ b/modules/azure-application/_examples/basic/example.tf
@@ -0,0 +1,34 @@
+// Basic example: Azure AD Application Registration using the module
+
+module "azure_application" {
+ source = "../../"
+
+ name = "my-app"
+ members = [
+ "user1@contoso.com",
+ "user2@contoso.com",
+ ]
+
+ msgraph_roles = [
+ {
+ id = "role-id-user-read-all"
+ delegated = true
+ }
+ ]
+
+ redirects = [
+ {
+ platform = "Web"
+ redirect_uris = ["https://myapp.com/auth/callback"]
+ }
+ ]
+
+ client_secret = {
+ enabled = true
+ rotation_days = 90
+ keyvault = {
+ id = "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/example-rg/providers/Microsoft.KeyVault/vaults/example-kv"
+ key_name = "my-app-secret"
+ }
+ }
+}
\ No newline at end of file
diff --git a/modules/azure-application/_examples/basic/example.yaml b/modules/azure-application/_examples/basic/example.yaml
new file mode 100644
index 000000000..7601a38ea
--- /dev/null
+++ b/modules/azure-application/_examples/basic/example.yaml
@@ -0,0 +1,23 @@
+# Basic example values for Azure Application Registration module
+
+name: my-app
+
+members:
+ - user1@contoso.com
+ - user2@contoso.com
+
+msgraph_roles:
+ - id: role-id-user-read-all
+ delegated: true
+
+redirects:
+ - platform: Web
+ redirect_uris:
+ - https://myapp.com/auth/callback
+
+client_secret:
+ enabled: true
+ rotation_days: 90
+ keyvault:
+ id: /subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/example-rg/providers/Microsoft.KeyVault/vaults/example-kv
+ key_name: my-app-secret
\ No newline at end of file
diff --git a/modules/azure-application/docs/footer.md b/modules/azure-application/docs/footer.md
new file mode 100644
index 000000000..a5ac5a636
--- /dev/null
+++ b/modules/azure-application/docs/footer.md
@@ -0,0 +1,18 @@
+---
+
+## Examples
+
+For detailed examples, refer to the [module examples](https://github.com/prefapp/tfm/tree/main/modules/azure-application/_examples):
+
+- [basic](https://github.com/prefapp/tfm/tree/main/modules/azure-application/_examples/basic) - Azure AD App Registration with members, redirects, Microsoft Graph roles and client secret stored in Key Vault.
+
+## Recursos adicionales
+
+- [Azure Active Directory App Registration](https://learn.microsoft.com/en-us/azure/active-directory/develop/quickstart-register-app)
+- [Proveedor Terraform AzureAD](https://registry.terraform.io/providers/hashicorp/azuread/latest/docs/resources/application)
+- [Proveedor Terraform AzureRM](https://registry.terraform.io/providers/hashicorp/azurerm/latest/docs)
+- [Documentación oficial de Terraform](https://www.terraform.io/docs)
+
+## Soporte
+
+Para dudas, incidencias o contribuciones, utiliza el issue tracker del repositorio: [https://github.com/prefapp/tfm/issues](https://github.com/prefapp/tfm/issues)
diff --git a/modules/azure-application/docs/header.md b/modules/azure-application/docs/header.md
new file mode 100644
index 000000000..7b24de5d2
--- /dev/null
+++ b/modules/azure-application/docs/header.md
@@ -0,0 +1,60 @@
+# Azure Application Registration Terraform Module
+
+## Overview
+
+Este módulo de Terraform permite crear y gestionar un registro de aplicación en Azure Active Directory (Azure AD), incluyendo:
+- Creación de la aplicación y service principal.
+- Asignación de roles y permisos (incluyendo Microsoft Graph).
+- Configuración de credenciales federadas y secretos.
+- Soporte para redirecciones y miembros.
+- Integración opcional con Azure Key Vault para almacenar secretos.
+
+## Características principales
+- Registro de aplicación y service principal en Azure AD.
+- Asignación de roles personalizados y de Microsoft Graph.
+- Soporte para credenciales federadas (OIDC, GitHub Actions, etc).
+- Gestión de secretos con rotación y almacenamiento seguro en Key Vault.
+- Configuración flexible de redirecciones y miembros.
+
+## Ejemplo básico de uso
+
+```hcl
+module "azure_application" {
+ source = "./modules/azure-application"
+ name = "my-app"
+ members = ["user1@dominio.com", "user2@dominio.com"]
+ msgraph_roles = [
+ {
+ id = "User.Read.All"
+ delegated = true
+ }
+ ]
+ redirects = [{
+ platform = "web"
+ redirect_uris = ["https://myapp.com/auth/callback"]
+ }]
+ client_secret = {
+ enabled = true
+ rotation_days = 90
+ keyvault = {
+ id = azurerm_key_vault.example.id
+ key_name = "my-app-secret"
+ }
+ }
+}
+```
+
+## Estructura de archivos
+
+```
+.
+├── main.tf
+├── variables.tf
+├── outputs.tf
+├── versions.tf
+├── README.md
+├── CHANGELOG.md
+└── docs/
+ ├── header.md
+ └── footer.md
+```