feat: Adds users attribute to mongodbatlas_organization(s) singular and plural data source. (#3468)

* Added `users` attribute, modified test and docs.

* Updated doc

* Fixed test

* Added changelog

* Fixed SDK version

* Update docs/data-sources/organization.md

Co-authored-by: Leo Antoli <[email protected]>

* Removed FlattenUsers and related functions from common utility

* Change 3 functions to private visibility

* Added some value checks

* Fixed doc (users attributes to be the same as in the schema)

* Minor changes

* Updated note in docs

* Changed attributes names for consistency and type to TypeSet

* Fix

* Removed TODOs

---------

Co-authored-by: Cristina Sánchez Sánchez <[email protected]>
Co-authored-by: Leo Antoli <[email protected]>

Author: 3 people

.changelog/3468.txt

@@ -0,0 +1,7 @@
+```release-note:enhancement
+data-source/mongodbatlas_organization: Adds `users` attribute
+```
+
+```release-note:enhancement
+data-source/mongodbatlas_organizations: Adds `users` attribute
+```

docs/data-sources/organization.md

@@ -23,6 +23,7 @@ In addition to all arguments above, the following attributes are exported:
 * `name` - Human-readable label that identifies the organization.
 * `id` - Unique 24-hexadecimal digit string that identifies the organization.
 * `is_deleted` - Flag that indicates whether this organization has been deleted.
+* `users`- Returns a list of all pending and active MongoDB Cloud users associated with the specified organization.
 * `api_access_list_required` - (Optional) Flag that indicates whether to require API operations to originate from an IP Address added to the API access list for the specified organization.
 * `multi_factor_auth_required` - (Optional) Flag that indicates whether to require users to set up Multi-Factor Authentication (MFA) before accessing the specified organization. To learn more, see: https://www.mongodb.com/docs/atlas/security-multi-factor-authentication/.
 * `restrict_employee_access` - (Optional) Flag that indicates whether to block MongoDB Support from accessing Atlas infrastructure for any deployment in the specified organization without explicit permission. Once this setting is turned on, you can grant MongoDB Support a 24-hour bypass access to the Atlas deployment to resolve support issues. To learn more, see: https://www.mongodb.com/docs/atlas/security-restrict-support-access/.
@@ -31,6 +32,28 @@ In addition to all arguments above, the following attributes are exported:
 * `skip_default_alerts_settings` - (Optional) Flag that indicates whether to prevent Atlas from automatically creating organization-level alerts not explicitly managed through Terraform. Defaults to `true`.
 
 
+### Users
+* `id` - Unique 24-hexadecimal digit string that identifies the MongoDB Cloud user.
+* `org_membership_status` - String enum that indicates whether the MongoDB Cloud user has a pending invitation to join the organization or they are already active in the organization.
+* `roles` - Organization- and project-level roles assigned to one MongoDB Cloud user within one organization.
+* `team_ids` - List of unique 24-hexadecimal digit strings that identifies the teams to which this MongoDB Cloud user belongs.
+* `username` - Email address that represents the username of the MongoDB Cloud user.
+* `country` - Two-character alphabetical string that identifies the MongoDB Cloud user's geographic location. This parameter uses the ISO 3166-1a2 code format.
+* `invitation_created_at` - Date and time when MongoDB Cloud sent the invitation. MongoDB Cloud represents this timestamp in ISO 8601 format in UTC.
+* `invitation_expires_at` - Date and time when the invitation from MongoDB Cloud expires. MongoDB Cloud represents this timestamp in ISO 8601 format in UTC.
+* `inviter_username` - Username of the MongoDB Cloud user who sent the invitation to join the organization.
+* `created_at` - Date and time when MongoDB Cloud created the current account. This value is in the ISO 8601 timestamp format in UTC.
+* `first_name` - First or given name that belongs to the MongoDB Cloud user.
+* `last_auth` - Date and time when the current account last authenticated. This value is in the ISO 8601 timestamp format in UTC.
+* `last_name` - Last name, family name, or surname that belongs to the MongoDB Cloud user.
+* `mobile_number` - Mobile phone number that belongs to the MongoDB Cloud user.
+
+
+~> **NOTE:** - Users with pending invitations created using [`mongodbatlas_project_invitation`](../resources/project_invitation.md) resource or via the deprecated [Invite One MongoDB Cloud User to Join One Project](https://www.mongodb.com/docs/api/doc/atlas-admin-api-v2/operation/operation-createprojectinvitation) endpoint are excluded (or cannot be managed) with this resource. See  [MongoDB Atlas API]<link-to-resource-API> for details. 
+To manage these users with this resource/data source, refer to our [migration guide]<link-to-migration-guide>.
+
+
+
 ~> **NOTE:** - If you create an organization with our Terraform provider version >=1.30.0, this field is set to `true` by default.<br> - If you have an existing organization created with our Terraform provider version <1.30.0, this field might be `false`, which is the [API default value](https://www.mongodb.com/docs/api/doc/atlas-admin-api-v2/operation/operation-createorganization). To prevent the creation of future default alerts, set this explicitly to `true` using the [`mongodbatlas_organization`](../resources/organization.md) resource.
 
 

docs/data-sources/organizations.md

@@ -28,13 +28,36 @@ data "mongodbatlas_organizations" "test" {
 * `name` - Human-readable label that identifies the organization.
 * `id` - Unique 24-hexadecimal digit string that identifies the organization.
 * `is_deleted` - Flag that indicates whether this organization has been deleted.
+* `users` - Returns list of all pending and active MongoDB Cloud users associated with the specified organization.
 * `api_access_list_required` - (Optional) Flag that indicates whether to require API operations to originate from an IP Address added to the API access list for the specified organization.
 * `multi_factor_auth_required` - (Optional) Flag that indicates whether to require users to set up Multi-Factor Authentication (MFA) before accessing the specified organization. To learn more, see: https://www.mongodb.com/docs/atlas/security-multi-factor-authentication/.
 * `restrict_employee_access` - (Optional) Flag that indicates whether to block MongoDB Support from accessing Atlas infrastructure for any deployment in the specified organization without explicit permission. Once this setting is turned on, you can grant MongoDB Support a 24-hour bypass access to the Atlas deployment to resolve support issues. To learn more, see: https://www.mongodb.com/docs/atlas/security-restrict-support-access/.
 * `gen_ai_features_enabled` - (Optional) Flag that indicates whether this organization has access to generative AI features. This setting only applies to Atlas Commercial and defaults to `true`. With this setting on, Project Owners may be able to enable or disable individual AI features at the project level. To learn more, see https://www.mongodb.com/docs/generative-ai-faq/.
 * `security_contact` - (Optional) String that specifies a single email address for the specified organization to receive security-related notifications. Specifying a security contact does not grant them authorization or access to Atlas for security decisions or approvals.
 * `skip_default_alerts_settings` - (Optional) Flag that indicates whether to prevent Atlas from automatically creating organization-level alerts not explicitly managed through Terraform. Defaults to `true`. 
 
+
+### Users
+* `id` - Unique 24-hexadecimal digit string that identifies the MongoDB Cloud user.
+* `org_membership_status` - String enum that indicates whether the MongoDB Cloud user has a pending invitation to join the organization or they are already active in the organization.
+* `roles` - Organization- and project-level roles assigned to one MongoDB Cloud user within one organization.
+* `teamIds` - List of unique 24-hexadecimal digit strings that identifies the teams to which this MongoDB Cloud user belongs.
+* `username` - Email address that represents the username of the MongoDB Cloud user.
+* `country` - Two-character alphabetical string that identifies the MongoDB Cloud user's geographic location. This parameter uses the ISO 3166-1a2 code format.
+* `invitation_created_at` - Date and time when MongoDB Cloud sent the invitation. MongoDB Cloud represents this timestamp in ISO 8601 format in UTC.
+* `invitation_expires_at` - Date and time when the invitation from MongoDB Cloud expires. MongoDB Cloud represents this timestamp in ISO 8601 format in UTC.
+* `inviter_username` - Username of the MongoDB Cloud user who sent the invitation to join the organization.
+* `created_at` - Date and time when MongoDB Cloud created the current account. This value is in the ISO 8601 timestamp format in UTC.
+* `first_name` - First or given name that belongs to the MongoDB Cloud user.
+* `last_auth` - Date and time when the current account last authenticated. This value is in the ISO 8601 timestamp format in UTC.
+* `last_name` - Last name, family name, or surname that belongs to the MongoDB Cloud user.
+* `mobile_number` - Mobile phone number that belongs to the MongoDB Cloud user.
+
+
+~> **NOTE:** - Users with pending invitations created using [`mongodbatlas_project_invitation`](../resources/project_invitation.md) resource or via the deprecated [Invite One MongoDB Cloud User to Join One Project](https://www.mongodb.com/docs/api/doc/atlas-admin-api-v2/operation/operation-createprojectinvitation) endpoint are excluded (or cannot be managed) with this resource. See  [MongoDB Atlas API]<link-to-resource-API> for details. 
+To manage these users with this resource/data source, refer to our [migration guide]<link-to-migration-guide>.
+
+
 ~> **NOTE:** - If you create an organization with our Terraform provider version >=1.30.0, this field is set to `true` by default.<br> - If you have an existing organization created with our Terraform provider version <1.30.0, this field might be `false`, which is the [API default value](https://www.mongodb.com/docs/api/doc/atlas-admin-api-v2/operation/operation-createorganization). To prevent the creation of future default alerts, set this explicitly to `true` using the [`mongodbatlas_organization`](../resources/organization.md) resource.
 
 

internal/service/organization/data_source_organization.go

@@ -3,14 +3,112 @@ package organization
 import (
 	"context"
 	"fmt"
+	"net/http"
+	"time"
 
 	"github.com/hashicorp/terraform-plugin-sdk/v2/diag"
 	"github.com/hashicorp/terraform-plugin-sdk/v2/helper/schema"
+	"go.mongodb.org/atlas-sdk/v20250312005/admin"
 
 	"github.com/mongodb/terraform-provider-mongodbatlas/internal/common/conversion"
+	"github.com/mongodb/terraform-provider-mongodbatlas/internal/common/dsschema"
 	"github.com/mongodb/terraform-provider-mongodbatlas/internal/config"
 )
 
+var (
+	DSOrgUsersSchema = schema.Schema{
+		Type:     schema.TypeSet,
+		Computed: true,
+		Elem: &schema.Resource{
+			Schema: map[string]*schema.Schema{
+				"id": {
+					Type:     schema.TypeString,
+					Computed: true,
+				},
+				"org_membership_status": {
+					Type:     schema.TypeString,
+					Computed: true,
+				},
+				"roles": {
+					Type:     schema.TypeList,
+					Computed: true,
+					Elem: &schema.Resource{
+						Schema: map[string]*schema.Schema{
+							"org_roles": {
+								Type:     schema.TypeSet,
+								Computed: true,
+								Elem:     &schema.Schema{Type: schema.TypeString},
+							},
+							"project_roles_assignments": {
+								Type:     schema.TypeSet,
+								Computed: true,
+								Elem: &schema.Resource{
+									Schema: map[string]*schema.Schema{
+										"project_id": {
+											Type:     schema.TypeString,
+											Computed: true,
+										},
+										"project_roles": {
+											Type:     schema.TypeSet,
+											Computed: true,
+											Elem:     &schema.Schema{Type: schema.TypeString},
+										},
+									},
+								},
+							},
+						},
+					},
+				},
+				"team_ids": {
+					Type:     schema.TypeList,
+					Computed: true,
+					Elem:     &schema.Schema{Type: schema.TypeString},
+				},
+				"username": {
+					Type:     schema.TypeString,
+					Computed: true,
+				},
+				"invitation_created_at": {
+					Type:     schema.TypeString,
+					Computed: true,
+				},
+				"invitation_expires_at": {
+					Type:     schema.TypeString,
+					Computed: true,
+				},
+				"inviter_username": {
+					Type:     schema.TypeString,
+					Computed: true,
+				},
+				"country": {
+					Type:     schema.TypeString,
+					Computed: true,
+				},
+				"created_at": {
+					Type:     schema.TypeString,
+					Computed: true,
+				},
+				"first_name": {
+					Type:     schema.TypeString,
+					Computed: true,
+				},
+				"last_auth": {
+					Type:     schema.TypeString,
+					Computed: true,
+				},
+				"last_name": {
+					Type:     schema.TypeString,
+					Computed: true,
+				},
+				"mobile_number": {
+					Type:     schema.TypeString,
+					Computed: true,
+				},
+			},
+		},
+	}
+)
+
 func DataSource() *schema.Resource {
 	return &schema.Resource{
 		ReadContext: dataSourceRead,
@@ -43,6 +141,7 @@ func DataSource() *schema.Resource {
 					},
 				},
 			},
+			"users": &DSOrgUsersSchema,
 			"api_access_list_required": {
 				Type:     schema.TypeBool,
 				Computed: true,
@@ -71,6 +170,57 @@ func DataSource() *schema.Resource {
 	}
 }
 
+func flattenUsers(users []admin.OrgUserResponse) []map[string]any {
+	ret := make([]map[string]any, len(users))
+	for i := range users {
+		user := &users[i]
+		ret[i] = map[string]any{
+			"id":                    user.GetId(),
+			"org_membership_status": user.GetOrgMembershipStatus(),
+			"roles":                 flattenUserRoles(user.GetRoles()),
+			"team_ids":              user.GetTeamIds(),
+			"username":              user.GetUsername(),
+			"invitation_created_at": user.GetInvitationCreatedAt().Format(time.RFC3339),
+			"invitation_expires_at": user.GetInvitationExpiresAt().Format(time.RFC3339),
+			"inviter_username":      user.GetInviterUsername(),
+			"country":               user.GetCountry(),
+			"created_at":            user.GetCreatedAt().Format(time.RFC3339),
+			"first_name":            user.GetFirstName(),
+			"last_auth":             user.GetLastAuth().Format(time.RFC3339),
+			"last_name":             user.GetLastName(),
+			"mobile_number":         user.GetMobileNumber(),
+		}
+	}
+	return ret
+}
+
+func flattenUserRoles(roles admin.OrgUserRolesResponse) []map[string]any {
+	ret := make([]map[string]any, 0)
+	roleMap := map[string]any{
+		"org_roles":                 []string{},
+		"project_roles_assignments": []map[string]any{},
+	}
+	if roles.HasOrgRoles() {
+		roleMap["org_roles"] = roles.GetOrgRoles()
+	}
+	if roles.HasGroupRoleAssignments() {
+		roleMap["project_roles_assignments"] = flattenProjectRolesAssignments(roles.GetGroupRoleAssignments())
+	}
+	ret = append(ret, roleMap)
+	return ret
+}
+
+func flattenProjectRolesAssignments(assignments []admin.GroupRoleAssignment) []map[string]any {
+	ret := make([]map[string]any, 0, len(assignments))
+	for _, assignment := range assignments {
+		ret = append(ret, map[string]any{
+			"project_id":    assignment.GetGroupId(),
+			"project_roles": assignment.GetGroupRoles(),
+		})
+	}
+	return ret
+}
+
 func dataSourceRead(ctx context.Context, d *schema.ResourceData, meta any) diag.Diagnostics {
 	conn := meta.(*config.MongoDBClient).AtlasV2
 	orgID := d.Get("org_id").(string)
@@ -97,6 +247,14 @@ func dataSourceRead(ctx context.Context, d *schema.ResourceData, meta any) diag.
 		return diag.FromErr(fmt.Errorf("error setting `is_deleted`: %s", err))
 	}
 
+	users, err := listAllOrganizationUsers(ctx, orgID, conn)
+	if err != nil {
+		return diag.FromErr(fmt.Errorf("error getting organization users: %s", err))
+	}
+	if err := d.Set("users", flattenUsers(users)); err != nil {
+		return diag.FromErr(fmt.Errorf("error setting `users`: %s", err))
+	}
+
 	settings, _, err := conn.OrganizationsApi.GetOrganizationSettings(ctx, orgID).Execute()
 	if err != nil {
 		return diag.FromErr(fmt.Errorf("error getting organization settings: %s", err))
@@ -121,3 +279,11 @@ func dataSourceRead(ctx context.Context, d *schema.ResourceData, meta any) diag.
 
 	return nil
 }
+
+func listAllOrganizationUsers(ctx context.Context, orgID string, conn *admin.APIClient) ([]admin.OrgUserResponse, error) {
+	return dsschema.AllPages(ctx, func(ctx context.Context, pageNum int) (dsschema.PaginateResponse[admin.OrgUserResponse], *http.Response, error) {
+		request := conn.MongoDBCloudUsersApi.ListOrganizationUsers(ctx, orgID)
+		request = request.PageNum(pageNum)
+		return request.Execute()
+	})
+}

internal/service/organization/data_source_organizations.go

@@ -63,6 +63,7 @@ func PluralDataSource() *schema.Resource {
 								},
 							},
 						},
+						"users": &DSOrgUsersSchema,
 						"api_access_list_required": {
 							Type:     schema.TypeBool,
 							Computed: true,
@@ -138,16 +139,21 @@ func flattenOrganizations(ctx context.Context, conn *admin.APIClient, organizati
 	results = make([]map[string]any, len(organizations))
 
 	for k, organization := range organizations {
+		users, err := listAllOrganizationUsers(ctx, *organization.Id, conn)
+		if err != nil {
+			return nil, fmt.Errorf("error getting organization users (orgID: %s, name: %s): %s", organization.GetId(), organization.GetName(), err)
+		}
 		settings, _, err := conn.OrganizationsApi.GetOrganizationSettings(ctx, *organization.Id).Execute()
 		if err != nil {
-			return nil, fmt.Errorf("error getting organization settings (orgID: %s, org Name: %s): %s", organization.GetId(), organization.GetName(), err)
+			return nil, fmt.Errorf("error getting organization settings (orgID: %s, name: %s): %s", organization.GetId(), organization.GetName(), err)
 		}
 		results[k] = map[string]any{
 			"id":                           organization.Id,
 			"name":                         organization.Name,
 			"skip_default_alerts_settings": organization.SkipDefaultAlertsSettings,
 			"is_deleted":                   organization.IsDeleted,
 			"links":                        conversion.FlattenLinks(organization.GetLinks()),
+			"users":                        flattenUsers(users),
 			"api_access_list_required":     settings.ApiAccessListRequired,
 			"multi_factor_auth_required":   settings.MultiFactorAuthRequired,
 			"restrict_employee_access":     settings.RestrictEmployeeAccess,

internal/service/organization/resource_organization_test.go

@@ -184,7 +184,40 @@ func TestAccConfigDSOrganization_basic(t *testing.T) {
 			{
 				Config: configWithPluralDS(orgID),
 				Check: checkAggrDS(resource.TestCheckResourceAttr(datasourceName, "gen_ai_features_enabled", "true"),
-					resource.TestCheckResourceAttr(pluralDSName, "results.0.gen_ai_features_enabled", "true")),
+					resource.TestCheckResourceAttr(pluralDSName, "results.0.gen_ai_features_enabled", "true"),
+					resource.TestCheckResourceAttrSet(datasourceName, "users.#"),
+					resource.TestCheckResourceAttrSet(datasourceName, "users.0.id")),
+			},
+		},
+	})
+}
+
+func TestAccConfigDSOrganization_users(t *testing.T) {
+	var (
+		orgID = os.Getenv("MONGODB_ATLAS_ORG_ID")
+	)
+
+	resource.ParallelTest(t, resource.TestCase{
+		ProtoV6ProviderFactories: acc.TestAccProviderV6Factories,
+		Steps: []resource.TestStep{
+			{
+				Config: configWithPluralDS(orgID),
+				Check: checkAggrDS(
+					resource.TestCheckResourceAttrWith(datasourceName, "users.#", acc.IntGreatThan(0)),
+					resource.TestCheckResourceAttrSet(datasourceName, "users.0.id"),
+					resource.TestCheckResourceAttrSet(datasourceName, "users.0.roles.0.org_roles.#"),
+					resource.TestCheckResourceAttrSet(datasourceName, "users.0.roles.0.project_roles_assignments.#"),
+					resource.TestMatchResourceAttr(datasourceName, "users.0.username", regexp.MustCompile(`.*@mongodb\.com$`)),
+					resource.TestMatchResourceAttr(datasourceName, "users.0.last_auth", regexp.MustCompile(`^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})$`)), // Follows RFC3339 timestamp
+
+					resource.TestCheckResourceAttrWith(pluralDSName, "results.0.users.#", acc.IntGreatThan(0)),
+					resource.TestCheckResourceAttrSet(pluralDSName, "results.0.users.0.id"),
+					resource.TestCheckResourceAttrSet(pluralDSName, "results.0.users.0.roles.0.org_roles.#"),
+					resource.TestCheckResourceAttrSet(pluralDSName, "results.0.users.0.roles.0.project_roles_assignments.#"),
+					resource.TestMatchResourceAttr(pluralDSName, "results.0.users.0.username", regexp.MustCompile(`.*@mongodb\.com$`)),
+					resource.TestMatchResourceAttr(pluralDSName, "results.0.users.0.last_auth", regexp.MustCompile(`^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})$`)), // Follows RFC3339 timestamp
+
+				),
 			},
 		},
 	})