Skip to content

Latest commit

 

History

History
246 lines (157 loc) · 13.7 KB

README-use-certificate.md

File metadata and controls

246 lines (157 loc) · 13.7 KB
Raw

How to use certificates instead of secrets in your application(s)

Microsoft identity platform supports two types of authentication for confidential client applications: password-based authentication (i.e. client secret) and certificate-based authentication. For a higher level of security, we recommend using a certificate (instead of a client secret) as a credential in your confidential client applications.

In production, you should purchase a certificate signed by a well-known certificate authority, and use Azure Key Vault to manage certificate access and lifetime for you. For testing purposes, follow the steps below to create a self-signed certificate and configure your apps to authenticate with certificates.

Using certificates

ℹ️ Expand this to use automation

  1. While inside AppCreationScripts folder, open a terminal.

  2. Run the Cleanup-withCertCertificates.ps1 script to delete any existing app registrations and certificates for the sample.

    .\Cleanup-withCertCertificates.ps1
  1. Run the Configure-withCertCertificates.ps1 script to re-create the App Registration. The script will also create .pfx file(s) (e.g. ciam-aspnet-webapp.pfx) that you can upload to Key Vault later. When asked about a password, do remember it - you will need the password when uploading the certificate.
    .\Configure-withCertCertificates.ps1
  1. Proceed to step 3 to configure application settings.

If you plan to deploy your app(s) to Azure App Service afterwards, we recommend Azure Managed Identity to completely eliminate secrets, certificates, connection strings and etc. from your source code. See Using Managed Identity below for more.

Create a self-signed certificate

You can skip this step if you already have a valid self-signed certificate at hand.

Create self-signed certificate on local machine

If you wish to generate a new self-signed certificate yourself, follow the steps below.

Click here to use Powershell

To generate a new self-signed certificate, we will use the New-SelfSignedCertificate Powershell command.

Open PowerShell and run the command with the following parameters to create a new self-signed certificate that will be stored in the current user certificate store on your computer:

$cert = New-SelfSignedCertificate -Subject "CN=ciam-aspnet-webapp" -CertStoreLocation "Cert:\CurrentUser\My" -KeyExportPolicy Exportable -KeySpec Signature -KeyLength 2048 -KeyAlgorithm RSA -HashAlgorithm SHA256

You can now export a public key (.cer file) and a public + private key combination (.pfx file) to use in your app:

Export-Certificate -Cert $cert -FilePath "C:\Users\diego\Desktop\ciam-aspnet-webapp.cer" ## Specify your preferred location

$mypwd = ConvertTo-SecureString -String "{myPassword}" -Force -AsPlainText  ## Replace {myPassword}
Export-PfxCertificate -Cert $cert -FilePath "C:\Users\diego\Desktop\ciam-aspnet-webapp.pfx" -Password $mypwd ## Specify your preferred location

Proceed to Step 2.

ℹ️ For more details, follow the guide: Create a self-signed public certificate to authenticate your application

Click here to use OpenSSL

Download and build OpenSSL for your OS following the guide at github.com/openssl. If you like to skip building and get a binary distributable from the community instead, check the OpenSSL Wiki: Binaries page. Afterwards, add the path to OpenSSL to your environment variables so that you can call it from anywhere.

Type the following in a terminal. The files will be generated in the terminals current directory.

openssl req -x509 -newkey rsa:2048 -keyout ciam-aspnet-webapp.key -out ciam-aspnet-webapp.cer -subj "/CN=ciam-aspnet-webapp" -nodes

Generating a RSA private key
.........................................................
writing new private key to 'ciam-aspnet-webapp.key'

The following files should be generated: ciam-aspnet-webapp.key, ciam-aspnet-webapp.cer

If you need, you can generate a ciam-aspnet-webapp.pfx (certificate + private key combination) with the command below:

openssl pkcs12 -export -out CertificateName.pfx -inkey ciam-aspnet-webapp.key -in ciam-aspnet-webapp.cer

Enter an export password when prompted and make a note of it. The following file should be generated: ciam-aspnet-webapp.pfx.

Proceed to Step 2.

ℹ️ If you wish so, you can upload your locally generated self-signed certificate to Azure Key Vault later on. See: Import a certificate in Azure Key Vault

Create self-signed certificate on Key Vault

You can use Azure Key Vault to generate a self-signed certificate for you. Doing so will have the additional benefits of assigning a partner Certificate Authority (CA) and automating certificate rotation.

Click here to use Azure Portal

Follow the guide: Set and retrieve a certificate from Azure Key Vault using the Azure portal

Afterwards, proceed to Step 2.

Click here to use Powershell

Follow the guide: Set and retrieve a certificate from Azure Key Vault using Azure PowerShell

Afterwards, proceed to Step 2.

Configure an Azure AD app registration to use a certificate

Now you must associate your Azure AD app registration with the certificate you will use in your application.

ℹ️ If you have the certificate locally available, you can follow the steps below. If your certificate(s) is on Azure Key Vault, you must first export and download them to your computer, and delete the local copy after following the steps below. See: Export certificates from Azure Key Vault

  1. Navigate to Azure portal and select your Azure AD app registration.
  2. Select Certificates & secrets blade on the left.
  3. Click on Upload certificate and select the certificate file to upload (e.g. ciam-aspnet-webapp).
  4. Click Add. Once the certificate is uploaded, the thumbprint, start date, and expiration values are displayed. Record the thumbprint value as you will make use of it later in your app's configuration file.

For more information, see: Register your certificate with the Microsoft identity platform

Proceed to Step 3

Configure your app(s) to use a certificate

Finally, you need to modify the app's configuration files.

Using an existing certificate from local machine

Perform the steps below for the client app (ciam-aspnet-webapp)

  1. Open the appsettings.json file.
  2. Comment out the next line:
    "ClientSecret": "[Copy the client secret added to the app from the Azure portal]"
  1. Un-comment the following lines and replace the default values:
    "ClientCredentials": [
        {
            "SourceType": "Path",
            "CertificateDiskPath": "<path to certificate e.g. c:\Users\diego\Desktop\ciam-aspnet-webapp.pfx",
            "CertificateThumbprint": "<the thumbprint of the certificate, e.g. 962D129A...D18EFEB6961684>"
        }
    ]

ℹ️ For other alternatives, see: Using certificates with Microsoft.Identity.Web

You can now start the application as instructed in the README.

Using an existing certificate from Key Vault

Perform the steps below for the client app (ciam-aspnet-webapp)

  1. Open the appsettings.json file.
  2. Comment out the next line:
    "ClientSecret": "[Copy the client secret added to the app from the Azure portal]"
  1. Un-comment the following lines and replace the default values:
    "ClientCredentials": [
        {
            "SourceType": "KeyVault",
            "KeyVaultUrl": "https://example.vault.azure.net",
            "KeyVaultCertificateName": "ExampleCert"
        }
    ]

ℹ️ For other alternatives, see: Using certificates with Microsoft.Identity.Web

You can now start the application as instructed in the README.

Using Managed Identity

Once you deploy your app(s) to Azure App Service, you can assign a managed identity to it for accessing Azure Key Vault using its own identity. This allows you to eliminate the all secrets, certificates, connection strings and etc. from your source code.

Create a system-assigned identity

  1. Navigate to Azure portal and select the Azure App Service.
  2. Find and select the App Service instance you've created previously.
  3. On App Service portal, select Identity.
  4. Within the System assigned tab, switch Status to On. Click Save.

For more information, see Add a system-assigned identity

Grant access to Key Vault

Now that your app deployed to App Service has a managed identity, in this step you grant it access to your key vault.

  1. Go to the Azure portal and search for your Key Vault.
  2. Select Overview > Access policies blade on the left.
  3. Click on Add Access Policy > Certificate permissions > Get
  4. Click on Add Access Policy > Secret permissions > Get
  5. Click on Select Principal, add your account and pre-created system-assigned identity.
  6. Click on OK to add the new Access Policy, then click Save to save the Access Policy.

For more information, see Use Key Vault from App Service with Azure Managed Identity

Add environment variables

Finally, you need to add environment variables to the App Service where you deployed your app.

⚠️ Make sure your application is able to read environment variables. Alternatively, you can hardcode the key vault URL and certificate name in your applications configuration file.

  1. In the Azure portal, search for and select App Service, and then select your app.
  2. Select Configuration blade on the left, then select New Application Settings.
  3. Add the following variables (key-value pairs):
    1. KEY_VAULT_URL: the URL of the key vault you've created, e.g. https://example.vault.azure.net
    2. CERTIFICATE_NAME: the name of the certificate you specified when importing it to key vault, e.g. ExampleCert

Wait for a few minutes for your changes on App Service to take effect. You should then be able to visit your published website and sign-in accordingly.

More information