Merge branch 'main' into feature/groups_datasource-show-all-flag

README.md

@@ -5,6 +5,7 @@
 - [Terraform Website](https://www.terraform.io)
 - [AzureAD Provider Documentation](https://terraform.io/docs/providers/azuread/)
 - [AzureAD Provider Usage Examples](https://github.com/hashicorp/terraform-provider-azuread/tree/main/examples)
+- [Learn Tutorial](https://learn.hashicorp.com/tutorials/terraform/azure-ad)
 - [Slack Workspace for Contributors](https://terraform-azure.slack.com) ([Request Invite](https://join.slack.com/t/terraform-azure/shared_invite/enQtNDMzNjQ5NzcxMDc3LWNiY2ZhNThhNDgzNmY0MTM0N2MwZjE4ZGU0MjcxYjUyMzRmN2E5NjZhZmQ0ZTA1OTExMGNjYzA4ZDkwZDYxNDE))
 
 

docs/data-sources/application.md

@@ -6,25 +6,35 @@ subcategory: "Applications"
 
 Use this data source to access information about an existing Application within Azure Active Directory.
 
+## API Permissions
+
+The following API permissions are required in order to use this data source.
+
+When authenticated with a service principal, this data source requires one of the following application roles: `Application.Read.All` or `Directory.Read.All`
+
+When authenticated with a user principal, this data source does not require any additional roles.
+
 ## Example Usage
 
 ```terraform
 data "azuread_application" "example" {
   display_name = "My First AzureAD Application"
 }
 
-output "azure_ad_object_id" {
+output "application_object_id" {
   value = data.azuread_application.example.id
 }
 ```
 
 ## Argument Reference
 
+The following arguments are supported:
+
 * `application_id` - (Optional) Specifies the Application ID (also called Client ID).
 * `display_name` - (Optional) Specifies the display name of the application.
 * `object_id` - (Optional) Specifies the Object ID of the application.
 
-~> **NOTE:** One of `object_id`, `application_id` or `display_name` must be specified.
+~> One of `object_id`, `application_id` or `display_name` must be specified.
 
 ## Attributes Reference
 

docs/data-sources/client_config.md

@@ -6,23 +6,28 @@ subcategory: "Base"
 
 Use this data source to access the configuration of the AzureAD provider.
 
+## API Permissions
+
+No additional roles are required to use this data source.
+
 ## Example Usage
 
 ```hcl
-data "azuread_client_config" "current" {
-}
+data "azuread_client_config" "current" {}
 
-output "account_id" {
-  value = data.azuread_client_config.current.client_id
+output "object_id" {
+  value = data.azuread_client_config.current.object_id
 }
 ```
 
 ## Argument Reference
 
-There are no arguments available for this data source.
+This data source does not have any arguments.
 
 ## Attributes Reference
 
+The following attributes are exported:
+
 * `client_id` - The client ID (application ID) linked to the authenticated principal, or the application used for delegated authentication.
 * `object_id` - The object ID of the authenticated principal.
 * `tenant_id` - The tenant ID of the authenticated principal.

docs/data-sources/domains.md

@@ -6,33 +6,45 @@ subcategory: "Domains"
 
 Use this data source to access information about existing Domains within Azure Active Directory.
 
--> **NOTE:** If you're authenticating using a Service Principal then it must have permissions to `Directory.Read.All` within the `Windows Azure Active Directory` API.
+## API Permissions
+
+The following API permissions are required in order to use this data source.
+
+When authenticated with a service principal, this data source requires one of the following application roles: `Domain.Read.All` or `Directory.Read.All`
+
+When authenticated with a user principal, this data source does not require any additional roles.
 
 ## Example Usage
 
 ```terraform
 data "azuread_domains" "aad_domains" {}
 
-output "domains" {
-  value = data.azuread_domains.aad_domains.domains
+output "domain_names" {
+  value = data.azuread_domains.aad_domains.domains.*.domain_name
 }
 ```
 
 ## Argument Reference
 
+The following arguments are supported:
+
 * `admin_managed` - (Optional) Set to `true` to only return domains whose DNS is managed by Microsoft 365. Defaults to `false`.
 * `include_unverified` - (Optional) Set to `true` if unverified Azure AD domains should be included. Defaults to `false`.
 * `only_default` - (Optional) Set to `true` to only return the default domain.
 * `only_initial` - (Optional) Set to `true` to only return the initial domain, which is your primary Azure Active Directory tenant domain. Defaults to `false`.
 * `only_root` - (Optional) Set to `true` to only return verified root domains. Excludes subdomains and unverified domains.
 * `supports_services` - (Optional) A list of supported services that must be supported by a domain. Possible values include `Email`, `Sharepoint`, `EmailInternalRelayOnly`, `OfficeCommunicationsOnline`, `SharePointDefaultDomain`, `FullRedelegation`, `SharePointPublic`, `OrgIdAuthentication`, `Yammer` and `Intune`.
 
-~> **NOTE:** If `include_unverified` is set to `true` you cannot specify `only_default` or `only_initial`. Additionally, you cannot combine `only_default` with `only_initial`.
+-> **Note on filters** If `include_unverified` is set to `true`, you cannot specify `only_default` or `only_initial`. Additionally, you cannot combine `only_default` with `only_initial`.
 
 ## Attributes Reference
 
+In addition to all arguments above, the following attributes are exported:
+
 * `domains` - A list of tenant domains. Each `domain` object provides the attributes documented below.
 
+---
+
 `domain` object exports the following:
 
 * `admin_managed` - Whether the DNS for the domain is managed by Microsoft 365.
@@ -42,4 +54,4 @@ output "domains" {
 * `initial` - Whether this is the initial domain created by Azure Active Directory.
 * `root` - Whether the domain is a verified root domain (not a subdomain).
 * `verified` - Whether the domain has completed domain ownership verification.
-* `supported_services` - A list of capabilities / services supported by the domain. Possible values include `Email`, `Sharepoint`, `EmailInternalRelayOnly`, `OfficeCommunicationsOnline`, `SharePointDefaultDomain`, `FullRedelegation`, `SharePointPublic`, `OrgIdAuthentication`, `Yammer` and `Intune`.
+* `supported_services` - A list of capabilities / services supported by the domain. Possible values include `Email`, `Sharepoint`, `EmailInternalRelayOnly`, `OfficeCommunicationsOnline`, `SharePointDefaultDomain`, `FullRedelegation`, `SharePointPublic`, `OrgIdAuthentication`, `Yammer` and `Intune`.

docs/data-sources/group.md

@@ -6,6 +6,14 @@ subcategory: "Groups"
 
 Gets information about an Azure Active Directory group.
 
+## API Permissions
+
+The following API permissions are required in order to use this data source.
+
+When authenticated with a service principal, this data source requires one of the following application roles: `Group.Read.All` or `Directory.Read.All`
+
+When authenticated with a user principal, this data source does not require any additional roles.
+
 ## Example Usage (by Group Display Name)
 
 ```terraform
@@ -24,7 +32,7 @@ The following arguments are supported:
 * `object_id` - (Optional) Specifies the object ID of the group.
 * `security_enabled` - (Optional) Whether the group is a security group.
 
-~> **NOTE:** One of `display_name` or `object_id` must be specified.
+~> One of `display_name` or `object_id` must be specified.
 
 ## Attributes Reference
 

docs/data-sources/groups.md

@@ -6,6 +6,14 @@ subcategory: "Groups"
 
 Gets Object IDs or Display Names for multiple Azure Active Directory groups.
 
+## API Permissions
+
+The following API permissions are required in order to use this data source.
+
+When authenticated with a service principal, this data source requires one of the following application roles: `Group.Read.All` or `Directory.Read.All`
+
+When authenticated with a user principal, this data source does not require any additional roles.
+
 ## Example Usage
 
 ```terraform
@@ -28,7 +36,7 @@ The following arguments are supported:
 * `object_ids` - (Optional) The object IDs of the groups.
 * `show_all` - (Optional) A flag to denote if all groups should be fetched and returned.
 
-~> **NOTE:** Either `display_names`, `object_ids` or `show_all` should be specified. Either of the first two _may_ be specified as an empty list, in which case no results will be returned.
+~> One of `display_names`, `object_ids` or `show_all` should be specified. Either of the first two _may_ be specified as an empty list, in which case no results will be returned.
 
 ## Attributes Reference
 

docs/data-sources/service_principal.md

@@ -6,25 +6,33 @@ subcategory: "Service Principals"
 
 Gets information about an existing service principal associated with an application within Azure Active Directory.
 
+## API Permissions
+
+The following API permissions are required in order to use this data source.
+
+When authenticated with a service principal, this data source requires one of the following application roles: `Application.Read.All` or `Directory.Read.All`
+
+When authenticated with a user principal, this data source does not require any additional roles.
+
 ## Example Usage
 
-**Look up by application display name**
+*Look up by application display name*
 
 ```terraform
 data "azuread_service_principal" "example" {
   display_name = "my-awesome-application"
 }
 ```
 
-**Look up by application ID**
+*Look up by application ID (client ID)*
 
 ```terraform
 data "azuread_service_principal" "example" {
   application_id = "00000000-0000-0000-0000-000000000000"
 }
 ```
 
-**Look up by service principal object ID**
+*Look up by service principal object ID*
 
 ```terraform
 data "azuread_service_principal" "example" {
@@ -40,27 +48,30 @@ The following arguments are supported:
 * `display_name` - (Optional) The display name of the application associated with this service principal.
 * `object_id` - (Optional) The object ID of the service principal.
 
-~> **NOTE:** At least one of `application_id`, `display_name` or `object_id` must be specified.
+~> One of `application_id`, `display_name` or `object_id` must be specified.
 
 ## Attributes Reference
 
 The following attributes are exported:
 
 * `account_enabled` - - Whether or not the service principal account is enabled.
 * `alternative_names` - A list of alternative names, used to retrieve service principals by subscription, identify resource group and full resource ids for managed identities.
+* `application_id` - The application ID (client ID) of the application associated with this service principal.
 * `app_role_assignment_required` - Whether this service principal requires an app role assignment to a user or group before Azure AD will issue a user or access token to the application.
 * `app_role_ids` - A mapping of app role values to app role IDs, as published by the associated application, intended to be useful when referencing app roles in other resources in your configuration.
 * `app_roles` - A list of app roles published by the associated application, as documented below. For more information [official documentation](https://docs.microsoft.com/en-us/azure/architecture/multitenant-identity/app-roles).
 * `application_tenant_id` - The tenant ID where the associated application is registered.
 * `description` - A description of the service principal provided for internal end-users.
+* `display_name` - The display name of the application associated with this service principal.
 * `homepage_url` - Home page or landing page of the associated application.
 * `login_url` - The URL where the service provider redirects the user to Azure AD to authenticate. Azure AD uses the URL to launch the application from Microsoft 365 or the Azure AD My Apps.
 * `logout_url` - The URL that will be used by Microsoft's authorization service to logout an user using OpenId Connect front-channel, back-channel or SAML logout protocols, taken from the associated application.
 * `notes` - A free text field to capture information about the service principal, typically used for operational purposes.
 * `notification_email_addresses` - A list of email addresses where Azure AD sends a notification when the active certificate is near the expiration date. This is only for the certificates used to sign the SAML token issued for Azure AD Gallery applications.
-* `object_id` - The object ID for the service principal.
+* `object_id` - The object ID of the service principal.
 * `oauth2_permission_scope_ids` - A mapping of OAuth2.0 permission scope values to scope IDs, as exposed by the associated application, intended to be useful when referencing permission scopes in other resources in your configuration.
 * `oauth2_permission_scopes` - A collection of OAuth 2.0 delegated permissions exposed by the associated application. Each permission is covered by an `oauth2_permission_scopes` block as documented below.
+* `preferred_single_sign_on_mode` - The single sign-on mode configured for this application. Azure AD uses the preferred single sign-on mode to launch the application from Microsoft 365 or the Azure AD My Apps.
 * `redirect_uris` - A list of URLs where user tokens are sent for sign-in with the associated application, or the redirect URIs where OAuth 2.0 authorization codes and access tokens are sent for the associated application.
 * `saml_metadata_url` - The URL where the service exposes SAML metadata for federation.
 * `service_principal_names` - A list of identifier URI(s), copied over from the associated application.

docs/data-sources/user.md

@@ -6,6 +6,14 @@ subcategory: "Users"
 
 Gets information about an Azure Active Directory user.
 
+## API Permissions
+
+The following API permissions are required in order to use this data source.
+
+When authenticated with a service principal, this data source requires one of the following application roles: `User.Read.All` or `Directory.Read.All`
+
+When authenticated with a user principal, this data source does not require any additional roles.
+
 ## Example Usage
 
 ```terraform
@@ -22,7 +30,7 @@ The following arguments are supported:
 * `object_id` - (Optional) The object ID of the user.
 * `user_principal_name` - (Optional) The user principal name (UPN) of the user.
 
-~> **NOTE:** One of `user_principal_name`, `object_id` or `mail_nickname` must be specified.
+~> One of `user_principal_name`, `object_id` or `mail_nickname` must be specified.
 
 ## Attributes Reference
 
@@ -44,9 +52,10 @@ The following attributes are exported:
 * `given_name` - The given name (first name) of the user.
 * `im_addresses` - A list of instant message voice over IP (VOIP) session initiation protocol (SIP) addresses for the user.
 * `job_title` - The user’s job title.
-* `mail_nickname` - The email alias of the user.
 * `mail` - The SMTP address for the user.
+* `mail_nickname` - The email alias of the user.
 * `mobile_phone` - The primary cellular telephone number for the user.
+* `object_id` - The object ID of the user.
 * `office_location` - The office location in the user's place of business.
 * `onpremises_distinguished_name` - The on-premises distinguished name (DN) of the user, synchronised from the on-premises directory when Azure AD Connect is used.
 * `onpremises_domain_name` - The on-premises FQDN, also called dnsDomainName, synchronised from the on-premises directory when Azure AD Connect is used.

docs/data-sources/users.md

@@ -6,6 +6,14 @@ subcategory: "Users"
 
 Gets object IDs or user principal names for multiple Azure Active Directory users.
 
+## API Permissions
+
+The following API permissions are required in order to use this data source.
+
+When authenticated with a service principal, this data source requires one of the following application roles: `User.Read.All` or `Directory.Read.All`
+
+When authenticated with a user principal, this data source does not require any additional roles.
+
 ## Example Usage
 
 ```terraform
@@ -23,7 +31,7 @@ The following arguments are supported:
 * `object_ids` - (Optional) The object IDs of the users.
 * `user_principal_names` - (Optional) The user principal names (UPNs) of the users.
 
-~> **NOTE:** One of `user_principal_names`, `object_ids` or `mail_nicknames` must be specified. These _may_ be specified as an empty list, in which case no results will be returned.
+~> One of `user_principal_names`, `object_ids` or `mail_nicknames` must be specified. These _may_ be specified as an empty list, in which case no results will be returned.
 
 ## Attributes Reference