From 98c986a1685c4aef5c6800d8c715e99c3bdc74a6 Mon Sep 17 00:00:00 2001 From: "Mike F. Robbins" Date: Thu, 9 Apr 2020 20:23:28 -0500 Subject: [PATCH] Added notes to tenant and accesstoken params --- .../Accounts/help/Connect-AzAccount.md | 283 ++++++++++-------- 1 file changed, 164 insertions(+), 119 deletions(-) diff --git a/src/Accounts/Accounts/help/Connect-AzAccount.md b/src/Accounts/Accounts/help/Connect-AzAccount.md index c1484540596a..bc0cf7b47f84 100644 --- a/src/Accounts/Accounts/help/Connect-AzAccount.md +++ b/src/Accounts/Accounts/help/Connect-AzAccount.md @@ -8,26 +8,30 @@ schema: 2.0.0 # Connect-AzAccount ## SYNOPSIS -Connect to Azure with an authenticated account for use with Azure Resource Manager cmdlet requests. +Connect to Azure with an authenticated account for use with cmdlets from the Az PowerShell modules. ## SYNTAX ### UserWithSubscriptionId (Default) + ``` -Connect-AzAccount [-Environment ] [-Tenant ] [-Subscription ] [-ContextName ] - [-SkipContextPopulation] [-UseDeviceAuthentication] [-Force] [-Scope ] - [-DefaultProfile ] [-WhatIf] [-Confirm] [] +Connect-AzAccount [-Environment ] [-Tenant ] [-Subscription ] + [-ContextName ] [-SkipContextPopulation] [-UseDeviceAuthentication] [-Force] + [-Scope ] [-DefaultProfile ] [-WhatIf] [-Confirm] + [] ``` ### ServicePrincipalWithSubscriptionId + ``` -Connect-AzAccount [-Environment ] -Credential [-ServicePrincipal] -Tenant - [-Subscription ] [-ContextName ] [-SkipContextPopulation] [-Force] +Connect-AzAccount [-Environment ] -Credential -ServicePrincipal + -Tenant [-Subscription ] [-ContextName ] [-SkipContextPopulation] [-Force] [-Scope ] [-DefaultProfile ] [-WhatIf] [-Confirm] [] ``` ### UserWithCredential + ``` Connect-AzAccount [-Environment ] -Credential [-Tenant ] [-Subscription ] [-ContextName ] [-SkipContextPopulation] [-Force] @@ -36,142 +40,163 @@ Connect-AzAccount [-Environment ] -Credential [-Tenant ] -CertificateThumbprint -ApplicationId - [-ServicePrincipal] -Tenant [-Subscription ] [-ContextName ] [-SkipContextPopulation] - [-Force] [-Scope ] [-DefaultProfile ] [-WhatIf] [-Confirm] - [] + [-ServicePrincipal] -Tenant [-Subscription ] [-ContextName ] + [-SkipContextPopulation] [-Force] [-Scope ] + [-DefaultProfile ] [-WhatIf] [-Confirm] [] ``` ### AccessTokenWithSubscriptionId + ``` -Connect-AzAccount [-Environment ] [-Tenant ] -AccessToken [-GraphAccessToken ] - [-KeyVaultAccessToken ] -AccountId [-Subscription ] [-ContextName ] - [-SkipValidation] [-SkipContextPopulation] [-Force] [-Scope ] - [-DefaultProfile ] [-WhatIf] [-Confirm] [] +Connect-AzAccount [-Environment ] [-Tenant ] -AccessToken + [-GraphAccessToken ] [-KeyVaultAccessToken ] -AccountId + [-Subscription ] [-ContextName ] [-SkipValidation] [-SkipContextPopulation] + [-Force] [-Scope ] [-DefaultProfile ] [-WhatIf] + [-Confirm] [] ``` ### ManagedServiceLogin + ``` -Connect-AzAccount [-Environment ] [-Tenant ] [-AccountId ] [-Identity] - [-ManagedServicePort ] [-ManagedServiceHostName ] [-ManagedServiceSecret ] - [-Subscription ] [-ContextName ] [-SkipContextPopulation] [-Force] - [-Scope ] [-DefaultProfile ] [-WhatIf] [-Confirm] - [] +Connect-AzAccount [-Environment ] [-Tenant ] [-AccountId ] -Identity + [-ManagedServicePort ] [-ManagedServiceHostName ] + [-ManagedServiceSecret ] [-Subscription ] [-ContextName ] + [-SkipContextPopulation] [-Force] [-Scope ] + [-DefaultProfile ] [-WhatIf] [-Confirm] [] ``` ## DESCRIPTION -The Connect-AzAccount cmdlet connects to Azure with an authenticated account for use with Azure Resource Manager cmdlet requests. -You can use this authenticated account only with Azure Resource Manager cmdlets. -To add an authenticated account for use with Service Management cmdlets, use the Add-AzAccount or the Import-AzPublishSettingsFile cmdlet. -If no context is found for the current user, this command will populate the user's context list with a context for each of their (first 25) subscriptions. The list of contexts created for the user can be found by running "Get-AzContext -ListAvailable". To skip this context population, you can run this command with the "-SkipContextPopulation" switch parameter. -After executing this cmdlet, you can disconnect from an Azure account using Disconnect-AzAccount. + +The `Connect-AzAccount` cmdlet connects to Azure with an authenticated account for use with cmdlets +from the Az PowerShell modules. You can use this authenticated account only with Azure Resource +Manager requests. To add an authenticated account for use with Service Management, use the +`Add-AzureAccount` cmdlet from the Azure PowerShell module. If no context is found for the current +user, the user's context list is populated with a context for each of their first 25 subscriptions. +The list of contexts created for the user can be found by running `Get-AzContext -ListAvailable`. To +skip this context population, specify the **SkipContextPopulation** switch parameter. After +executing this cmdlet, you can disconnect from an Azure account using `Disconnect-AzAccount`. ## EXAMPLES -### Example 1: Use an interactive login to connect to an Azure account +### Example 1: Connect to an Azure account + +This example connects to an Azure account. You must provide a Microsoft account or organizational ID +credentials. If multi-factor authentication is enabled for your credentials, you must log in using +the interactive option or use service principal authentication. + ```powershell -PS C:\> Connect-AzAccount +Connect-AzAccount +``` +```Output Account SubscriptionName TenantId Environment ------- ---------------- -------- ----------- azureuser@contoso.com Subscription1 xxxx-xxxx-xxxx-xxxx AzureCloud ``` -This command connects to an Azure account. -To run Azure Resource Manager cmdlets with this account, you must provide Microsoft account or organizational ID credentials at the prompt. -If multi-factor authentication is enabled for your credentials, you must log in using the interactive option or use service principal authentication. +### Example 2: (Windows PowerShell 5.1 only) Connect to Azure using organizational ID credentials + +This scenario works only in Windows PowerShell 5.1. The first command prompts for user credentials +and stores them in the `$Credential` variable. The second command connects to an Azure account using +the credentials stored in `$Credential`. This account authenticates with Azure using organizational +ID credentials. -### Example 2: (Windows PowerShell 5.1 only) Connect to an Azure account using organizational ID credentials ```powershell -PS C:\> $Credential = Get-Credential -PS C:\> Connect-AzAccount -Credential $Credential +$Credential = Get-Credential +Connect-AzAccount -Credential $Credential +``` +```Output Account SubscriptionName TenantId Environment ------- ---------------- -------- ----------- azureuser@contoso.com Subscription1 xxxx-xxxx-xxxx-xxxx AzureCloud ``` -This scenario works only in Windows PowerShell 5.1. The first command will prompt for user credentials (username and password), and then stores them in the $Credential variable. -The second command connects to an Azure account using the credentials stored in $Credential. -This account authenticates with Azure Resource Manager using organizational ID credentials. -You cannot use multi-factor authentication or Microsoft account credentials to run Azure Resource Manager cmdlets with this account. +### Example 3: Connect to Azure using a service principal account + +The first command prompts for service principal credentials and stores them in the `$Credential` +variable. Enter your application ID for the username and service principal secret as the password +when prompted. The second command connects the specified Azure tenant using the service principal +credentials stored in the `$Credential` variable. The **ServicePrincipal** switch parameter +indicates that the account authenticates as a service principal. -### Example 3: Connect to an Azure service principal account ```powershell -PS C:\> $Credential = Get-Credential -PS C:\> Connect-AzAccount -Credential $Credential -Tenant "xxxx-xxxx-xxxx-xxxx" -ServicePrincipal +$Credential = Get-Credential +Connect-AzAccount -Credential $Credential -Tenant 'xxxx-xxxx-xxxx-xxxx' -ServicePrincipal +``` +```Output Account SubscriptionName TenantId Environment ------- ---------------- -------- ----------- xxxx-xxxx-xxxx-xxxx Subscription1 xxxx-xxxx-xxxx-xxxx AzureCloud ``` -The first command gets the service principal credentials (application id and service principal secret), and then stores them in the $Credential variable. -The second command connect to Azure using the service principal credentials stored in $Credential for the specified Tenant. -The ServicePrincipal switch parameter indicates that the account authenticates as a service principal. +### Example 4: Use an interactive login to connect to a specific tenant and subscription + +This example connects to an Azure account with the specified tenant and subscription. -### Example 4: Use an interactive login to connect to an account for a specific tenant and subscription ```powershell -PS C:\> Connect-AzAccount -Tenant "xxxx-xxxx-xxxx-xxxx" -SubscriptionId "yyyy-yyyy-yyyy-yyyy" +Connect-AzAccount -Tenant 'xxxx-xxxx-xxxx-xxxx' -SubscriptionId 'yyyy-yyyy-yyyy-yyyy' +``` +```Output Account SubscriptionName TenantId Environment ------- ---------------- -------- ----------- azureuser@contoso.com Subscription1 xxxx-xxxx-xxxx-xxxx AzureCloud ``` -This command connects to an Azure account and configured AzureRM PowerShell to run cmdlets for the specified tenant and subscription by default. +### Example 5: Connect using a Managed Service Identity + +This example connects using the Managed Service Identity (MSI) of the host environment. For example, +you sign into Azure from a virtual machine that has an assigned MSI. -### Example 5: Add an Account Using Managed Service Identity Login ```powershell -PS C:\> Connect-AzAccount -Identity +Connect-AzAccount -Identity +``` +```Output Account SubscriptionName TenantId Environment ------- ---------------- -------- ----------- MSI@50342 Subscription1 xxxx-xxxx-xxxx-xxxx AzureCloud ``` -This command connects using the managed service identity of the host environment (for example, if executed on a -VirtualMachine with an assigned Managed Service Identity, this will allow the code to login using that assigned identity) +### Example 6: Connect using Managed Service Identity login and ClientId -### Example 6: Add an Account Using Managed Service Identity Login and ClientId -```powershell -PS C:\> $identity = Get-AzUserAssignedIdentity -ResourceGroupName "myResourceGroup" -Name "myUserAssignedIdentity" -PS C:\> Get-AzVM -ResourceGroupName contoso -Name testvm | Update-AzVM -IdentityType UserAssigned -IdentityId $identity.Id -PS C:\> Connect-AzAccount -Identity -AccountId $identity.ClientId # Run on the "testvm" virtual machine +This example connects using the Managed Service Identity of **myUserAssignedIdentity**. It adds the +user assigned identity to the virtual machine, then connects using the ClientId of the user assigned +identity. For more information, see +[Configure managed identities for Azure resources on an Azure VM](/azure/active-directory/managed-identities-azure-resources/qs-configure-powershell-windows-vm). -Account SubscriptionName TenantId Environment -------- ---------------- -------- ----------- -yyyy-yyyy-yyyy-yyyy Subscription1 xxxx-xxxx-xxxx-xxxx AzureCloud -``` - -This command connects using the managed service identity of "myUserAssignedIdentity" by adding the User Assigned Identity to the Virtual Machine, then connecting using the ClientId of the User Assigned Identity. -More information about configuring Managed Identities can be found here: https://docs.microsoft.com/en-us/azure/active-directory/managed-identities-azure-resources/qs-configure-powershell-windows-vm. - -### Example 7: Add an Account Using Managed Service Identity Login and ClientId ```powershell -PS C:\> $identity = Get-AzUserAssignedIdentity -ResourceGroupName "myResourceGroup" -Name "myUserAssignedIdentity" -PS C:\> Get-AzVM -ResourceGroupName contoso -Name testvm | Update-AzVM -IdentityType UserAssigned -IdentityId $identity.Id -PS C:\> Connect-AzAccount -Identity -AccountId $identity.Id # Run on the "testvm" virtual machine +$identity = Get-AzUserAssignedIdentity -ResourceGroupName 'myResourceGroup' -Name 'myUserAssignedIdentity' +Get-AzVM -ResourceGroupName contoso -Name testvm | Update-AzVM -IdentityType UserAssigned -IdentityId $identity.Id +Connect-AzAccount -Identity -AccountId $identity.ClientId # Run on the virtual machine +``` +```Output Account SubscriptionName TenantId Environment ------- ---------------- -------- ----------- yyyy-yyyy-yyyy-yyyy Subscription1 xxxx-xxxx-xxxx-xxxx AzureCloud ``` -This command connects using the managed service identity of "myUserAssignedIdentity" by adding the User Assigned Identity to the Virtual Machine, then connecting using the Id of the User Assigned Identity. -More information about configuring Managed Identities can be found here: https://docs.microsoft.com/en-us/azure/active-directory/managed-identities-azure-resources/qs-configure-powershell-windows-vm. +### Example 7: Connect using certificates + +This example connects to an Azure account using certificate-based service principal authentication. +The service principal used for authentication must be created with the specified certificate. For +more information on creating a self-signed certificates and assigning them permissions, see +[Use Azure PowerShell to create a service principal with a certificate](/azure/active-directory/develop/howto-authenticate-service-principal-powershell) -### Example 8: Add an account using certificates ```powershell -# For more information on creating a self-signed certificate -# and giving it proper permissions, please see the following: -# https://docs.microsoft.com/en-us/azure/active-directory/develop/howto-authenticate-service-principal-powershell -PS C:\> $Thumbprint = "0SZTNJ34TCCMUJ5MJZGR8XQD3S0RVHJBA33Z8ZXV" -PS C:\> $TenantId = "4cd76576-b611-43d0-8f2b-adcb139531bf" -PS C:\> $ApplicationId = "3794a65a-e4e4-493d-ac1d-f04308d712dd" -PS C:\> Connect-AzAccount -CertificateThumbprint $Thumbprint -ApplicationId $ApplicationId -Tenant $TenantId -ServicePrincipal +$Thumbprint = '0SZTNJ34TCCMUJ5MJZGR8XQD3S0RVHJBA33Z8ZXV' +$TenantId = '4cd76576-b611-43d0-8f2b-adcb139531bf' +$ApplicationId = '3794a65a-e4e4-493d-ac1d-f04308d712dd' +Connect-AzAccount -CertificateThumbprint $Thumbprint -ApplicationId $ApplicationId -Tenant $TenantId -ServicePrincipal +``` +```Output Account SubscriptionName TenantId Environment ------- ---------------- -------- ----------- xxxx-xxxx-xxxx-xxxx Subscription1 xxxx-xxxx-xxxx-xxxx AzureCloud @@ -183,32 +208,17 @@ TenantId : 4cd76576-b611-43d0-8f2b-adcb139531bf Environment : AzureCloud ``` -This command connects to an Azure account using certificate-based service principal authentication. The service principal used for authentication should have been created with the given certificate. - -### Example 9: Add an account using AccessToken authentication -```powershell -PS C:\> $url = "https://login.windows.net//oauth2/token" -PS C:\> $body = "grant_type=refresh_token&refresh_token=" # Refresh token obtained from ~/.azure/TokenCache.dat -PS C:\> $response = Invoke-RestMethod $url -Method POST -Body $body -PS C:\> $AccessToken = $response.access_token -PS C:\> $body1 = $body + "&resource=https%3A%2F%2Fvault.azure.net" -PS C:\> $response = Invoke-RestMethod $url -Method POST -Body $body1 -PS C:\> $body2 = $body + "&resource=https%3A%2F%2Fgraph.windows.net" -PS C:\> $GraphAccessToken = $response.access_token -PS C:\> Connect-AzAccount -AccountId "azureuser@contoso.com" -AccessToken $AccessToken -KeyVaultAccessToken $KeyVaultAccessToken -GraphAccessToken $GraphAccessToken -Tenant "xxxx-xxxx-xxxx-xxxx" -SubscriptionId "yyyy-yyyy-yyyy-yyyy" - -Account SubscriptionName TenantId Environment -------- ---------------- -------- ----------- -azureuser@contoso.com Subscription1 xxxx-xxxx-xxxx-xxxx AzureCloud -``` - -This command connects to an Azure account specified in "AccountId" using the AccessToken and KeyVaultAccessToken provided. - ## PARAMETERS ### -AccessToken + Specifies an access token. +> [!CAUTION] +> Access tokens are a type of credential. You should take the appropriate security precautions to +> keep them confidential. Access tokens also timeout and may prevent long running tasks from +> completing. + ```yaml Type: System.String Parameter Sets: AccessTokenWithSubscriptionId @@ -222,8 +232,10 @@ Accept wildcard characters: False ``` ### -AccountId -Account Id for access token in AccessToken parameter set. -Account Id for managed service in ManagedService parameter set. Can be a managed service resource Id, or the associated client id. To use the SystemAssigned identity, leave this field blank. + +Account ID for access token in **AccessToken** parameter set. Account ID for managed service in +**ManagedService** parameter set. Can be a managed service resource ID, or the associated client ID. +To use the system assigned identity, leave this field blank. ```yaml Type: System.String @@ -250,7 +262,8 @@ Accept wildcard characters: False ``` ### -ApplicationId -SPN + +Application ID of the service principal. ```yaml Type: System.String @@ -265,7 +278,8 @@ Accept wildcard characters: False ``` ### -CertificateThumbprint -Certificate Hash (Thumbprint) + +Certificate Hash or Thumbprint. ```yaml Type: System.String @@ -280,7 +294,9 @@ Accept wildcard characters: False ``` ### -ContextName -Name of the default context from this login. You will be able to select this context by this name after login. + +Name of the default Azure context for this login. For more information about Azure contexts, see +[Azure PowerShell context objects](/powershell/azure/context-persistence). ```yaml Type: System.String @@ -295,9 +311,10 @@ Accept wildcard characters: False ``` ### -Credential -Specifies a PSCredential object. -For more information about the PSCredential object, type Get-Help Get-Credential. -The PSCredential object provides the user ID and password for organizational ID credentials, or the application ID and secret for service principal credentials. + +Specifies a **PSCredential** object. For more information about the **PSCredential** object, type +`Get-Help Get-Credential`. The **PSCredential** object provides the user ID and password for +organizational ID credentials, or the application ID and secret for service principal credentials. ```yaml Type: System.Management.Automation.PSCredential @@ -312,7 +329,8 @@ Accept wildcard characters: False ``` ### -DefaultProfile -The credentials, account, tenant, and subscription used for communication with azure. + +The credentials, account, tenant, and subscription used for communication with Azure. ```yaml Type: Microsoft.Azure.Commands.Common.Authentication.Abstractions.Core.IAzureContextContainer @@ -327,7 +345,8 @@ Accept wildcard characters: False ``` ### -Environment -Environment containing the account to log into + +Environment containing the Azure account. ```yaml Type: System.String @@ -342,7 +361,8 @@ Accept wildcard characters: False ``` ### -Force -Overwrite the existing context with the same name, if any. + +Overwrite the existing context with the same name without prompting. ```yaml Type: System.Management.Automation.SwitchParameter @@ -357,7 +377,8 @@ Accept wildcard characters: False ``` ### -GraphAccessToken -AccessToken for Graph Service + +AccessToken for Graph Service. ```yaml Type: System.String @@ -372,7 +393,8 @@ Accept wildcard characters: False ``` ### -Identity -Login using managed service identity in the current environment. + +Login using a Managed Service Identity. ```yaml Type: System.Management.Automation.SwitchParameter @@ -387,7 +409,8 @@ Accept wildcard characters: False ``` ### -KeyVaultAccessToken -AccessToken for KeyVault Service + +AccessToken for KeyVault Service. ```yaml Type: System.String @@ -402,7 +425,8 @@ Accept wildcard characters: False ``` ### -ManagedServiceHostName -Host name for managed service login + +Host name for the managed service. ```yaml Type: System.String @@ -417,7 +441,8 @@ Accept wildcard characters: False ``` ### -ManagedServicePort -Port number for managed service login + +Port number for the managed service. ```yaml Type: System.Int32 @@ -432,7 +457,8 @@ Accept wildcard characters: False ``` ### -ManagedServiceSecret -Secret, used for some kinds of managed service login. + +Token for the managed service login. ```yaml Type: System.Security.SecureString @@ -447,7 +473,9 @@ Accept wildcard characters: False ``` ### -Scope -Determines the scope of context changes, for example, whether changes apply only to the current process, or to all sessions started by this user. + +Determines the scope of context changes, for example, whether changes apply only to the current +process, or to all sessions started by this user. ```yaml Type: Microsoft.Azure.Commands.Profile.Common.ContextModificationScope @@ -463,6 +491,7 @@ Accept wildcard characters: False ``` ### -ServicePrincipal + Indicates that this account authenticates by providing service principal credentials. ```yaml @@ -490,6 +519,7 @@ Accept wildcard characters: False ``` ### -SkipContextPopulation + Skips context population if no contexts are found. ```yaml @@ -505,7 +535,8 @@ Accept wildcard characters: False ``` ### -SkipValidation -Skip validation for access token + +Skip validation for access token. ```yaml Type: System.Management.Automation.SwitchParameter @@ -520,7 +551,8 @@ Accept wildcard characters: False ``` ### -Subscription -Subscription Name or ID + +Subscription Name or ID. ```yaml Type: System.String @@ -535,7 +567,12 @@ Accept wildcard characters: False ``` ### -Tenant -Optional tenant name or ID + +Optional tenant name or ID. + +> [!NOTE] +> Due to limitations of the current API, you must use a tenant ID instead of a tenant name when +> connecting with a business-to-business (B2B) account. ```yaml Type: System.String @@ -562,7 +599,9 @@ Accept wildcard characters: False ``` ### -UseDeviceAuthentication -Use device code authentication instead of a browser control + +Use device code authentication instead of a browser control. This is the default authentication type +for PowerShell version 6 and higher. ```yaml Type: System.Management.Automation.SwitchParameter @@ -577,6 +616,7 @@ Accept wildcard characters: False ``` ### -Confirm + Prompts you for confirmation before running the cmdlet. ```yaml @@ -592,6 +632,7 @@ Accept wildcard characters: False ``` ### -WhatIf + Shows what would happen if the cmdlet runs. The cmdlet is not run. ```yaml @@ -607,7 +648,11 @@ Accept wildcard characters: False ``` ### CommonParameters -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, +-WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](/powershell/module/microsoft.powershell.core/about/about_commonparameters). +(http://go.microsoft.com/fwlink/?LinkID=113216). ## INPUTS