diff --git a/docs/data-sources/application.md b/docs/data-sources/application.md index 740dbd9de5..448bb35ea9 100644 --- a/docs/data-sources/application.md +++ b/docs/data-sources/application.md @@ -6,6 +6,14 @@ 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 @@ -13,18 +21,20 @@ 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 diff --git a/docs/data-sources/client_config.md b/docs/data-sources/client_config.md index 7d31b761c4..1502080991 100644 --- a/docs/data-sources/client_config.md +++ b/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. diff --git a/docs/data-sources/domains.md b/docs/data-sources/domains.md index 34ca6dfd09..9b28161414 100644 --- a/docs/data-sources/domains.md +++ b/docs/data-sources/domains.md @@ -6,20 +6,28 @@ 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. @@ -27,12 +35,16 @@ output "domains" { * `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`. \ No newline at end of file +* `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`. diff --git a/docs/data-sources/group.md b/docs/data-sources/group.md index caebbb57ac..9f452a7c89 100644 --- a/docs/data-sources/group.md +++ b/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 diff --git a/docs/data-sources/groups.md b/docs/data-sources/groups.md index c9418b2e62..55db6bdaf6 100644 --- a/docs/data-sources/groups.md +++ b/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 @@ -21,7 +29,7 @@ The following arguments are supported: * `display_names` - (Optional) The display names of the groups. * `object_ids` - (Optional) The object IDs of the groups. -~> **NOTE:** Either `display_names` or `object_ids` should be specified. Either of these _may_ be specified as an empty list, in which case no results will be returned. +~> One of `display_names` or `object_ids` should be specified. Either of these _may_ be specified as an empty list, in which case no results will be returned. ## Attributes Reference diff --git a/docs/data-sources/service_principal.md b/docs/data-sources/service_principal.md index 4afef5fefa..dc1287cb2f 100644 --- a/docs/data-sources/service_principal.md +++ b/docs/data-sources/service_principal.md @@ -6,9 +6,17 @@ 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" { @@ -16,7 +24,7 @@ data "azuread_service_principal" "example" { } ``` -**Look up by application ID** +*Look up by application ID (client ID)* ```terraform data "azuread_service_principal" "example" { @@ -24,7 +32,7 @@ data "azuread_service_principal" "example" { } ``` -**Look up by service principal object ID** +*Look up by service principal object ID* ```terraform data "azuread_service_principal" "example" { @@ -40,7 +48,7 @@ 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 @@ -48,19 +56,22 @@ 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. diff --git a/docs/data-sources/user.md b/docs/data-sources/user.md index 76e3b2598b..dc63ea212b 100644 --- a/docs/data-sources/user.md +++ b/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. diff --git a/docs/data-sources/users.md b/docs/data-sources/users.md index 19de021919..b9ddab5915 100644 --- a/docs/data-sources/users.md +++ b/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 diff --git a/docs/guides/azure_cli.md b/docs/guides/azure_cli.md index 012a048729..1c1501b5de 100644 --- a/docs/guides/azure_cli.md +++ b/docs/guides/azure_cli.md @@ -25,17 +25,11 @@ We recommend using either a Service Principal or Managed Identity when running T ## Logging into the Azure CLI -~> **Using other clouds** If you're using the **China**, **German** or **Government** Azure Clouds - you'll need to first configure the Azure CLI to work with that Cloud, so that the correct authentication service is used. You can do this by running: - -```shell -$ az cloud set --name AzureChinaCloud|AzureGermanCloud|AzureUSGovernment -``` - ---- +-> **Using other clouds** If you're using the **China**, **German** or **Government** Azure Clouds - you'll need to first configure the Azure CLI to work with that Cloud, so that the correct authentication service is used. You can do this by running:

`$ az cloud set --name AzureChinaCloud|AzureGermanCloud|AzureUSGovernment` Firstly, login to the Azure CLI using: -```shell +```shell-session $ az login --allow-no-subscriptions ``` @@ -43,53 +37,48 @@ The `--allow-no-subscriptions` argument enables access to tenants that have no l Once logged in - it's possible to list the Subscriptions and Tenants associated with the account via: -```shell -$ az account list +```shell-session +$ az account list -o table --all --query "[].{TenantID: tenantId, Subscription: name, Default: isDefault}" ``` The output (similar to below) will display one or more Tenants and/or Subscriptions. -```json -[ - { - "cloudName": "AzureCloud", - "id": "00000000-0000-0000-0000-000000000000", - "isDefault": true, - "name": "PAYG Subscription", - "state": "Enabled", - "tenantId": "00000000-0000-0000-0000-000000000000", - "user": { - "name": "user@example.com", - "type": "user" - } - } -] +``` +TenantID Subscription Default +------------------------------------ ----------------------------------- --------- +00000000-0000-1111-1111-111111111111 N/A(tenant level account) False +00000000-0000-2222-2222-222222222222 N/A(tenant level account) False +00000000-0000-1111-1111-111111111111 My Subscription True +00000000-0000-1111-1111-111111111111 My Other Subscription False ``` -Each entry shown is referred to as an `Azure CLI account`, which represents either a subscription with its linked tenant, or a tenant without any accessible subscriptions. The provider will select the tenant ID from your default Azure CLI account. If you have more than one tenant listed in the output of `az account list`, for example if you are a guest user in other tenants, you can specify the tenant to use. +Each entry shown is referred to as an `Azure CLI account`, which represents either a subscription with its linked tenant, or a tenant without any accessible subscriptions (Azure CLI does not show tenant names or domains). The provider will select the tenant ID from your default Azure CLI account. If you have more than one tenant listed in the output of `az account list`, for example if you are a guest user in other tenants, you can specify the tenant to use. -```shell +```shell-session # sh -export ARM_TENANT_ID=00000000-0000-0000-0000-000000000000 - +export ARM_TENANT_ID=00000000-0000-2222-2222-222222222222 +``` +```powershell # PowerShell -$env:ARM_TENANT_ID = 00000000-0000-0000-0000-000000000000 +$env:ARM_TENANT_ID = 00000000-0000-2222-2222-222222222222 ``` You can also configure the tenant ID from within the provider block. ```hcl provider "azuread" { - tenant_id = "00000000-0000-0000-0000-000000000000" + tenant_id = "00000000-0000-2222-2222-222222222222" } ``` Alternatively, you can configure the Azure CLI to default to the tenant you are managing with Terraform. -```bash +```shell-session $ az login --allow-no-subscriptions --tenant "TENANT_ID_OR_DOMAIN" ``` +
+ -> **Tenants and Subscriptions** The AzureAD provider operates on tenants and not on subscriptions. We recommend always specifying `az login --allow-no-subscriptions` as it will force the Azure CLI to report tenants with no associated subscriptions, or where your user account does not have any roles assigned for a subscription. --- @@ -100,7 +89,7 @@ No specific configuration is required for the provider to use Azure CLI authenti ```hcl provider "azuread" { - tenant_id = "10000000-2000-3000-4000-500000000000" + tenant_id = "00000000-0000-1111-1111-111111111111" } ``` diff --git a/docs/guides/managed_service_identity.md b/docs/guides/managed_service_identity.md index 2a7c692d6c..3cfa364738 100644 --- a/docs/guides/managed_service_identity.md +++ b/docs/guides/managed_service_identity.md @@ -34,11 +34,11 @@ When using a managed identity, you can only manage resources in the tenant where The (simplified) Terraform configuration below configures a Virtual Machine with a system-assigned identity, and then outputs the Object ID of the corresponding Service Principal: -```hcl +```terraform data "azurerm_subscription" "current" {} -resource "azurerm_linux_virtual_machine" "example" { - name = "test-vm" +resource "azurerm_linux_virtual_machine" "management_host" { + name = "management-vm" # ... @@ -47,8 +47,8 @@ resource "azurerm_linux_virtual_machine" "example" { } } -output "example_msi_object_id" { - value = azurerm_linux_virtual_machine.test.identity.0.principal_id +output "management_host_identity_object_id" { + value = azurerm_linux_virtual_machine.management_host.identity.0.principal_id } ``` @@ -56,6 +56,25 @@ Refer to the [azurerm_linux_virtual_machine][azurerm_linux_virtual_machine] and The implicitly created Service Principal should have the same or similar name as your virtual machine. At this point you will need to assign permissions to access Azure Active Directory to create and modify Azure Active Directory objects such as users and groups. See the [Configuring a Service Principal for managing Azure Active Directory][azuread-service-principal-permissions] guide for more information. +## Using a user-assigned identity + +As an alternative to using a system-assigned managed identity, you can create a user-assigned identity that can be allocated to one or more resources such as virtual machines. + +```terraform +resource "azurerm_user_assigned_identity" "terraform" { + name = "terraform" + # ... +} + +output "terraform_identity_object_id" { + value = azurerm_user_assigned_identity.terraform.principal_id +} +``` + +Refer to the [azurerm_user_assigned_identity][azurerm_user_assigned_identity] documentation for more information on how to configure this resource. + +The implicitly created Service Principal should have the same or similar name as the user assigned identity. At this point you will need to assign permissions to access Azure Active Directory to create and modify Azure Active Directory objects such as users and groups. See the [Configuring a Service Principal for managing Azure Active Directory][azuread-service-principal-permissions] guide for more information. + ## Configuring Managed Identity in Terraform At this point we assume that managed identity is configured on the resource (e.g. virtual machine) being used, that permissions have been granted, and that you are running Terraform on that resource. @@ -108,3 +127,4 @@ Next you should follow the [Configuring a Service Principal for managing Azure A [azuread-service-principal-permissions]: https://registry.terraform.io/providers/hashicorp/azuread/latest/docs/guides/service_principal_configuration#method-1-api-roles-recommended-for-service-principals [azurerm_linux_virtual_machine]: https://www.terraform.io/docs/providers/azurerm/r/linux_virtual_machine.html [azurerm_windows_virtual_machine]: https://www.terraform.io/docs/providers/azurerm/r/windows_virtual_machine.html +[azurerm_user_assigned_identity]: https://registry.terraform.io/providers/hashicorp/azurerm/latest/docs/resources/user_assigned_identity diff --git a/docs/guides/microsoft-graph.md b/docs/guides/microsoft-graph.md index 94dcf88a0c..44ed0f23c2 100644 --- a/docs/guides/microsoft-graph.md +++ b/docs/guides/microsoft-graph.md @@ -210,7 +210,9 @@ The deprecated field `description` has been replaced by the `display_name` field -> The following also applies when the Microsoft Graph beta is enabled in version 1.5 or later -The `key_id` field has become read-only as Azure Active Directory no longer allows user-specified key IDs for passwords. This also means that the `azuread_application_password` resource no longer supports importing in version 2.0 of the provider. +The `azuread_application_password` resource no longer supports importing. + +The `key_id` field has become read-only as Azure Active Directory no longer allows user-specified key IDs for passwords. The `value` field has become read-only as Azure Active Directory no longer accepts user-supplied password values. Passwords are instead auto-generated by Azure and exported with the `value` attribute by the resource. @@ -226,9 +228,11 @@ The deprecated field `description` has been replaced by the `display_name` field -> The following also applies when the Microsoft Graph beta is enabled in version 1.5 or later +The `azuread_service_principal_password` resource no longer supports importing. + The `display_name`, `start_date` and `end_date` fields are no longer respected by the API and have been made read-only. Accordingly the `end_date_relative` field has been removed. -The `key_id` field has become read-only as Azure Active Directory no longer allows user-specified key IDs for passwords. This also means that the `azuread_service_principal_password` resource no longer supports importing in version 2.0 of the provider. +The `key_id` field has become read-only as Azure Active Directory no longer allows user-specified key IDs for passwords. The `value` field has become read-only as Azure Active Directory no longer accepts user-supplied password values. Passwords are instead auto-generated by Azure and exported with the `value` attribute by the resource. diff --git a/docs/guides/service_principal_client_certificate.md b/docs/guides/service_principal_client_certificate.md index 3b2755fc3d..7ebce126b7 100644 --- a/docs/guides/service_principal_client_certificate.md +++ b/docs/guides/service_principal_client_certificate.md @@ -78,13 +78,14 @@ The provider can be configured to read the certificate bundle from the .pfx file Our recommended approach is storing the credentials as Environment Variables, for example: *Reading the certificate bundle from the filesystem* -```bash +```shell-session # sh $ export ARM_CLIENT_ID="00000000-0000-0000-0000-000000000000" $ export ARM_CLIENT_CERTIFICATE_PATH="/path/to/my/client/certificate.pfx" $ export ARM_CLIENT_CERTIFICATE_PASSWORD="Pa55w0rd123" $ export ARM_TENANT_ID="10000000-2000-3000-4000-500000000000" - +``` +```powershell # PowerShell > $env:ARM_CLIENT_ID = "00000000-0000-0000-0000-000000000000" > $env:ARM_CLIENT_CERTIFICATE_PATH = "/path/to/my/client/certificate.pfx" @@ -93,13 +94,14 @@ $ export ARM_TENANT_ID="10000000-2000-3000-4000-500000000000" ``` *Passing the encoded certificate bundle directly* -```bash +```shell-session # sh $ export ARM_CLIENT_ID="00000000-0000-0000-0000-000000000000" $ export ARM_CLIENT_CERTIFICATE="$(base64 /path/to/my/client/certificate.pfx)" $ export ARM_CLIENT_CERTIFICATE_PASSWORD="Pa55w0rd123" $ export ARM_TENANT_ID="10000000-2000-3000-4000-500000000000" - +``` +```powershell # PowerShell > $env:ARM_CLIENT_ID = "00000000-0000-0000-0000-000000000000" > $env:ARM_CLIENT_CERTIFICATE = [Convert]::ToBase64String([System.IO.File]::ReadAllBytes("/path/to/my/client/certificate.pfx")) @@ -115,7 +117,7 @@ Next you should follow the [Configuring a Service Principal for managing Azure A It's also possible to configure these variables either directly, or from variables, in your provider block, like so: -~> We recommend not defining these variables in-line since they could easily be checked into Source Control. +~> **Caution** We recommend not defining these variables in-line since they could easily be checked into Source Control. *Reading the certificate bundle from the filesystem* ```hcl diff --git a/docs/guides/service_principal_client_secret.md b/docs/guides/service_principal_client_secret.md index b54311500f..12dc7562ec 100644 --- a/docs/guides/service_principal_client_secret.md +++ b/docs/guides/service_principal_client_secret.md @@ -56,16 +56,17 @@ Now we have obtained the necessary credentials, it's possible to configure Terra Our recommended approach is storing the credentials as Environment Variables, for example: -```bash +```shell-session # sh $ export ARM_CLIENT_ID="00000000-0000-0000-0000-000000000000" $ export ARM_CLIENT_SECRET="MyCl1eNtSeCr3t" $ export ARM_TENANT_ID="10000000-2000-3000-4000-500000000000" - +``` +```powershell # PowerShell -$env:ARM_CLIENT_ID = 00000000-0000-0000-0000-000000000000 -$env:ARM_CLIENT_SECRET = 03MWPmH2W3i008UVcucO1E1vifY_bR -$env:ARM_TENANT_ID = 10000000-2000-3000-4000-500000000000 +$env:ARM_CLIENT_ID = "00000000-0000-0000-0000-000000000000" +$env:ARM_CLIENT_SECRET = "MyCl1eNtSeCr3t" +$env:ARM_TENANT_ID = "10000000-2000-3000-4000-500000000000" ``` At this point running either `terraform plan` or `terraform apply` should allow Terraform to authenticate using the Client Secret. @@ -76,9 +77,9 @@ Next you should follow the [Configuring a Service Principal for managing Azure A It's also possible to configure these variables either directly, or from variables, in your provider block, like so: -~> We recommend not defining these variables in-line since they could easily be checked into Source Control. +~> **Caution** We recommend not defining these variables in-line since they could easily be checked into Source Control. -```hcl +```terraform variable "client_secret" {} provider "azuread" { diff --git a/docs/guides/service_principal_configuration.md b/docs/guides/service_principal_configuration.md index 9d6b4fe576..80fbff7926 100644 --- a/docs/guides/service_principal_configuration.md +++ b/docs/guides/service_principal_configuration.md @@ -20,7 +20,7 @@ We recommend using either a Service Principal or Managed Identity when running T A Service Principal represents an application within Azure Active Directory whose properties and authentication tokens can be used as the `tenant_id`, `client_id` and `client_secret` fields needed by Terraform. -Depending on how the service principal authenticates to Azure it can be created and configured in a number of different ways: +Depending on how the service principal authenticates to Azure it can be created and configured in a number of different ways: * [Authenticating to Azure using a Service Principal and a Client Certificate](service_principal_client_certificate.html) * [Authenticating to Azure using a Service Principal and a Client Secret](service_principal_client_secret.html) @@ -50,6 +50,8 @@ Resource(s) | Role Name(s) `azuread_group`
`azuread_group_member` | Group.ReadWrite.All `azuread_user` | User.ReadWrite.All +
+ -> **Permissions for other resources** If the resource you are using is not shown in the above table, consult the documentation page for the resource for a guide to the required permissions. Depending on the configuration of your AAD tenant, you may also need to grant the Directory.Read.All and/or Directory.ReadWrite.All roles. If a resource you are using is not shown in the table above, consult the resource documentation. diff --git a/docs/resources/application.md b/docs/resources/application.md index af0c28c879..1f1081d584 100644 --- a/docs/resources/application.md +++ b/docs/resources/application.md @@ -6,6 +6,16 @@ subcategory: "Applications" Manages an application registration within Azure Active Directory. +## API Permissions + +The following API permissions are required in order to use this resource. + +When authenticated with a service principal, this resource requires one of the following application roles: `Application.ReadWrite.All` or `Directory.ReadWrite.All` + +-> It's possible to use this resource with the `Application.ReadWrite.OwnedBy` application role, provided the principal being used to run Terraform is included in the `owners` property. + +When authenticated with a user principal, this resource requires one of the following directory roles: `Application Administrator` or `Global Administrator` + ## Example Usage ```terraform @@ -267,16 +277,11 @@ In addition to all arguments above, the following attributes are exported: * `app_role_ids` - A mapping of app role values to app role IDs, intended to be useful when referencing app roles in other resources in your configuration. * `application_id` - The Application ID (also called Client ID). * `disabled_by_microsoft` - Whether Microsoft has disabled the registered application. If the application is disabled, this will be a string indicating the status/reason, e.g. `DisabledDueToViolationOfServicesAgreement` +* `logo_url` - CDN URL to the application's logo. * `oauth2_permission_scope_ids` - A mapping of OAuth2.0 permission scope values to scope IDs, intended to be useful when referencing permission scopes in other resources in your configuration. * `object_id` - The application's object ID. * `publisher_domain` - The verified publisher domain for the application. ---- - -`info` block exports the following: - -* `logo_url` - CDN URL to the application's logo. - ## Import Applications can be imported using their object ID, e.g. diff --git a/docs/resources/application_certificate.md b/docs/resources/application_certificate.md index e38ffe42ae..644afd2b0c 100644 --- a/docs/resources/application_certificate.md +++ b/docs/resources/application_certificate.md @@ -6,6 +6,16 @@ subcategory: "Applications" Manages a certificate associated with an application within Azure Active Directory. These are also referred to as client certificates during authentication. +## API Permissions + +The following API permissions are required in order to use this resource. + +When authenticated with a service principal, this resource requires one of the following application roles: `Application.ReadWrite.All` or `Directory.ReadWrite.All` + +-> It's possible to use this resource with the `Application.ReadWrite.OwnedBy` application role, provided the principal being used to run Terraform is included in the `owners` property. + +When authenticated with a user principal, this resource requires one of the following directory roles: `Application Administrator` or `Global Administrator` + ## Example Usage *Using a PEM certificate* @@ -113,12 +123,12 @@ The following arguments are supported: * `application_object_id` - (Required) The object ID of the application for which this certificate should be created. Changing this field forces a new resource to be created. * `encoding` - (Optional) Specifies the encoding used for the supplied certificate data. Must be one of `pem`, `base64` or `hex`. Defaults to `pem`. --> **NOTE:** The `hex` encoding option is useful for consuming certificate data from the [azurerm_key_vault_certificate](https://registry.terraform.io/providers/hashicorp/azurerm/latest/docs/resources/key_vault_certificate) resource. +-> **Tip for Azure Key Vault** The `hex` encoding option is useful for consuming certificate data from the [azurerm_key_vault_certificate](https://registry.terraform.io/providers/hashicorp/azurerm/latest/docs/resources/key_vault_certificate) resource. * `end_date` - (Optional) The end date until which the certificate is valid, formatted as an RFC3339 date string (e.g. `2018-01-01T01:02:03Z`). If omitted, the API will decide a suitable expiry date, which is typically around 2 years from the start date. Changing this field forces a new resource to be created. * `end_date_relative` - (Optional) A relative duration for which the certificate is valid until, for example `240h` (10 days) or `2400h30m`. Changing this field forces a new resource to be created. -~> **NOTE:** One of `end_date` or `end_date_relative` must be set. The maximum duration is enforced by Azure AD. +~> One of `end_date` or `end_date_relative` must be set. The maximum allowed duration is determined by Azure AD. * `key_id` - (Optional) A UUID used to uniquely identify this certificate. If omitted, a random UUID will be automatically generated. Changing this field forces a new resource to be created. * `start_date` - (Optional) The start date from which the certificate is valid, formatted as an RFC3339 date string (e.g. `2018-01-01T01:02:03Z`). If this isn't specified, the current date and time are used. Changing this field forces a new resource to be created. @@ -127,9 +137,7 @@ The following arguments are supported: ## Attributes Reference -In addition to all arguments above, the following attributes are exported: - -*No additional attributes are exported* +No additional attributes are exported. ## Import @@ -139,4 +147,4 @@ Certificates can be imported using the object ID of the associated application a terraform import azuread_application_certificate.test 00000000-0000-0000-0000-000000000000/certificate/11111111-1111-1111-1111-111111111111 ``` --> **NOTE:** This ID format is unique to Terraform and is composed of the application's object ID, the string "certificate" and the certificate's key ID in the format `{ObjectId}/certificate/{CertificateKeyId}`. +-> This ID format is unique to Terraform and is composed of the application's object ID, the string "certificate" and the certificate's key ID in the format `{ObjectId}/certificate/{CertificateKeyId}`. diff --git a/docs/resources/application_password.md b/docs/resources/application_password.md index a35e6d66e7..c4dcb1dd09 100644 --- a/docs/resources/application_password.md +++ b/docs/resources/application_password.md @@ -6,6 +6,16 @@ subcategory: "Applications" Manages a password credential associated with an application within Azure Active Directory. These are also referred to as client secrets during authentication. +## API Permissions + +The following API permissions are required in order to use this resource. + +When authenticated with a service principal, this resource requires one of the following application roles: `Application.ReadWrite.All` or `Directory.ReadWrite.All` + +-> It's possible to use this resource with the `Application.ReadWrite.OwnedBy` application role, provided the principal being used to run Terraform is included in the `owners` property. + +When authenticated with a user principal, this resource requires one of the following directory roles: `Application Administrator` or `Global Administrator` + ## Example Usage *Basic example* diff --git a/docs/resources/application_pre_authorized.md b/docs/resources/application_pre_authorized.md index fac746dc32..e61512efa1 100644 --- a/docs/resources/application_pre_authorized.md +++ b/docs/resources/application_pre_authorized.md @@ -6,6 +6,16 @@ subcategory: "Applications" Manages client applications that are pre-authorized with the specified permissions to access an application's APIs without requiring user consent. +## API Permissions + +The following API permissions are required in order to use this resource. + +When authenticated with a service principal, this resource requires one of the following application roles: `Application.ReadWrite.All` or `Directory.ReadWrite.All` + +-> It's possible to use this resource with the `Application.ReadWrite.OwnedBy` application role, provided the principal being used to run Terraform is included in the `owners` property. + +When authenticated with a user principal, this resource requires one of the following directory roles: `Application Administrator` or `Global Administrator` + ## Example Usage ```terraform @@ -56,9 +66,7 @@ The following arguments are supported: ## Attributes Reference -In addition to all arguments above, the following attributes are exported: - -*No additional attributes are exported* +No additional attributes are exported. ## Import @@ -68,4 +76,4 @@ Pre-authorized applications can be imported using the object ID of the authorizi terraform import azuread_application_pre_authorized.example 00000000-0000-0000-0000-000000000000/preAuthorizedApplication/11111111-1111-1111-1111-111111111111 ``` --> **NOTE:** This ID format is unique to Terraform and is composed of the authorizing application's object ID, the string "preAuthorizedApplication" and the authorized application's application ID (client ID) in the format `{ObjectId}/preAuthorizedApplication/{ApplicationId}`. +-> This ID format is unique to Terraform and is composed of the authorizing application's object ID, the string "preAuthorizedApplication" and the authorized application's application ID (client ID) in the format `{ObjectId}/preAuthorizedApplication/{ApplicationId}`. diff --git a/docs/resources/group.md b/docs/resources/group.md index 78a3575ffe..f7ce7a6ec4 100644 --- a/docs/resources/group.md +++ b/docs/resources/group.md @@ -6,6 +6,14 @@ subcategory: "Groups" Manages a group within Azure Active Directory. +## API Permissions + +The following API permissions are required in order to use this resource. + +When authenticated with a service principal, this resource requires one of the following application roles: `Group.ReadWrite.All` or `Directory.ReadWrite.All` + +When authenticated with a user principal, this resource requires one of the following directory roles: `Groups Administrator`, `User Administrator` or `Global Administrator` + ## Example Usage *Basic example* diff --git a/docs/resources/group_member.md b/docs/resources/group_member.md index 911460b407..2a655ebe48 100644 --- a/docs/resources/group_member.md +++ b/docs/resources/group_member.md @@ -8,6 +8,14 @@ Manages a single group membership within Azure Active Directory. -> **Warning** Do not use this resource at the same time as the `members` property of the `azuread_group` resource. +## API Permissions + +The following API permissions are required in order to use this resource. + +When authenticated with a service principal, this resource requires one of the following application roles: `Group.ReadWrite.All` or `Directory.ReadWrite.All` + +When authenticated with a user principal, this resource requires one of the following directory roles: `Groups Administrator`, `User Administrator` or `Global Administrator` + ## Example Usage ```terraform @@ -48,4 +56,4 @@ Group members can be imported using the object ID of the group and the object ID terraform import azuread_group_member.test 00000000-0000-0000-0000-000000000000/member/11111111-1111-1111-1111-111111111111 ``` --> **NOTE:** This ID format is unique to Terraform and is composed of the Azure AD Group Object ID and the target Member Object ID in the format `{GroupObjectID}/member/{MemberObjectID}`. +-> This ID format is unique to Terraform and is composed of the Azure AD Group Object ID and the target Member Object ID in the format `{GroupObjectID}/member/{MemberObjectID}`. diff --git a/docs/resources/service_principal.md b/docs/resources/service_principal.md index c7a7a35724..5bf567b3a9 100644 --- a/docs/resources/service_principal.md +++ b/docs/resources/service_principal.md @@ -6,6 +6,14 @@ subcategory: "Service Principals" Manages a service principal associated with an application within Azure Active Directory. +## API Permissions + +The following API permissions are required in order to use this resource. + +When authenticated with a service principal, this resource requires one of the following application roles: `Application.ReadWrite.All` or `Directory.ReadWrite.All` + +When authenticated with a user principal, this resource requires one of the following directory roles: `Application Administrator` or `Global Administrator` + ## Example Usage ```terraform diff --git a/docs/resources/service_principal_certificate.md b/docs/resources/service_principal_certificate.md index 0e39108000..f5ac587522 100644 --- a/docs/resources/service_principal_certificate.md +++ b/docs/resources/service_principal_certificate.md @@ -6,6 +6,14 @@ subcategory: "Service Principals" Manages a certificate associated with a service principal within Azure Active Directory. +## API Permissions + +The following API permissions are required in order to use this resource. + +When authenticated with a service principal, this resource requires one of the following application roles: `Application.ReadWrite.All` or `Directory.ReadWrite.All` + +When authenticated with a user principal, this resource requires one of the following directory roles: `Application Administrator` or `Global Administrator` + ## Example Usage *Using a PEM certificate* @@ -53,12 +61,12 @@ The following arguments are supported: * `encoding` - (Optional) Specifies the encoding used for the supplied certificate data. Must be one of `pem`, `base64` or `hex`. Defaults to `pem`. --> **NOTE:** The `hex` encoding option is useful for consuming certificate data from the [azurerm_key_vault_certificate](https://registry.terraform.io/providers/hashicorp/azurerm/latest/docs/resources/key_vault_certificate) resource. +-> **Tip for Azure Key Vault** The `hex` encoding option is useful for consuming certificate data from the [azurerm_key_vault_certificate](https://registry.terraform.io/providers/hashicorp/azurerm/latest/docs/resources/key_vault_certificate) resource. * `end_date` - (Optional) The end date until which the certificate is valid, formatted as an RFC3339 date string (e.g. `2018-01-01T01:02:03Z`). Changing this field forces a new resource to be created. * `end_date_relative` - (Optional) A relative duration for which the certificate is valid until, for example `240h` (10 days) or `2400h30m`. Valid time units are "ns", "us" (or "µs"), "ms", "s", "m", "h". Changing this field forces a new resource to be created. -~> **NOTE:** One of `end_date` or `end_date_relative` must be set. The maximum duration is enforced by Azure AD. +~> One of `end_date` or `end_date_relative` must be set. The maximum duration is determined by Azure AD. * `key_id` - (Optional) A UUID used to uniquely identify this certificate. If not specified a UUID will be automatically generated. Changing this field forces a new resource to be created. * `service_principal_id` - (Required) The object ID of the service principal for which this certificate should be created. Changing this field forces a new resource to be created. @@ -68,9 +76,7 @@ The following arguments are supported: ## Attributes Reference -In addition to all arguments above, the following attributes are exported: - -*No additional attributes are exported* +No additional attributes are exported. ## Import @@ -80,4 +86,4 @@ Certificates can be imported using the object ID of the associated service princ terraform import azuread_service_principal_certificate.test 00000000-0000-0000-0000-000000000000/certificate/11111111-1111-1111-1111-111111111111 ``` --> **NOTE:** This ID format is unique to Terraform and is composed of the service principal's object ID, the string "certificate" and the certificate's key ID in the format `{ServicePrincipalObjectId}/certificate/{CertificateKeyId}`. +-> This ID format is unique to Terraform and is composed of the service principal's object ID, the string "certificate" and the certificate's key ID in the format `{ServicePrincipalObjectId}/certificate/{CertificateKeyId}`. diff --git a/docs/resources/service_principal_password.md b/docs/resources/service_principal_password.md index 100042461a..877e9ad297 100644 --- a/docs/resources/service_principal_password.md +++ b/docs/resources/service_principal_password.md @@ -6,6 +6,14 @@ subcategory: "Service Principals" Manages a password credential associated with a service principal within Azure Active Directory. See also the [azuread_application_password resource](application_password.html). +## API Permissions + +The following API permissions are required in order to use this resource. + +When authenticated with a service principal, this resource requires one of the following application roles: `Application.ReadWrite.All` or `Directory.ReadWrite.All` + +When authenticated with a user principal, this resource requires one of the following directory roles: `Application Administrator` or `Global Administrator` + ## Example Usage *Basic example* diff --git a/docs/resources/user.md b/docs/resources/user.md index a2689215f1..5a0334e917 100644 --- a/docs/resources/user.md +++ b/docs/resources/user.md @@ -6,6 +6,14 @@ subcategory: "Users" Manages a user within Azure Active Directory. +## API Permissions + +The following API permissions are required in order to use this resource. + +When authenticated with a service principal, this resource requires one of the following application roles: `User.ReadWrite.All` or `Directory.ReadWrite.All` + +When authenticated with a user principal, this resource requires one of the following directory roles: `User Administrator` or `Global Administrator` + ## Example Usage ```terraform