Skip to content

Latest commit

 

History

History
228 lines (161 loc) · 21.3 KB

azureappgw.md

File metadata and controls

228 lines (161 loc) · 21.3 KB

Azure Application Gateway Certificate

The Azure Application Gateway Certificate store type, AzureAppGw, manages ApplicationGatewaySslCertificate objects owned by Azure Application Gateways. This store type collects inventory and manages all ApplicationGatewaySslCertificate objects associated with an Application Gateway. The store type is implemented primarily for Inventory and Management Remove operations, since the intended usage of ApplicationGatewaySslCertificates in Application Gateways is for serving TLS client traffic via TLS Listeners. Management Add and associated logic for certificate renewal is also supported for this certificate store type for completeness, but the primary intended functionality of this extension is implemented with the App Gateway Certificate Binding store type.

If an ApplicationGatewaySslCertificate is bound to a TLS Listener at the time of a Management Remove operation, the operation will fail since at least one certificate must be bound at all times.

If a renewal job is scheduled for an AzureAppGw certificate store, the extension will report a success and perform no action if the certificate being renewed is bound to a TLS Listener. This is because a certificate located in an AzureAppGw certificate store that is bound to a TLS Listener is logically the same as the same certificate located in an AzureAppGwBin store type. For this reason, it's expected that the certificate will be renewed and re-bound to the listener by the AppGwBin certificate operations.

If the renewed certificate is not bound to a TLS Listener, the operation will be performed the same as any certificate renewal process that honors the Overwrite flag.

Supported Job Types

Job Name Supported
Inventory ✅
Management Add ✅
Management Remove ✅
Discovery ✅
Create
Reenrollment

Requirements

Azure Service Principal (Azure Resource Manager Authentication)

The Azure Application Gateway Orchestrator extension uses an Azure Service Principal for authentication. Follow Microsoft's documentation to create a service principal.

Azure Application Gateway permissions

For quick start and non-production environments, a Role Assignment should be created on each resource group that own Application Gateways desiring management that grants the created Application/Service Principal the Contributor (Privileged administrator) Role. For production environments, a custom role should be created that grants the following permissions:

  • Microsoft.Resources/subscriptions/resourcegroups/read - Read : Get Resource Group
  • Microsoft.Network/applicationGateways/read - Read : Get Application Gateway
  • Microsoft.Network/applicationGateways/write - Write : Create or Update Application Gateway
  • Microsoft.ManagedIdentity/userAssignedIdentities/assign/action - Other : RBAC action for assigning an existing user assigned identity to a resource
  • Microsoft.Network/virtualNetworks/subnets/join/action - Other : Joins a virtual network. Not Alertable.

Note that even if the Service Principal has permission to perform the 'Microsoft.Network/applicationGateways/write' action over the scope of the required resource group, there may be other permissions that are required by the CreateOrUpdate operation depending on the complexity of the Application Gateway's configuration. As such, the list of permissions above should not be considered as comprehensive.

Azure Key Vault permissions

If the managed Application Gateway is integrated with Azure Key Vault per the discussion in the Certificates Imported to Application Gateways from Azure Key Vault section, perform one of the following actions for each Key Vault with certificates imported to App Gateways:

  • Azure role-based access control - Create a Role Assignment that grants the Application/Service Principal the Key Vault Secrets User built-in role.
  • Vault access policy - Create an Access Policy that grants the Application/Service Principal the Get secret permission for each Azure Key Vault.
Client Certificate or Client Secret

Beginning in version 3.0.0, the Azure Application Gateway Orchestrator extension supports both client certificate authentication and client secret authentication.

  • Client Secret - Follow Microsoft's documentation to create a Client Secret. This secret will be used as the Server Password field in the Certificate Store Configuration section.

  • Client Certificate - Create a client certificate key pair with the Client Authentication extended key usage. The client certificate will be used in the ClientCertificate field in the Certificate Store Configuration section. If you have access to Keyfactor Command, the instructions in this section walk you through enrolling a certificate and ensuring that it's in the correct format. Once enrolled, follow Microsoft's documentation to add the public key certificate (no private key) to the service principal used for authentication.

    The certificate can be in either of the following formats:

    • Base64-encoded PKCS#12 (PFX) with a matching private key.
    • Base64-encoded PEM-encoded certificate and PEM-encoded PKCS8 private key. Make sure that the certificate and private key are separated with a newline. The order doesn't matter - the extension will determine which is which.

    If the private key is encrypted, the encryption password will replace the Server Password field in the Certificate Store Configuration section.

Creating and Formatting a Client Certificate using Keyfactor Command

To get started quickly, you can follow the instructions below to create and properly format a client certificate to authenticate to the Microsoft Graph API.

  1. In Keyfactor Command, hover over Enrollment and select PFX Enrollment.
  2. Select a Template that supports Client Authentication as an extended key usage.
  3. Populate the certificate subject as appropriate for the Template. It may be sufficient to only populate the Common Name, but consult your IT policy to ensure that this certificate is compliant.
  4. At the bottom of the page, uncheck the box for Include Chain, and select either PFX or PEM as the certificate Format.
  5. Make a note of the password on the next page - it won't be shown again.
  6. Prepare the certificate and private key for Azure and the Orchestrator extension:

    • If you downloaded the certificate in PEM format, use the commands below:

      # Verify that the certificate downloaded from Command contains the certificate and private key. They should be in the same file
cat <your_certificate.pem>

# Separate the certificate from the private key
openssl x509 -in <your_certificate.pem> -out pubkeycert.pem

# Base64 encode the certificate and private key
cat <your_certificate.pem> | base64 > clientcertkeypair.pem.base64

    • If you downloaded the certificate in PFX format, use the commands below:

      # Export the certificate from the PFX file
openssl pkcs12 -in <your_certificate.pfx> -clcerts -nokeys -out pubkeycert.pem

# Base64 encode the PFX file
cat <your_certificate.pfx> | base64 > clientcert.pfx.base64
  7. Follow Microsoft's documentation to add the public key certificate to the service principal used for authentication.

You will use clientcert.[pem|pfx].base64 as the ClientCertificate field in the Certificate Store Configuration section.

Certificate Store Type Configuration

The recommended method for creating the AzureAppGw Certificate Store Type is to use kfutil. After installing, use the following command to create the AzureAppGw Certificate Store Type:

kfutil store-types create AzureAppGw
AzureAppGw

Create a store type called AzureAppGw with the attributes in the tables below:

Basic Tab

Attribute Value Description
Name Azure Application Gateway Certificate Display name for the store type (may be customized)
Short Name AzureAppGw Short display name for the store type
Capability AzureAppGw Store type name orchestrator will register with. Check the box to allow entry of value
Supported Job Types (check the box for each) Add, Discovery, Remove Job types the extension supports
Supports Add ✅ Check the box. Indicates that the Store Type supports Management Add
Supports Remove ✅ Check the box. Indicates that the Store Type supports Management Remove
Supports Discovery ✅ Check the box. Indicates that the Store Type supports Discovery
Supports Reenrollment Indicates that the Store Type supports Reenrollment
Supports Create Indicates that the Store Type supports store creation
Needs Server ✅ Determines if a target server name is required when creating store
Blueprint Allowed Determines if store type may be included in an Orchestrator blueprint
Uses PowerShell Determines if underlying implementation is PowerShell
Requires Store Password Determines if a store password is required when configuring an individual store.
Supports Entry Password Determines if an individual entry within a store can have a password.

The Basic tab should look like this:

AzureAppGw Basic Tab

Advanced Tab

Attribute Value Description
Supports Custom Alias Required Determines if an individual entry within a store can have a custom Alias.
Private Key Handling Required This determines if Keyfactor can send the private key associated with a certificate to the store. Required because IIS certificates without private keys would be invalid.
PFX Password Style Default 'Default' - PFX password is randomly generated, 'Custom' - PFX password may be specified when the enrollment job is created (Requires the Allow Custom Password application setting to be enabled.)

The Advanced tab should look like this:

AzureAppGw Advanced Tab

Custom Fields Tab

Custom fields operate at the certificate store level and are used to control how the orchestrator connects to the remote target server containing the certificate store to be managed. The following custom fields should be added to the store type:

Name Display Name Type Default Value/Options Required Description
ServerUsername Server Username Secret Application ID of the service principal, representing the identity used for managing the Application Gateway.
ServerPassword Server Password Secret A Client Secret that the extension will use to authenticate with the Azure Resource Management API for managing Application Gateway certificates, OR the password that encrypts the private key in ClientCertificate
ClientCertificate Client Certificate Secret The client certificate used to authenticate with Azure Resource Management API for managing Application Gateway certificates. See the requirements for more information.
AzureCloud Azure Global Cloud Authority Host MultipleChoice public,china,germany,government Specifies the Azure Cloud instance used by the organization.
ServerUseSsl Use SSL Bool true ✅ Specifies whether SSL should be used for communication with the server. Set to 'true' to enable SSL, and 'false' to disable it.

The Custom Fields tab should look like this:

AzureAppGw Custom Fields Tab

Extension Mechanics

Discovery Job

The Discovery operation discovers all Azure Application Gateways in each resource group that the service principal has access to. The discovered Application Gateways are reported back to Command and can be easily added as certificate stores from the Locations tab.

The Discovery operation uses the "Directories to search" field, and accepts input in one of the following formats:

  • * - If the asterisk symbol * is used, the extension will search for Application Gateways in every resource group that the service principal has access to, but only in the tenant that the discovery job was configured for as specified by the "Client Machine" field in the certificate store configuration.
  • <tenant-id>,<tenant-id>,... - If a comma-separated list of tenant IDs is used, the extension will search for Application Gateways in every resource group and tenant specified in the list. The tenant IDs should be the GUIDs associated with each tenant, and it's the user's responsibility to ensure that the service principal has access to the specified tenants.

The Discovery Job only supports Client Secret authentication.

Certificates Imported to Application Gateways from Azure Key Vault

Natively, Azure Application Gateways support integration with Azure Key Vault for secret/certificate management. This integration works by creating a TLS Listener certificate with a reference to a secret in Azure Key Vault (specifically, a URI in the format https://<vault-name>.vault.azure.net/secrets/<secret-name>), authenticated using a Managed Identity. If the Application Gateway orchestrator extension is deployed to manage App Gateways with certificates imported from Azure Key Vault, the following truth table represents the possible operations and their result, specifically with respect to AKV.

Store Type Operation Result
AzureAppGw Inventory Certificate is downloaded from Azure Key Vault and reported back to Keyfactor Command. In Keyfactor Command, the certificate will show as being located in the AzureAppGw certificate store [in addition to the AKV, if AKV orchestrator extension is also deployed].
AzureAppGw Add The Add operation will not create secrets in AKV; it creates ApplicationGatewaySslCertificates.

If an AzureAppGw Add operation is scheduled with the Replace flag, the link to the AKV certificate will be broken, and a native ApplicationGatewaySslCertificate will be created in its place - The secret in AKV will still exist.
AzureAppGw Remove The ApplicationGatewaySslCertificate is deleted from the Application Gateway, but the secret that the certificate referenced in AKV still exists.
AzureAppGwBin Inventory Certificate is downloaded from Azure Key Vault and reported back to Keyfactor Command. In Keyfactor Command, the certificate will show as present in both an AzureAppGw certificate store and an AppGwBin certificate store [in addition to the AKV, if AKV orchestrator extension is also deployed].
AzureAppGwBin Add The Add operation will not create secrets in AKV; it creates ApplicationGatewaySslCertificates.

If a certificate with the same name as the TLS Listener already exists, it will be replaced by a new ApplicationGatewaySslCertificate.

If the certificate being replaced was imported from AKV, this binding will be broken and the secret will still exist in AKV.
Mechanics of the Azure Key Vault Download Operation for Inventory Jobs that report certificates imported from AKV

If an AzureApplicationSslCertificate references a secret in AKV (was imported to the App Gateway from AKV), the inventory job will create and use a SecretClient from the Azure.Security.KeyVault.Secrets.SecretClient dotnet package. Authentication to AKV via this client is configured using the exact same TokenCredential provided by the Azure Identity client library for .NET. This means that the Service Principal described in the Azure Configuration section must also have appropriate permissions to read secrets from the AKV that the App Gateway is integrated with. The secret referenced in the AzureApplicationSslCertificate will be accessed exactly as reported by Azure, regardless of whether it exists in AKV.

Certificate Store Configuration

After creating the AzureAppGw Certificate Store Type and installing the Azure Application Gateway Universal Orchestrator extension, you can create new Certificate Stores to manage certificates in the remote platform.

The following table describes the required and optional fields for the AzureAppGw certificate store type.

Attribute Description Attribute is PAM Eligible
Category Select "Azure Application Gateway Certificate" or the customized certificate store name from the previous step.
Container Optional container to associate certificate store with.
Client Machine The Azure Tenant (directory) ID that owns the Service Principal.
Store Path Azure resource ID of the application gateway, following the format: /subscriptions//resourceGroups//providers/Microsoft.Network/applicationGateways/.
Orchestrator Select an approved orchestrator capable of managing AzureAppGw certificates. Specifically, one with the AzureAppGw capability.
ServerUsername Application ID of the service principal, representing the identity used for managing the Application Gateway.
ServerPassword A Client Secret that the extension will use to authenticate with the Azure Resource Management API for managing Application Gateway certificates, OR the password that encrypts the private key in ClientCertificate
ClientCertificate The client certificate used to authenticate with Azure Resource Management API for managing Application Gateway certificates. See the requirements for more information.
AzureCloud Specifies the Azure Cloud instance used by the organization.
ServerUseSsl Specifies whether SSL should be used for communication with the server. Set to 'true' to enable SSL, and 'false' to disable it.

  • Using kfutil

    # Generate a CSV template for the AzureApp certificate store
kfutil stores import generate-template --store-type-name AzureAppGw --outpath AzureAppGw.csv

# Open the CSV file and fill in the required fields for each certificate store.

# Import the CSV file to create the certificate stores
kfutil stores import csv --store-type-name AzureAppGw --file AzureAppGw.csv

  • Manually with the Command UI: In Keyfactor Command, navigate to Certificate Stores from the Locations Menu. Click the Add button to create a new Certificate Store using the attributes in the table above.