Line edits

Author: lootle1

learn-pr/azure/authenticate-azure-deployment-pipeline-service-principals/includes/1-introduction.md

@@ -1,8 +1,8 @@
-Deployment pipelines need to communicate with Azure, so they can create and configure your Azure resources. In this module, you'll learn how service principals work, how to create and manage them, and how to authorize them to work with Azure on your behalf.
+Deployment pipelines need to communicate with Azure so they can create and configure your Azure resources. In this module, you'll learn how service principals work, how to create and manage them, and how to authorize them to work with Azure on your behalf.
 
 ## Example scenario
 
-Suppose you're responsible for deploying and configuring the Azure infrastructure at a toy company. You've created a Bicep template to deploy your company's website. Until now, you've been deploying it from your own computer by using command-line tools. You've decided to move the deployment into a pipeline. 
+Suppose you're responsible for deploying and configuring the Azure infrastructure at a toy company. You've created a Bicep template to deploy your company's website. Until now, you've been deploying it from your own computer by using command-line tools. You've decided to move the deployment into a pipeline.
 
 One of your colleagues has told you that you'll need to set up a service principal for the deployment pipeline. You need to understand what this is, and then set it up so you can deploy your company's website.
 

learn-pr/azure/authenticate-azure-deployment-pipeline-service-principals/includes/2-understand-service-principals.md

@@ -2,7 +2,7 @@ Service principals provide a way to authenticate pipelines, applications, and so
 
 ## Why does a pipeline need to authenticate?
 
-When you deploy a Bicep template, you effectively ask Azure Resource Manager to create or modify your Azure resources. In this example scenario, you've created a Bicep template to deploy your toy company's website. The Bicep template declares resources that include an Azure App Service plan, an app, and an Application Insights instance. 
+When you deploy a Bicep template, you effectively ask Azure Resource Manager to create or modify your Azure resources. In this example scenario, you've created a Bicep template to deploy your toy company's website. The Bicep template declares resources that include an Azure App Service plan, an app, and an Application Insights instance.
 
 When you deploy the template, Resource Manager checks whether the resources exist. If they don't, Resource Manager creates them. If any already exist, Resource Manager ensures that their configuration matches the configuration that you specify in the template.
 
@@ -22,10 +22,10 @@ Microsoft Entra ID is the service that manages identities for Azure. Microsoft E
 
 :::image type="content" source="../media/2-security-principals.png" alt-text="Diagram that shows the four types of security principals: user, group, service principal, and managed identity." border="false":::
 
-- A *user* represents a human who usually signs in interactively by using a browser. Users often have additional security checks to perform when they sign in, such as multifactor authentication (MFA) and Conditional Access based on their location or network.
-- A *group* represents a collection of users. Groups don't authenticate directly, but they provide a convenient way to assign permissions to a set of users together.
-- A *service principal* represents an automated process or system that usually doesn't have a human directly running it.
-- A *managed identity* is a special type of service principal that's designed for situations where a human isn't involved in the authentication process.
+- A _user_ represents a human who usually signs in interactively by using a browser. Users often have additional security checks to perform when they sign in, such as multifactor authentication (MFA) and Conditional Access based on their location or network.
+- A _group_ represents a collection of users. Groups don't authenticate directly, but they provide a convenient way to assign permissions to a set of users together.
+- A _service principal_ represents an automated process or system that usually doesn't have a human directly running it.
+- A _managed identity_ is a special type of service principal that's designed for situations where a human isn't involved in the authentication process.
 
 ### Service principals
 
@@ -42,20 +42,20 @@ Managed identities are available for Azure-hosted resources like virtual machine
 When you work with pipelines, you usually can't use managed identities. This is because managed identities require that you own and manage the Azure resources that run your deployments. When you work with Azure Pipelines, you usually rely on shared infrastructure provided by Microsoft.
 
 > [!NOTE]
-> There are some situations where pipelines can use managed identities. In Azure Pipelines, you can create a _self-hosted agent_ to run your pipeline's scripts and code by using on your own Azure-based virtual machine. Because you own the virtual machine, you can assign it a managed identity and use it from your pipeline. 
+> There are some situations where pipelines can use managed identities. In Azure Pipelines, you can create a _self-hosted agent_ to run your pipeline's scripts and code by using on your own Azure-based virtual machine. Because you own the virtual machine, you can assign it a managed identity and use it from your pipeline.
 >
 > However, most of the time your pipelines run by using a _hosted agent_, which is a server that Microsoft manages. Hosted agents aren't currently compatible with managed identities.
-
+>
 > [!TIP]
 > In other parts of your solution, if you have a choice between using a managed identity or using a normal service principal, it's best to go with a managed identity. They're easier to work with and are usually more secure.
 
 ## Why can't you just use your user account?
 
 You might wonder why you need to create this whole new type of object just to authenticate a pipeline, when you have user accounts that work perfectly well.
 
-User accounts aren't designed for unattended use. The authentication process for a user account often checks that a human is the entity that's trying to sign in. Increasingly, organizations use additional security checks during authentication. These checks include MFA, CAPTCHA checks, and inspecting the device and network that the user is using so that they can verify the legitimacy of a request to sign in.
+User accounts aren't designed for unattended use. The authentication process for a user account often checks that a human is the entity that's trying to sign in. Increasingly, organizations use additional security checks during authentication. These checks include MFA, CAPTCHA checks, and inspecting the device and network that the user is using so they can verify the legitimacy of a request to sign in.
 
-Pipelines are designed to run your deployments even when no-one is actively running them. In fact, most of the benefits of pipelines come from the fact that they are completely automated and don't require human interaction. If you store your username and password in a pipeline and try to use them to sign in, they probably won't work. Even if they do seem to work, they can easily break in the future if Microsoft Entra ID or your organizational administrator adds more security checks to your user authentication process.
+Pipelines are designed to run your deployments even when no one is actively running them. In fact, most of the benefits of pipelines come from the fact that they're completely automated and don't require human interaction. If you store your username and password in a pipeline and try to use them to sign in, they probably won't work. Even if they do seem to work, they can easily break in the future if Microsoft Entra ID or your organizational administrator adds more security checks to your user authentication process.
 
 > [!WARNING]
 > It's also a bad idea to save your username and password anywhere, because someone else might get access to them and then use them to impersonate you.
@@ -64,11 +64,11 @@ For these reasons, the built-in pipeline tasks that interact with Azure don't le
 
 ## How do service principals work?
 
-You might see a few different terms in use when you work with service principals, or with tools like the Azure portal or the Microsoft Graph API. Although it's not essential to understand these terms just to use service principals in a pipeline, it is helpful to know a little about the concepts.
+You might see a few different terms in use when you work with service principals, or with tools like the Azure portal or the Microsoft Graph API. Although it's not essential to understand these terms just to use service principals in a pipeline, it's helpful to know a little about the concepts.
 
 Service principals are a feature of Microsoft Entra ID. Microsoft Entra ID is a global identity service. Many companies use Microsoft Entra ID, and each company is called a _tenant_.
 
-Microsoft Entra ID has a concept of an _application_, which represents a system, piece of software, process, or some other non-human agent. You can think of a deployment pipeline as an application. 
+Microsoft Entra ID has a concept of an _application_, which represents a system, piece of software, process, or some other non-human agent. You can think of a deployment pipeline as an application.
 
 In Microsoft Entra ID, applications can do many things that are beyond the scope of authentication and pipeline deployments. When you create an application and tell Microsoft Entra ID about it, you create an object called an _application registration_. An application registration represents the application in Microsoft Entra ID.
 

learn-pr/azure/authenticate-azure-deployment-pipeline-service-principals/includes/3-create-service-principal-key.md

@@ -2,21 +2,21 @@ Now that you understand the concept of a service principal, you might wonder how
 
 ## Understand how service principals are authenticated
 
-When a service principal needs to communicate with Azure, it signs in to Microsoft Entra ID. After Microsoft Entra ID verifies the service principal's identity, it issues a _token_ that the client application stores and uses when it makes any requests to Azure. 
+When a service principal needs to communicate with Azure, it signs in to Microsoft Entra ID. After Microsoft Entra ID verifies the service principal's identity, it issues a _token_ that the client application stores and uses when it makes any requests to Azure.
 
 Broadly speaking, this process is similar to how things work when you sign in to Azure yourself as a user. However, compared to users, service principals have a slightly different type of credential to prove their identity. Service principals use two main credentials: keys and certificates.
 
 > [!NOTE]
-> Remember that managed identities are special service principals that work within Azure. They have a different type of authentication process that doesn't require that you know or handle credentials at all.
+> Remember that managed identities are special service principals that work within Azure. They have a different type of authentication process that doesn't require you know or handle credentials at all.
 
 ### Keys
 
 Keys are similar to passwords. However, keys are much longer and more complex. In fact, for most situations, Microsoft Entra ID generates keys itself to ensure that:
 
 - The keys are _cryptographically random_. That is, they're extremely hard to guess.
-- Humans don't accidentally use weak passwords as keys. 
+- Humans don't accidentally use weak passwords as keys.
 
-Service principals often have highly privileged permissions, so it's essential that they're secure. Typically, you only need to handle the key briefly when first configuring the service principal and your pipeline. So the key doesn't need to be memorable or easy to type. 
+Service principals often have highly privileged permissions, so it's essential that they're secure. Typically, you only need to handle the key briefly when first configuring the service principal and your pipeline. So the key doesn't need to be memorable or easy to type.
 
 A single service principal can have multiple keys at the same time, but users can't have multiple passwords. Like passwords, keys have an expiration date. You'll learn more about that soon.
 
@@ -25,7 +25,7 @@ A single service principal can have multiple keys at the same time, but users ca
 
 ### Certificates
 
-Certificates are another way to authenticate service principals. They're very secure but can be hard to manage. Some organizations require the use of certificates for certain types of service principals. 
+Certificates are another way to authenticate service principals. They're very secure but can be hard to manage. Some organizations require the use of certificates for certain types of service principals.
 
 We won't discuss certificates in this module. However, if you work with a service principal that uses certificate authentication, it basically works the same way as any other service principal in terms of managing it and granting it permission for your pipeline.
 
@@ -37,15 +37,15 @@ We won't discuss certificates in this module. However, if you work with a servic
 When you create a service principal, you generally ask Azure to create a key at the same time. Azure typically generates a random key for you.
 
 > [!NOTE]
-> Remember our earlier discussion about how service principals work? Keys are stored as part of the application registration object. If you open the Azure portal, look within the Microsoft Entra configuration, and then go to the application registrations, you can create and delete keys there too.
+> Remember our earlier discussion about how service principals work? Keys are stored as part of the application registration object. If you open the Azure portal, look within the Microsoft Entra configuration, and then go to the application registrations. You can create and delete keys there too.
 
 Azure shows you the key when you create the service principal. This is the only time that Azure will ever show you the key. After that, you can't retrieve it anymore. It's important that you securely copy the key so you can use it when you configure your pipeline. Don't share the key by email or another non-secure means. If you lose a key, you must delete it and create a new one.
 
 ## Manage service principals for Azure Pipelines
 
-When you create a key for a pipeline's service principal, it's a good idea to immediately copy the key into the pipeline's configuration. That way, you avoid storing or transmitting the key unnecessarily. 
+When you create a key for a pipeline's service principal, it's a good idea to immediately copy the key into the pipeline's configuration. That way, you avoid storing or transmitting the key unnecessarily.
 
-Pipeline tools include secure ways to specify your service principal's application ID and key. Never store credentials of any kind in source control. Instead, use *service connections* when you work with Azure Pipelines. In this module, we only discuss how to create a service principal and key. You'll learn how to configure your pipeline with the key in a later module.
+Pipeline tools include secure ways to specify your service principal's application ID and key. Never store credentials of any kind in source control. Instead, use _service connections_ when you work with Azure Pipelines. In this module, we only discuss how to create a service principal and key. You'll learn how to configure your pipeline with the key in a later module.
 
 > [!TIP]
 > Azure Pipelines can create service principals for you automatically. In this module, you'll manually create and manage your service principals to gain a better understanding of what's happening. In other modules, you'll use the automatic creation method for simplicity.
@@ -108,7 +108,7 @@ Service principals have several identifiers and names that you use to identify a
 
 > [!TIP]
 > Use a clear, descriptive display name for your service principal. It's important to help your team understand what the service principal is for, so that nobody accidentally deletes it or changes its permissions.
-
+>
 > [!CAUTION]
 > A display name isn't unique. Multiple service principals might share the same display name. Be careful when you grant permissions to a service principal by using its display name to identify it. You might accidentally give permissions to the wrong service principal. It's a good practice to use the application ID instead.
 
@@ -154,17 +154,17 @@ $newKey = $newCredential.SecretText
 
 ## Manage the lifecycle of your service principal
 
-It's important to consider the whole lifecycle of each service principal that you create. When you build a service principal for a pipeline, what will happen if the pipeline is eventually deleted or is no longer used? 
+It's important to consider the whole lifecycle of each service principal that you create. When you build a service principal for a pipeline, what will happen if the pipeline is eventually deleted or is no longer used?
 
-Service principals aren't removed automatically, so you need to audit and remove old service principals. It's important to remove old service principals for the same reason that you delete old user accounts: attackers might gain access to their keys. It's best not to have credentials that aren't actively used.
+Service principals aren't removed automatically, so you need to audit and remove old ones. It's important to remove old service principals for the same reason that you delete old user accounts: attackers might gain access to their keys. It's best not to have credentials that aren't actively used.
 
 It's a good practice to document your service principals in a place that you and your team can easily access. You should include the following information for each service principal:
 
 > [!div class="checklist"]
 > * Essential identifying information, including its name and application ID.
-> * The purpose of the service principal.
-> * Who created it, who's responsible for managing it and its keys, and who might have answers if there's a problem.
-> * The permissions that it needs, and a clear justification for why it needs them.
-> * What its expected lifetime is.
+> - The purpose of the service principal.
+> - Who created it, who's responsible for managing it and its keys, and who might have answers if there's a problem.
+> - The permissions that it needs, and a clear justification for why it needs them.
+> - What its expected lifetime is.
 
 You should regularly audit your service principals to ensure that they're still being used and that the permissions they've been assigned are still correct.

learn-pr/azure/authenticate-azure-deployment-pipeline-service-principals/includes/4-exercise-create-service-principal-key.md

@@ -15,13 +15,13 @@ This exercise requires that you have permission to create applications and servi
 
 ::: zone pivot="cli"
 
-To work with service principals in Azure, you need to sign in to your Azure account from the Visual Studio Code terminal. 
+To work with service principals in Azure, you need to sign in to your Azure account from the Visual Studio Code terminal.
 
 [!include[](../../includes/azure-exercise-terminal-cli.md)]
 
 ### Sign in to Azure by using the Azure CLI
 
-1. In the Visual Studio Code terminal, sign in to Azure by running the following command: 
+1. In the Visual Studio Code terminal, sign in to Azure by running the following command:
 
     ```azurecli
     az login
@@ -33,7 +33,7 @@ To work with service principals in Azure, you need to sign in to your Azure acco
 
 ::: zone pivot="powershell"
 
-To deploy this template to Azure, sign in to your Azure account from the Visual Studio Code terminal. 
+To deploy this template to Azure, sign in to your Azure account from the Visual Studio Code terminal.
 
 [!include[](../../includes/azure-exercise-terminal-powershell.md)]
 
@@ -67,7 +67,7 @@ To deploy this template to Azure, sign in to your Azure account from the Visual
    * `password`: The service principal's key.
    * `tenant`: Your Microsoft Entra tenant ID.
 
-   Copy these values somewhere safe. You'll use them soon. 
+   Copy these values somewhere safe. You'll use them soon.
 
 ::: zone-end
 
@@ -79,9 +79,10 @@ To deploy this template to Azure, sign in to your Azure account from the Visual
    $servicePrincipal = New-AzADServicePrincipal `
      -DisplayName ToyWebsitePipeline
    ```
+
 1. Run the following command to get the service principal's key:
 
-   ```azurepowershell 
+   ```azurepowershell
    $servicePrincipalKey = $servicePrincipal.PasswordCredentials.SecretText
    ```