Merge pull request #19 from oracle-quickstart/release-0.1.7

Release 0.1.7
oci-landing-zones · Nov 1, 2023 · 7775ac3 · 7775ac3
2 parents 65ac9be + 68237aa
commit 7775ac3
Show file tree

Hide file tree

Showing 37 changed files with 1,289 additions and 26 deletions.
diff --git a/README.md b/README.md
@@ -9,6 +9,7 @@ The following modules are available:
 - [Policies](./policies/)
 - [Groups](./groups/)
 - [Dynamic Groups](./dynamic-groups/)
+- [Identity Domains](./identity-domains/)
 
 Within each module you find an *examples* folder. Each example is a fully runnable Terraform configuration that you can quickly test and put to use by modifying the input data according to your own needs.  
 
@@ -22,6 +23,7 @@ This repository is part of a broader collection of repositories containing modul
 - [Governance](https://github.com/oracle-quickstart/terraform-oci-cis-landing-zone-governance)
 - [Security](https://github.com/oracle-quickstart/terraform-oci-cis-landing-zone-security)
 - [Observability & Monitoring](https://github.com/oracle-quickstart/terraform-oci-cis-landing-zone-observability)
+- [Secure Workloads](https://github.com/oracle-quickstart/terraform-oci-secure-workloads)
 
 The modules in this collection are designed for flexibility, are straightforward to use, and enforce CIS OCI Foundations Benchmark recommendations when possible.
 

diff --git a/RELEASE-NOTES.md b/RELEASE-NOTES.md
@@ -1,3 +1,12 @@
+# November 01, 2023 Release Notes - 0.1.7
+## New
+1. Identity Domains module, supporting identity domains, groups, and dynamic groups. 
+2. Groups and dynamic groups can be created in existing identity domains.
+
+## Updates
+### Policy Module
+1. Multiple intents can be declared for a specific compartment through *cislz-cmp-type* attribute. This configures the compartment (through the creation of necessary policy grants) to host resources that can be managed by different groups.
+
 # October 06, 2023 Release Notes - 0.1.6
 
 ## Updates

diff --git a/identity-domains/README.md b/identity-domains/README.md
@@ -0,0 +1,151 @@
+# CIS OCI Landing Zone Identity Domains Module
+
+![Landing Zone logo](../landing_zone_300.png)
+
+This module manages Identity and Access Management (IAM) Identity Domains, Identity Domain Groups and Identity Domain Dynamic Groups in Oracle Cloud Infrastructure (OCI) based on maps of objects. Identity Domains are a fundamental construct in OCI IAM, they represent a user a group population and its associated configurations and security settings (such as Federation, MFA).
+
+Check [module specification](./SPEC.md) for a full description of module requirements, supported variables, managed resources and outputs.
+
+Check the [examples](./examples/) folder for actual module usage.
+
+- [Requirements](#requirements)
+- [How to Invoke the Module](#invoke)
+- [Module Functioning](#functioning)
+- [Related Documentation](#related)
+- [Known Issues](#issues)
+
+## <a name="requirements">Requirements</a>
+
+### IAM Permissions
+
+This module requires the following OCI IAM permission:
+```
+Allow group <group> to manage domains in tenancy
+```
+### Terraform Version < 1.3.x and Optional Object Type Attributes
+This module relies on [Terraform Optional Object Type Attributes feature](https://developer.hashicorp.com/terraform/language/expressions/type-constraints#optional-object-type-attributes), which is experimental from Terraform 0.14.x to 1.2.x. It shortens the amount of input values in complex object types, by having Terraform automatically inserting a default value for any missing optional attributes. The feature has been promoted and it is no longer experimental in Terraform 1.3.x.
+
+**As is, this module can only be used with Terraform versions up to 1.2.x**, because it can be consumed by other modules via [OCI Resource Manager service](https://docs.oracle.com/en-us/iaas/Content/ResourceManager/home.htm), that still does not support Terraform 1.3.x.
+
+Upon running *terraform plan* with Terraform versions prior to 1.3.x, Terraform displays the following warning:
+```
+Warning: Experimental feature "module_variable_optional_attrs" is active
+```
+
+Note the warning is harmless. The code has been tested with Terraform 1.3.x and the implementation is fully compatible.
+
+If you really want to use Terraform 1.3.x, in [providers.tf](./providers.tf):
+1. Change the terraform version requirement to:
+```
+required_version = ">= 1.3.0"
+```
+2. Remove the line:
+```
+experiments = [module_variable_optional_attrs]
+```
+
+## <a name="invoke">How to Invoke the Module</a>
+
+Terraform modules can be invoked locally or remotely. 
+
+For invoking the module locally, just set the module *source* attribute to the module file path (relative path works). The following example assumes the module is two folders up in the file system.
+```
+
+module "identity_domains" {
+  source       = "../../"
+  tenancy_ocid = var.tenancy_ocid
+  identity_domains_configuration                = var.identity_domains_configuration
+  identity_domain_groups_configuration          = var.identity_domain_groups_configuration
+  identity_domain_dynamic_groups_configuration  = var.identity_domain_dynamic_groups_configuration
+}
+```
+
+For invoking the module remotely, set the module *source* attribute to the groups module folder in this repository, as shown:
+```
+module "identity_domains" {
+  source = "github.com/oracle-quickstart/terraform-oci-cis-landing-zone-iam/identity-domains"
+  tenancy_id                                    = var.tenancy_id
+  identity_domains_configuration                = var.identity_domains_configuration
+  identity_domain_groups_configuration          = var.identity_domain_groups_configuration
+  identity_domain_dynamic_groups_configuration  = var.identity_domain_dynamic_groups_configuration
+}
+```
+For referring to a specific module version, append *ref=\<version\>* to the *source* attribute value, as in:
+```
+  source = "github.com/oracle-quickstart/terraform-oci-cis-landing-zone-iam//identity-domains?ref=v0.1.0"
+```
+
+## <a name="functioning">Module Functioning</a>
+
+The module defines three top-level input variables named *identity_domains_configuration*, *identity_domain_groups_configuration*, and *identity_domain_dynamic_groups_configuration*, for identity domains related attributes. A fourth top-level input variable, *compartments_dependency*, is used for bringing in externally managed compartments into identity domains configuration. See [External Dependencies](#extdep) section.
+
+## Defining Identity Domains
+Use *identity_domains_configuration* attribute. It supports the following attributes:
+
+  - **default_compartment_id**: (Optional) defines the compartment for all identity domains, unless overriden by *compartment_id* attribute within each identity domain.  This attribute is overloaded: it can be either a compartment OCID or a reference (a key) to the compartment OCID. *tenancy_ocid* is used if undefined. See [External Dependencies](#extdep) section.
+  - **default_defined_tags**: (Optional) defined tags to apply to all resources, unless overriden by *defined_tags* attribute within each resource.
+  - **default_freeform_tags**: (Optional) freeform tags to apply to all resources, unless overriden by *freeform_tags* attribute within each resource.
+  - **identity_domains**: (Optional) the map of objects that defines the identity domains, where each object corresponds to an identity domain resource.
+    - **compartment_id**:  (Optional) The compartment for the identity domain. This attribute is overloaded: it can be either a compartment OCID or a reference (a key) to the compartment OCID. *default_compartment_id* is used if undefined. See [External Dependencies](#extdep).            
+    - **display_name**:  (Required) The mutable display name for the identity domain.              
+    - **description**:  (Required) The description of the identity domain.              
+    - **home_region**:  (Required) The region name of the identity domain. The tenancy home region name is used if undefined.  Example: us-ashburn-1
+    - **license_type**: (Required) The license type of the identity domain.  Examples: free, oracle-apps-premium, premium, external-user.             
+    - **admin_email**:  (Optional) The email address of the identity domain administrator.               
+    - **admin_first_name**: (Optional) The first name of the identity domain administrator.      
+    - **admin_last_name**: (Optional) The last name of the identity domain administrator.              
+    - **admin_user_name**: (Optional) The username for the identity domain administrator.             
+    - **is_hidden_on_login**:  (Optional) Indicates whether the identity domain is hidden on login screen or not.  Example: true   
+    - **is_notification_bypassed**:  Indicates if admin user created in the Identity Domain would like to receive notification like welcome email or not. Required field only if admin information is provided, otherwise optional.  
+    - **is_primary_email_required**: (Optional) Indicates whether users in the domain are required to have a primary email address or not.  Example: true
+    - **defined_tags**: (Optional) defined tags to apply to the identity domain. *default_defined_tags* is used if undefined.             
+    - **freeform_tags**:  (Optional) free tags to apply to the identity domain. *default_freeform_tags* is used if undefined.       
+
+## Defining Identity Domain Groups
+Use *identity_domain_groups_configuration* attribute. It supports the following attributes:
+
+  - **default_identity_domain_id**: (Optional) defines the identity domain for all groups, unless overriden by *identity_domain_id* attribute within each group.  This attribute is overloaded: it can be either an existing identity domain OCID (if provisioning the group in an existing identity domain) or the identity domain reference (key) in identity_domains map.
+  - **default_defined_tags**: (Optional) defined tags to apply to all resources, unless overriden by *defined_tags* attribute within each resource.
+  - **default_freeform_tags**: (Optional) freeform tags to apply to all resources, unless overriden by *freeform_tags* attribute within each resource.     
+  - **groups**: (Optional) the map of objects that defines groups of users, where each object corresponds to a group resource.
+    - **identity_domain_id**: (Optional) The identity domain for the group. This attribute is overloaded: it can be either an existing identity domain OCID (if provisioning the group in an existing identity domain) or the identity domain reference (key) in identity_domains map.          
+    - **name**:  (Required) The display name of the group.                     
+    - **description**: (Optional) The description of the group.             
+    - **requestable**: (Optional) Flag controlling whether group membership can be requested by users through self service console.  Example: true           
+    - **members**: (Optional)  List of existing user names to assign to the group.                  
+    - **defined_tags**: (Optional) defined tags to apply to the group. *default_defined_tags* is used if undefined.             
+    - **freeform_tags**: (Optional) free tags to apply to the group. *default_freeform_tags* is used if undefined.     
+
+## Defining Identity Domain Dynamic Groups
+Use *identity_domain_dynamic_groups_configuration* attribute. It supports the following attributes:
+
+  - **default_identity_domain_id**: (Optional) defines the identity domain for all dynamic groups, unless overriden by *identity_domain_id* attribute within each dynamic group.  This attribute is overloaded: it can be either an identity domain OCID or a reference (a key) to the identity domain OCID.
+  - **default_defined_tags**: (Optional) defined tags to apply to all resources, unless overriden by *defined_tags* attribute within each resource.
+  - **default_freeform_tags**: (Optional) freeform tags to apply to all resources, unless overriden by *freeform_tags* attribute within each resource.      
+  - **dynamic_groups**: (Optional) the map of objects that defines dynamic groups, where each object corresponds to a dynamic group resource.
+    - **identity_domain_id**: (Optional) The identity domain for the dynamic group. This attribute is overloaded: it can be either an existing identity domain OCID (if provisioning the dynamic group in an existing identity domain) or the identity domain reference (key) in identity_domains map.    
+    - **name**:  (Required) The display name of the dynamic group.                      
+    - **description**: (Optional) The description of the dynamic group.               
+    - **matching_rule**: (Required)  An expression that defines the principals assigned to the dynamic group resource.             
+    - **defined_tags**:  (Optional) defined tags to apply to the group. *default_defined_tags* is used if undefined.              
+    - **freeform_tags**: (Optional) free tags to apply to the group. *default_freeform_tags* is used if undefined.             
+
+Check the [examples](./examples/) folder for module usage. Specifically, see [vision](./examples/vision/README.md) example to deploy two identity domains including groups and dynamic_groups.
+
+### <a name="extdep">External Dependencies</a>
+
+An optional feature, external dependencies are resources managed elsewhere that resources managed by this module may depend on. The following dependencies are supported:
+
+- **compartments_dependency**: A map of objects containing the externally managed compartments this module may depend on. All map objects must have the same type and must contain at least an *id* attribute with the compartment OCID. This mechanism allows for the usage of referring keys (instead of OCIDs) in identity domains *default_compartment_id* and *compartment_id* attributes. The module replaces the keys by the OCIDs provided within *compartments_dependency* map. Contents of *compartments_dependency is typically the output of a [Compartments module](../compartments/) client.
+
+## <a name="related">Related Documentation</a>
+- [Managing Identity Domains](https://docs.oracle.com/en-us/iaas/Content/Identity/domains/overview.htm)
+- [Identity Domains in Terraform OCI Provider](https://registry.terraform.io/providers/oracle/oci/latest/docs/resources/identity_domain)
+
+## <a name="issues">Known Issues</a>
+1. Terraform will not destroy identity domains. In order do destroy an identity domain, first run ```terraform destroy``` to destroy contained resources (groups, dynamic groups...). The error ```"Error: 412-PreConditionFailed, Cannot perform DELETE_DOMAIN operation on Domain with Status CREATED"``` is returned.  Then deactivate and delete the identity domain(s) using the OCI console or OCI CLI, as in:
+```
+  oci iam domain deactivate --domain-id <identity domain OCID>
+  oci iam domain delete --domain-id <identity domain OCID>
+```
+
diff --git a/identity-domains/SPEC.md b/identity-domains/SPEC.md
@@ -0,0 +1,47 @@
+## Requirements
+
+| Name | Version |
+|------|---------|
+| <a name="requirement_terraform"></a> [terraform](#requirement\_terraform) | < 1.3.0 |
+
+## Providers
+
+| Name | Version |
+|------|---------|
+| <a name="provider_oci"></a> [oci](#provider\_oci) | n/a |
+
+## Modules
+
+No modules.
+
+## Resources
+
+| Name | Type |
+|------|------|
+| [oci_identity_domain.these](https://registry.terraform.io/providers/oracle/oci/latest/docs/resources/identity_domain) | resource |
+| [oci_identity_domains_dynamic_resource_group.these](https://registry.terraform.io/providers/oracle/oci/latest/docs/resources/identity_domains_dynamic_resource_group) | resource |
+| [oci_identity_domains_group.these](https://registry.terraform.io/providers/oracle/oci/latest/docs/resources/identity_domains_group) | resource |
+| [oci_identity_domain.dyngrp_domain](https://registry.terraform.io/providers/oracle/oci/latest/docs/data-sources/identity_domain) | data source |
+| [oci_identity_domain.grp_domain](https://registry.terraform.io/providers/oracle/oci/latest/docs/data-sources/identity_domain) | data source |
+| [oci_identity_domains_users.these](https://registry.terraform.io/providers/oracle/oci/latest/docs/data-sources/identity_domains_users) | data source |
+| [oci_identity_regions.these](https://registry.terraform.io/providers/oracle/oci/latest/docs/data-sources/identity_regions) | data source |
+| [oci_identity_tenancy.this](https://registry.terraform.io/providers/oracle/oci/latest/docs/data-sources/identity_tenancy) | data source |
+
+## Inputs
+
+| Name | Description | Type | Default | Required |
+|------|-------------|------|---------|:--------:|
+| <a name="input_compartments_dependency"></a> [compartments\_dependency](#input\_compartments\_dependency) | A map of objects containing the externally managed compartments this module may depend on. All map objects must have the same type and must contain at least an 'id' attribute (representing the compartment OCID) of string type. | `map(any)` | `null` | no |
+| <a name="input_identity_domain_dynamic_groups_configuration"></a> [identity\_domain\_dynamic\_groups\_configuration](#input\_identity\_domain\_dynamic\_groups\_configuration) | The identity domain dynamic groups configuration. | <pre>object({<br>    default_identity_domain_id  = optional(string)<br>    default_defined_tags        = optional(map(string))<br>    default_freeform_tags       = optional(map(string))<br>    dynamic_groups = map(object({<br>      identity_domain_id        = optional(string),<br>      name                      = string,<br>      description               = optional(string),<br>      matching_rule             = string,<br>      defined_tags              = optional(map(string)),<br>      freeform_tags             = optional(map(string))<br>    }))<br>  })</pre> | `null` | no |
+| <a name="input_identity_domain_groups_configuration"></a> [identity\_domain\_groups\_configuration](#input\_identity\_domain\_groups\_configuration) | The identity domain groups configuration. | <pre>object({<br>    default_identity_domain_id  = optional(string)<br>    default_defined_tags        = optional(map(string))<br>    default_freeform_tags       = optional(map(string))<br>    groups = map(object({<br>      identity_domain_id        = optional(string),<br>      name                      = string,<br>      description               = optional(string),<br>      requestable               = optional(bool),<br>      members                   = optional(list(string)),<br>      defined_tags              = optional(map(string)),<br>      freeform_tags             = optional(map(string))<br>    }))<br>  })</pre> | `null` | no |
+| <a name="input_identity_domains_configuration"></a> [identity\_domains\_configuration](#input\_identity\_domains\_configuration) | The identity domains configuration. | <pre>object({<br>    default_compartment_id = optional(string)<br>    default_defined_tags   = optional(map(string))<br>    default_freeform_tags  = optional(map(string))<br>    identity_domains = map(object({<br>      compartment_id            = optional(string),<br>      display_name              = string,<br>      description               = string,<br>      home_region               = optional(string),<br>      license_type              = string,<br>      admin_email               = optional(string),<br>      admin_first_name          = optional(string),<br>      admin_last_name           = optional(string),<br>      admin_user_name           = optional(string),<br>      is_hidden_on_login        = optional(bool),<br>      is_notification_bypassed  = optional(bool),<br>      is_primary_email_required = optional(bool),<br>      defined_tags              = optional(map(string)),<br>      freeform_tags             = optional(map(string))<br>    }))<br>  })</pre> | `null` | no |
+| <a name="input_module_name"></a> [module\_name](#input\_module\_name) | The module name. | `string` | `"iam-identity-domains"` | no |
+| <a name="input_tenancy_ocid"></a> [tenancy\_ocid](#input\_tenancy\_ocid) | The OCID of the tenancy. | `string` | n/a | yes |
+
+## Outputs
+
+| Name | Description |
+|------|-------------|
+| <a name="output_identity_domain_dynamic_groups"></a> [identity\_domain\_dynamic\_groups](#output\_identity\_domain\_dynamic\_groups) | The identity domain groups |
+| <a name="output_identity_domain_groups"></a> [identity\_domain\_groups](#output\_identity\_domain\_groups) | The identity domain groups |
+| <a name="output_identity_domains"></a> [identity\_domains](#output\_identity\_domains) | The identity domains. |