Skip to content

Commit a445f24

Browse files
mikefrobbinsmikefrobbins
authored
Recreated conceptual docs folder for azps 4.2.0 (MicrosoftDocs#1445)
1 parent d76488e commit a445f24

22 files changed

+8529
-0
lines changed

‎docs-conceptual/azps-4.2.0/authenticate-azureps.md

Lines changed: 189 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,189 @@
1+
---
2+
title: Sign in with Azure PowerShell
3+
description: How to sign in with Azure PowerShell as a user, service principal, or with managed identities for Azure resources.
4+
ms.devlang: powershell
5+
ms.topic: conceptual
6+
ms.date: 06/18/2020
7+
---
8+
# Sign in with Azure PowerShell
9+
10+
Azure PowerShell supports several authentication methods. The easiest way to get started is with
11+
[Azure Cloud Shell](/azure/cloud-shell/overview), which automatically logs you in. With a local
12+
install, you can sign in interactively through your browser. When writing scripts for automation,
13+
the recommended approach is to use a [service principal](create-azure-service-principal-azureps.md)
14+
with the necessary permissions. When you restrict sign-in permissions as much as possible for your
15+
use case, you help keep your Azure resources secure.
16+
17+
After signing in, commands are run against your default subscription. To change your active
18+
subscription for a session, use the [Set-AzContext](/powershell/module/az.accounts/set-azcontext)
19+
cmdlet. To change the default subscription used when logging in with Azure PowerShell, use
20+
[Set-AzDefault](/powershell/module/az.accounts/set-azdefault).
21+
22+
> [!IMPORTANT]
23+
> Your credentials are shared among multiple PowerShell sessions as long as you remain signed in.
24+
> For more information, see the article on [Persistent Credentials](context-persistence.md).
25+
26+
## Sign in interactively
27+
28+
To sign in interactively, use the
29+
[Connect-AzAccount](/powershell/module/az.accounts/connect-azaccount) cmdlet.
30+
31+
```azurepowershell-interactive
32+
Connect-AzAccount
33+
```
34+
35+
When run from PowerShell version 6 and higher, this cmdlet presents a token string. To sign in, copy
36+
this string and paste it into [microsoft.com/devicelogin](https://microsoft.com/devicelogin) in a
37+
web browser. Your PowerShell session will be authenticated to connect to Azure. You can specify the
38+
`UseDeviceAuthentication` parameter to receive a token string on Windows PowerShell.
39+
40+
> [!IMPORTANT]
41+
> Username/password credential authorization has been removed in Azure PowerShell due to changes in
42+
> Active Directory authorization implementations and security concerns. If you use credential
43+
> authorization for automation purposes, instead
44+
> [create a service principal](create-azure-service-principal-azureps.md).
45+
46+
Use the [Get-AzContext](/powershell/module/az.accounts/get-azcontext) cmdlet to store your tenant ID
47+
in a variable to be used in the next two sections of this article.
48+
49+
```azurepowershell-interactive
50+
$tenantId = (Get-AzContext).Tenant.Id
51+
```
52+
53+
## Sign in with a service principal <a name="sp-signin"/>
54+
55+
Service principals are non-interactive Azure accounts. Like other user accounts, their permissions
56+
are managed with Azure Active Directory. By granting a service principal only the permissions it
57+
needs, your automation scripts stay secure.
58+
59+
To learn how to create a service principal for use with Azure PowerShell, see
60+
[Create an Azure service principal with Azure PowerShell](create-azure-service-principal-azureps.md).
61+
62+
To sign in with a service principal, use the `-ServicePrincipal` argument with the
63+
`Connect-AzAccount` cmdlet. You'll also need the service principal's application ID, sign-in
64+
credentials, and the tenant ID associate with the service principal. How you sign in with a service
65+
principal depends on whether it's configured for password-based or certificate-based
66+
authentication.
67+
68+
### Password-based authentication
69+
70+
Create a service principal to be used in the examples in this section. For more information on
71+
creating service principals, see
72+
[Create an Azure service principal with Azure PowerShell](/powershell/azure/create-azure-service-principal-azureps).
73+
74+
```azurepowershell-interactive
75+
$sp = New-AzADServicePrincipal -DisplayName ServicePrincipalName
76+
```
77+
78+
To get the service principal's credentials as the appropriate object, use the
79+
[Get-Credential](/powershell/module/microsoft.powershell.security/get-credential) cmdlet. This
80+
cmdlet presents a prompt for a username and password. Use the service principal's `applicationID`
81+
for the username and convert its `secret` to plain text for the password.
82+
83+
```azurepowershell-interactive
84+
# Retrieve the plain text password for use with `Get-Credential` in the next command.
85+
$sp.secret | ConvertFrom-SecureString -AsPlainText
86+
87+
$pscredential = Get-Credential -UserName $sp.ApplicationId
88+
Connect-AzAccount -ServicePrincipal -Credential $pscredential -Tenant $tenantId
89+
```
90+
91+
For automation scenarios, you need to create credentials from a service principal's `applicationId`
92+
and `secret`:
93+
94+
```azurepowershell-interactive
95+
$pscredential = New-Object -TypeName System.Management.Automation.PSCredential($sp.ApplicationId, $sp.Secret)
96+
Connect-AzAccount -ServicePrincipal -Credential $pscredential -Tenant $tenantId
97+
```
98+
99+
Make sure that you use good password storage practices when automating service principal connections.
100+
101+
### Certificate-based authentication
102+
103+
Certificate-based authentication requires that Azure PowerShell can retrieve information from a
104+
local certificate store based on a certificate thumbprint.
105+
106+
```azurepowershell-interactive
107+
Connect-AzAccount -ApplicationId $appId -Tenant $tenantId -CertificateThumbprint <thumbprint>
108+
```
109+
110+
When using a service principal instead of a registered application, add the `-ServicePrincipal` argument
111+
and provide the service principal's Application ID as the `-ApplicationId` parameter's value.
112+
113+
```azurepowershell-interactive
114+
Connect-AzAccount -ServicePrincipal -ApplicationId $servicePrincipalId -Tenant $tenantId -CertificateThumbprint <thumbprint>
115+
```
116+
117+
In PowerShell 5.1, the certificate store can be managed and inspected with the
118+
[PKI](/powershell/module/pkiclient) module. For PowerShell Core 6.x and later, the process is more
119+
complicated. The following scripts show you how to import an existing certificate into the
120+
certificate store accessible by PowerShell.
121+
122+
#### Import a certificate in PowerShell 5.1
123+
124+
```azurepowershell-interactive
125+
# Import a PFX
126+
$credentials = Get-Credential -Message "Provide PFX private key password"
127+
Import-PfxCertificate -FilePath <path to certificate> -Password $credentials.Password -CertStoreLocation cert:\CurrentUser\My
128+
```
129+
130+
#### Import a certificate in PowerShell Core 6.x and later
131+
132+
```azurepowershell-interactive
133+
# Import a PFX
134+
$storeName = [System.Security.Cryptography.X509Certificates.StoreName]::My
135+
$storeLocation = [System.Security.Cryptography.X509Certificates.StoreLocation]::CurrentUser
136+
$store = [System.Security.Cryptography.X509Certificates.X509Store]::new($storeName, $storeLocation)
137+
$certPath = <path to certificate>
138+
$credentials = Get-Credential -Message "Provide PFX private key password"
139+
$flag = [System.Security.Cryptography.X509Certificates.X509KeyStorageFlags]::Exportable
140+
$certificate = [System.Security.Cryptography.X509Certificates.X509Certificate2]::new($certPath, $credentials.Password, $flag)
141+
$store.Open([System.Security.Cryptography.X509Certificates.OpenFlags]::ReadWrite)
142+
$store.Add($Certificate)
143+
$store.Close()
144+
```
145+
146+
## Sign in using a managed identity
147+
148+
Managed identities are a feature of Azure Active Directory. Managed identities are service
149+
principals assigned to resources that run in Azure. You can use a managed identity service principal
150+
for sign-in, and acquire an app-only access token to access other resources. Managed identities are
151+
only available on resources running in an Azure cloud.
152+
153+
This example connects using the managed identity of the host environment. For example, if executed
154+
on a VirtualMachine with an assigned Managed Service Identity, this allows the code to sign in using
155+
that assigned identity.
156+
157+
```azurepowershell-interactive
158+
Connect-AzAccount -Identity
159+
```
160+
161+
## Sign in with a non-default tenant or as a Cloud Solution Provider (CSP)
162+
163+
If your account is associated with more than one tenant, sign-in requires the `-Tenant` parameter to
164+
be specified when connecting. This parameter works with any sign-in method. When logging in, this
165+
parameter value can either be the Azure object ID of the tenant (Tenant ID) or the fully qualified
166+
domain name of the tenant.
167+
168+
If you're a [Cloud Solution Provider (CSP)](https://azure.microsoft.com/offers/ms-azr-0145p/), the
169+
`-Tenant` value **must** be a tenant ID.
170+
171+
```azurepowershell-interactive
172+
Connect-AzAccount -Tenant 'xxxx-xxxx-xxxx-xxxx'
173+
```
174+
175+
## Sign in to another Cloud
176+
177+
Azure cloud services offer environments compliant with regional data-handling laws. For accounts in
178+
a regional cloud, set the environment when you sign in with the `-Environment` argument. This
179+
parameter works with any sign-in method. For example, if your account is in the China cloud:
180+
181+
```azurepowershell-interactive
182+
Connect-AzAccount -Environment AzureChinaCloud
183+
```
184+
185+
The following command gets a list of available environments:
186+
187+
```azurepowershell-interactive
188+
Get-AzEnvironment | Select-Object -Property Name
189+
```

‎docs-conceptual/azps-4.2.0/azureps-in-docker.md

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
---
2+
title: Using Azure PowerShell in Docker
3+
description: How to use Azure PowerShell that is preinstalled in a Docker image.
4+
ms.devlang: powershell
5+
ms.topic: conceptual
6+
ms.date: 03/20/2020
7+
---
8+
9+
# Using Azure PowerShell in Docker
10+
11+
We are publishing Docker images with Azure PowerShell preinstalled. This article shows you how to
12+
get started using Azure PowerShell in the Docker container.
13+
14+
## Finding available images
15+
16+
The released images require Docker 17.05 or newer. It is also expected that you are able to run
17+
Docker without `sudo` or local administrative rights. Please follow Docker's official
18+
[instructions][install] to install `docker` correctly.
19+
20+
The latest container image contains the latest version of PowerShell and the latest Azure PowerShell
21+
modules supported with the Az module.
22+
23+
For each new release of the Az module we are releasing an image for the following operating systems:
24+
25+
- Ubuntu 18.04 (default)
26+
- Debian 9
27+
- CentOs 7
28+
29+
A full list of available images can be found on our [Docker image][az image] page.
30+
31+
## Using Azure PowerShell in a container
32+
33+
The following steps show the Docker commands required to download the image and start an interactive
34+
PowerShell session.
35+
36+
1. Download the latest azure-powershell image.
37+
38+
```console
39+
docker pull mcr.microsoft.com/azure-powershell
40+
```
41+
42+
1. Run the azure-powershell container in interactive mode:
43+
44+
```console
45+
docker run -it mcr.microsoft.com/azure-powershell pwsh
46+
```
47+
48+
For Windows Docker hosts, you must enable Docker File Sharing to allow local drives on Windows to be shared with Linux containers. For more information see [Get started with Docker for Windows][file-sharing].
49+
50+
### Run the azure-powershell container interactively using host authentication
51+
52+
If you have Azure PowerShell already installed on the system hosting Docker, you may have cached
53+
Azure credentials. These credentials can be used in the PowerShell session running in the Docker
54+
container.
55+
56+
By default, the cached credentials are in `$HOME/.Azure` directory on your host. The Docker service
57+
must have access to this location to access the credentials. The following command starts the
58+
container with the credential cache mounted and starts an interactive PowerShell session.
59+
60+
```console
61+
docker run -it -v ~/.Azure/AzureRmContext.json:/root/.Azure/AzureRmContext.json -v ~/.Azure/TokenCache.dat:/root/.Azure/TokenCache.dat mcr.microsoft.com/azure-powershell pwsh
62+
```
63+
64+
### Remove the image when no longer needed
65+
66+
The following command is used to delete the Docker container when you no longer need it.
67+
68+
```console
69+
docker rmi mcr.microsoft.com/azure-powershell
70+
```
71+
72+
## Next steps
73+
74+
To learn more about the Azure PowerShell modules and their features, see
75+
[Get Started with Azure PowerShell](get-started-azureps.md).
76+
77+
<!-- link references -->
78+
[install]: https://docs.docker.com/engine/installation/
79+
[powershell image]: https://hub.docker.com/_/microsoft-powershell
80+
[az image]: https://hub.docker.com/_/microsoft-azure-powershell
81+
[file-sharing]: https://docs.docker.com/docker-for-windows/#file-sharing

0 commit comments

Comments
 (0)