Merge pull request #214722 from cilwerner/content-health-1

[msid][content-health] howto-create-self-signed-certificate.md (ADO-1999950)

Author: BCS2022

articles/active-directory/develop/howto-create-self-signed-certificate.md

@@ -9,27 +9,27 @@ ms.service: active-directory
 ms.subservice: develop
 ms.topic: conceptual
 ms.workload: identity
-ms.date: 08/10/2021
+ms.date: 10/17/2022
 ms.author: henrymbugua
 ms.reviewer: jmprieur, saeeda, sureshja, ludwignick
-ms.custom: scenarios:getting-started
+ms.custom: scenarios:getting-started, engagement-fy23
 #Customer intent: As an application developer, I want to understand the basic concepts of authentication and authorization in the Microsoft identity platform.
 ---
 
 # Create a self-signed public certificate to authenticate your application
 
-Azure Active Directory (Azure AD) supports two types of authentication for service principals: **password-based authentication** (app secret) and **certificate-based authentication**. While app secrets can easily be created in the Azure portal, it's recommended that your application uses a certificate.
+Azure Active Directory (Azure AD) supports two types of authentication for service principals: **password-based authentication** (app secret) and **certificate-based authentication**. While app secrets can easily be created in the Azure portal, they're long-lived, and not as secure as certificates. It's therefore recommended that your application uses a certificate rather than a secret.
 
-For testing, you can use a self-signed public certificate instead of a Certificate Authority (CA)-signed certificate. This article shows you how to use Windows PowerShell to create and export a self-signed certificate.
+For testing, you can use a self-signed public certificate instead of a Certificate Authority (CA)-signed certificate. In this how-to, you'll use Windows PowerShell to create and export a self-signed certificate.
 
 > [!CAUTION]
 > Self-signed certificates are not trusted by default and they can be difficult to maintain. Also, they may use outdated hash and cipher suites that may not be strong. For better security, purchase a certificate signed by a well-known certificate authority.
 
-You configure various parameters for the certificate. For example, the cryptographic and hash algorithms, the certificate validity period, and your domain name. Then export the certificate with or without its private key depending on your application needs. 
+While creating the certificate using PowerShell, you can specify parameters like cryptographic and hash algorithms, certificate validity period, and domain name. The certificate can then be exported with or without its private key depending on your application needs. 
 
-The application that initiates the authentication session requires the private key while the application that confirms the authentication requires the public key. So, if you're authenticating from your PowerShell desktop app to Azure AD, you only export the public key (`.cer` file) and upload it to the Azure portal. Your PowerShell app uses the private key from your local certificate store to initiate authentication and obtain access tokens for Microsoft Graph.
+The application that initiates the authentication session requires the private key while the application that confirms the authentication requires the public key. So, if you're authenticating from your PowerShell desktop app to Azure AD, you only export the public key (*.cer* file) and upload it to the Azure portal. The PowerShell app uses the private key from your local certificate store to initiate authentication and obtain access tokens for Microsoft Graph.
 
-Your application may also be running from another machine, such as Azure Automation. In this scenario, you export the public and private key pair from your local certificate store, upload the public key to the Azure portal, and the private key (a `.pfx` file) to Azure Automation. Your application running in Azure Automation will use the private key to initiate authentication and obtain access tokens for Microsoft Graph.
+Your application may also be running from another machine, such as Azure Automation. In this scenario, you export the public and private key pair from your local certificate store, upload the public key to the Azure portal, and the private key (a *.pfx* file) to Azure Automation. Your application running in Azure Automation will use the private key to initiate authentication and obtain access tokens for Microsoft Graph.
 
 This article uses the `New-SelfSignedCertificate` PowerShell cmdlet to create the self-signed certificate and the `Export-Certificate` cmdlet to export it to a location that is easily accessible. These cmdlets are built-in to modern versions of Windows (Windows 8.1 and greater, and Windows Server 2012R2 and greater). The self-signed certificate will have the following configuration:
 
@@ -39,11 +39,10 @@ This article uses the `New-SelfSignedCertificate` PowerShell cmdlet to create th
 + The certificate is valid for only one year.
 + The certificate is supported for use for both client and server authentication.
 
-> [!NOTE]
-> To customize the start and expiry date as well as other properties of the certificate, see the [`New-SelfSignedCertificate` reference](/powershell/module/pki/new-selfsignedcertificate?view=windowsserver2019-ps&preserve-view=true).
+To customize the start and expiry date and other properties of the certificate, refer to [New-SelfSignedCertificate](/powershell/module/pki/new-selfsignedcertificate?view=windowsserver2019-ps&preserve-view=true).
 
 
-## Option 1:  Create and export your public certificate without a private key
+## Create and export your public certificate
 
 Use the certificate you create using this method to authenticate from an application running from your machine. For example, authenticate from Windows PowerShell.
 
@@ -55,7 +54,7 @@ $cert = New-SelfSignedCertificate -Subject "CN=$certname" -CertStoreLocation "Ce
 
 ```
 
-The **$cert** variable in the previous command stores your certificate in the current session and allows you to export it. The command below exports the certificate in `.cer` format. You can also export it in other formats supported on the Azure portal including `.pem` and `.crt`.
+The `$cert` variable in the previous command stores your certificate in the current session and allows you to export it. The command below exports the certificate in *.cer* format. You can also export it in other formats supported on the Azure portal including *.pem* and *.crt*.
 
 ```powershell
 
@@ -65,50 +64,32 @@ Export-Certificate -Cert $cert -FilePath "C:\Users\admin\Desktop\$certname.cer"
 
 Your certificate is now ready to upload to the Azure portal. Once uploaded, retrieve the certificate thumbprint for use to authenticate your application.
 
+## (Optional): Export your public certificate with its private key
 
-## Option 2: Create and export your public certificate with its private key
+If your application will be running from another machine or cloud, such as Azure Automation, you'll also need a private key.
 
-Use this option to create a certificate and its private key if your application will be running from another machine or cloud, such as Azure Automation.
-
-In an elevated PowerShell prompt, run the following command and leave the PowerShell console session open. Replace `{certificateName}` with name that you wish to give your certificate.
-
-```powershell
-$certname = "{certificateName}"    ## Replace {certificateName}
-$cert = New-SelfSignedCertificate -Subject "CN=$certname" -CertStoreLocation "Cert:\CurrentUser\My" -KeyExportPolicy Exportable -KeySpec Signature -KeyLength 2048 -KeyAlgorithm RSA -HashAlgorithm SHA256
-
-```
-
-The **$cert** variable in the previous command stores your certificate in the current session and allows you to export it. The command below exports the certificate in `.cer` format. You can also export it in other formats supported on the Azure portal including `.pem` and `.crt`.
-
-
-```powershell
-
-Export-Certificate -Cert $cert -FilePath "C:\Users\admin\Desktop\$certname.cer"   ## Specify your preferred location
-
-```
-
-Still in the same session, create a password for your certificate private key and save it in a variable. In the following command, replace `{myPassword}` with the password that you wish to use to protect your certificate private key.
+Following on from the previous commands, create a password for your certificate private key and save it in a variable. Replace `{myPassword}` with the password that you wish to use to protect your certificate private key.
 
 ```powershell
 
 $mypwd = ConvertTo-SecureString -String "{myPassword}" -Force -AsPlainText  ## Replace {myPassword}
 
 ```
 
-Now, using the password you stored in the `$mypwd` variable, secure, and export your private key.
+Using the password you stored in the `$mypwd` variable, secure and export your private key using the command;
 
 ```powershell
 
 Export-PfxCertificate -Cert $cert -FilePath "C:\Users\admin\Desktop\$certname.pfx" -Password $mypwd   ## Specify your preferred location
 
 ```
 
-Your certificate (`.cer` file) is now ready to upload to the Azure portal. You also have a private key (`.pfx` file) that is encrypted and can't be read by other parties. Once uploaded, retrieve the certificate thumbprint for use to authenticate your application.
+Your certificate (*.cer* file) is now ready to upload to the Azure portal. The private key (*.pfx* file) is encrypted and can't be read by other parties. Once uploaded, retrieve the certificate thumbprint, which you can use to authenticate your application.
 
 
 ## Optional task: Delete the certificate from the keystore.
 
-If you created the certificate using Option 2, you can delete the key pair from your personal store. First, run the following command to retrieve the certificate thumbprint.
+You can delete the key pair from your personal store by running the following command to retrieve the certificate thumbprint.
 
 ```powershell