Skip to content

Latest commit

 

History

History
196 lines (121 loc) · 12.5 KB

README-use-certificate.md

File metadata and controls

196 lines (121 loc) · 12.5 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

⚠️ Make sure you have OpenSSL installed on your machine. After installation, you may need to start a new command line instance for the openssl command to be available on system path.

choco install openssl

Alternatively, 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.

  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-msal-node-console.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 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-msal-node-console.key -out ciam-msal-node-console.cer -subj "/CN=ciam-msal-node-console" -nodes

Generating a RSA private key
.........................................................
writing new private key to 'ciam-msal-node-console.key'

The following files should be generated: ciam-msal-node-console.key, ciam-msal-node-console.cer

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

openssl pkcs12 -export -out CertificateName.pfx -inkey ciam-msal-node-console.key -in ciam-msal-node-console.cer

Enter an export password when prompted and make a note of it. The following file should be generated: ciam-msal-node-console.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.

ℹ️ Azure Key Vault can export certificates and private keys in pem format (see: Export stored certificates), if Content Type was chosen as pem during certificate generation (see: Create a certificate in Key Vault). If for some reason this is not the case, OpenSSL can be used for conversions.

cat ciam-msal-node-console.crt ciam-msal-node-console.key > ciam-msal-node-console.pem ## if powershell: Get-Content ciam-msal-node-console.crt, ciam-msal-node-console.key | Set-Content ciam-msal-node-console.pem
openssl pkcs12 -in ciam-msal-node-console.pfx -out ciam-msal-node-console.pem
Click here to use Microsoft Entra admin center

Follow the guide: Set and retrieve a certificate from Azure Key Vault using the Microsoft Entra admin center

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 Microsoft Entra admin center 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-msal-node-console).
  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-msal-node-console)

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-msal-node-console)

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 Microsoft Entra admin center 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 Microsoft Entra admin center 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 Microsoft Entra admin center, 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