diff --git a/.github/workflows/keyfactor-starter-workflow.yml b/.github/workflows/keyfactor-bootstrap-workflow.yml similarity index 80% rename from .github/workflows/keyfactor-starter-workflow.yml rename to .github/workflows/keyfactor-bootstrap-workflow.yml index 6d8de53..64919a4 100644 --- a/.github/workflows/keyfactor-starter-workflow.yml +++ b/.github/workflows/keyfactor-bootstrap-workflow.yml @@ -11,9 +11,10 @@ on: jobs: call-starter-workflow: - uses: keyfactor/actions/.github/workflows/starter.yml@v2 + uses: keyfactor/actions/.github/workflows/starter.yml@v3 secrets: token: ${{ secrets.V2BUILDTOKEN}} APPROVE_README_PUSH: ${{ secrets.APPROVE_README_PUSH}} gpg_key: ${{ secrets.KF_GPG_PRIVATE_KEY }} gpg_pass: ${{ secrets.KF_GPG_PASSPHRASE }} + scan_token: ${{ secrets.SAST_TOKEN }} diff --git a/.github/workflows/keyfactor-merge-store-types.yml b/.github/workflows/keyfactor-merge-store-types.yml deleted file mode 100644 index c70659f..0000000 --- a/.github/workflows/keyfactor-merge-store-types.yml +++ /dev/null @@ -1,27 +0,0 @@ -name: Keyfactor Merge Cert Store Types -on: [workflow_dispatch] - -jobs: - get-manifest-properties: - runs-on: windows-latest - outputs: - update_catalog: ${{ steps.read-json.outputs.update_catalog }} - integration_type: ${{ steps.read-json.outputs.integration_type }} - steps: - - uses: actions/checkout@v3 - - name: Store json - id: read-json - shell: pwsh - run: | - $json = Get-Content integration-manifest.json | ConvertFrom-Json - $myvar = $json.update_catalog - echo "update_catalog=$myvar" | Out-File -FilePath $Env:GITHUB_OUTPUT -Encoding utf8 -Append - $myvar = $json.integration_type - echo "integration_type=$myvar" | Out-File -FilePath $Env:GITHUB_OUTPUT -Encoding utf8 -Append - - call-update-store-types-workflow: - needs: get-manifest-properties - if: needs.get-manifest-properties.outputs.integration_type == 'orchestrator' && (github.event_name == 'push' || github.event_name == 'workflow_dispatch') - uses: Keyfactor/actions/.github/workflows/update-store-types.yml@main - secrets: - token: ${{ secrets.UPDATE_STORE_TYPES }} diff --git a/CHANGELOG.md b/CHANGELOG.md index 9ce2155..083e29e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -28,3 +28,6 @@ - 3.1.0 - fix(deps): Revert main Azure Application Gateway Orchestrator extension .NET project to .NET 6 from .NET 8. + +- 3.2.0 + - chore(docs): Upgrade GitHub Actions to use Bootstrap Workflow v3 to support Doctool diff --git a/README.md b/README.md index bfacc48..7a25997 100644 --- a/README.md +++ b/README.md @@ -1,53 +1,3 @@ - -# Azure Application Gateway Orchestrator - -The Azure Application Gateway Orchestrator Extension is an extension to the Keyfactor Universal Orchestrator that allows for the management of certificates on Azure Application Gateways, including the ability to add and bind certificates to HTTPS listeners. - -#### Integration status: Production - Ready for use in production environments. - -## About the Keyfactor Universal Orchestrator Extension - -This repository contains a Universal Orchestrator Extension which is a plugin to the Keyfactor Universal Orchestrator. Within the Keyfactor Platform, Orchestrators are used to manage “certificate stores” — collections of certificates and roots of trust that are found within and used by various applications. - -The Universal Orchestrator is part of the Keyfactor software distribution and is available via the Keyfactor customer portal. For general instructions on installing Extensions, see the “Keyfactor Command Orchestrator Installation and Configuration Guide” section of the Keyfactor documentation. For configuration details of this specific Extension see below in this readme. - -The Universal Orchestrator is the successor to the Windows Orchestrator. This Orchestrator Extension plugin only works with the Universal Orchestrator and does not work with the Windows Orchestrator. - -## Support for Azure Application Gateway Orchestrator - -Azure Application Gateway Orchestrator is supported by Keyfactor for Keyfactor customers. If you have a support issue, please open a support ticket via the Keyfactor Support Portal at https://support.keyfactor.com - -###### To report a problem or suggest a new feature, use the **[Issues](../../issues)** tab. If you want to contribute actual bug fixes or proposed enhancements, use the **[Pull requests](../../pulls)** tab. - ---- - - ---- - - - -## Keyfactor Version Supported - -The minimum version of the Keyfactor Universal Orchestrator Framework needed to run this version of the extension is 10.4 -## Platform Specific Notes - -The Keyfactor Universal Orchestrator may be installed on either Windows or Linux based platforms. The certificate operations supported by a capability may vary based what platform the capability is installed on. The table below indicates what capabilities are supported based on which platform the encompassing Universal Orchestrator is running. -| Operation | Win | Linux | -|-----|-----|------| -|Supports Management Add|✓ |✓ | -|Supports Management Remove|✓ |✓ | -|Supports Create Store| | | -|Supports Discovery|✓ |✓ | -|Supports Reenrollment| | | -|Supports Inventory|✓ |✓ | - - - - - ---- - -

Azure Application Gateway Universal Orchestrator Extension

@@ -87,6 +37,14 @@ The Azure Application Gateway Orchestrator extension remotely manages certificat > > If the certificate management capabilities of Azure Key Vault are desired over direct management of certificates in Application Gateways, the Azure Key Vault orchestrator can be used in conjunction with this extension for accurate certificate location reporting via the inventory job type. This management strategy requires manual binding of certificates imported to an Application Gateway from AKV and can result in broken state in the Azure Application Gateway in the case that the secret is deleted in AKV. +## Compatibility + +This integration is compatible with Keyfactor Universal Orchestrator version 10.4 and later. + +## Support +The Azure Application Gateway Universal Orchestrator extension is supported by Keyfactor for Keyfactor customers. If you have a support issue, please open a support ticket with your Keyfactor representative. If you have a support issue, please open a support ticket via the Keyfactor Support Portal at https://support.keyfactor.com. + +> To report a problem or suggest a new feature, use the **[Issues](../../issues)** tab. If you want to contribute actual bug fixes or proposed enhancements, use the **[Pull requests](../../pulls)** tab. ## Installation Before installing the Azure Application Gateway Universal Orchestrator extension, it's recommended to install [kfutil](https://github.com/Keyfactor/kfutil). Kfutil is a command-line tool that simplifies the process of creating store types, installing extensions, and instantiating certificate stores in Keyfactor Command. @@ -101,12 +59,12 @@ The Azure Application Gateway Universal Orchestrator extension implements 2 Cert 1. Follow the [requirements section](docs/azureappgw.md#requirements) to configure a Service Account and grant necessary API permissions.
Requirements - - ### Azure Service Principal (Azure Resource Manager Authentication) + + #### Azure Service Principal (Azure Resource Manager Authentication) The Azure Application Gateway Orchestrator extension uses an [Azure Service Principal](https://learn.microsoft.com/en-us/entra/identity-platform/app-objects-and-service-principals?tabs=browser) for authentication. Follow [Microsoft's documentation](https://learn.microsoft.com/en-us/entra/identity-platform/howto-create-service-principal-portal) to create a service principal. - #### Azure Application Gateway permissions + ##### 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](https://learn.microsoft.com/en-us/azure/role-based-access-control/built-in-roles#contributor). For production environments, a custom role should be created that grants the following permissions: @@ -118,13 +76,13 @@ The Azure Application Gateway Universal Orchestrator extension implements 2 Cert > 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 + ##### 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](#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](https://learn.microsoft.com/en-us/azure/key-vault/general/rbac-guide?tabs=azure-cli) built-in role. * **Vault access policy** - [Create an Access Policy](https://learn.microsoft.com/en-us/azure/key-vault/general/assign-access-policy?tabs=azure-portal) that grants the Application/Service Principal the Get secret permission for each Azure Key Vault. - #### Client Certificate or Client Secret + ##### Client Certificate or Client Secret Beginning in version 3.0.0, the Azure Application Gateway Orchestrator extension supports both [client certificate authentication](https://learn.microsoft.com/en-us/graph/auth-register-app-v2#option-1-add-a-certificate) and [client secret](https://learn.microsoft.com/en-us/graph/auth-register-app-v2#option-2-add-a-client-secret) authentication. @@ -173,8 +131,6 @@ The Azure Application Gateway Universal Orchestrator extension implements 2 Cert > > You will use `clientcert.[pem|pfx].base64` as the **ClientCertificate** field in the [Certificate Store Configuration](#certificate-store-configuration) section. - -
2. Create Certificate Store Types for the Azure Application Gateway Orchestrator extension. @@ -204,7 +160,10 @@ The Azure Application Gateway Universal Orchestrator extension implements 2 Cert * **Manually**: Follow the [official Command documentation](https://software.keyfactor.com/Core-OnPrem/Current/Content/InstallingAgents/NetCoreOrchestrator/CustomExtensions.htm?Highlight=extensions) to install the latest [Azure Application Gateway Universal Orchestrator extension](https://github.com/Keyfactor/azure-appgateway-orchestrator/releases/latest). 4. Create new certificate stores in Keyfactor Command for the Sample Universal Orchestrator extension. + * [Azure Application Gateway Certificate](docs/azureappgw.md#certificate-store-configuration) + +
Azure Application Gateway Certificate Binding @@ -214,11 +173,11 @@ The Azure Application Gateway Universal Orchestrator extension implements 2 Cert
Requirements - ### Azure Service Principal (Azure Resource Manager Authentication) + #### Azure Service Principal (Azure Resource Manager Authentication) The Azure Application Gateway Orchestrator extension uses an [Azure Service Principal](https://learn.microsoft.com/en-us/entra/identity-platform/app-objects-and-service-principals?tabs=browser) for authentication. Follow [Microsoft's documentation](https://learn.microsoft.com/en-us/entra/identity-platform/howto-create-service-principal-portal) to create a service principal. - #### Azure Application Gateway permissions + ##### 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](https://learn.microsoft.com/en-us/azure/role-based-access-control/built-in-roles#contributor). For production environments, a custom role should be created that grants the following permissions: @@ -230,13 +189,13 @@ The Azure Application Gateway Universal Orchestrator extension implements 2 Cert > 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 + ##### 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](#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](https://learn.microsoft.com/en-us/azure/key-vault/general/rbac-guide?tabs=azure-cli) built-in role. * **Vault access policy** - [Create an Access Policy](https://learn.microsoft.com/en-us/azure/key-vault/general/assign-access-policy?tabs=azure-portal) that grants the Application/Service Principal the Get secret permission for each Azure Key Vault. - #### Client Certificate or Client Secret + ##### Client Certificate or Client Secret Beginning in version 3.0.0, the Azure Application Gateway Orchestrator extension supports both [client certificate authentication](https://learn.microsoft.com/en-us/graph/auth-register-app-v2#option-1-add-a-certificate) and [client secret](https://learn.microsoft.com/en-us/graph/auth-register-app-v2#option-2-add-a-client-secret) authentication. @@ -285,8 +244,6 @@ The Azure Application Gateway Universal Orchestrator extension implements 2 Cert > > You will use `clientcert.[pem|pfx].base64` as the **ClientCertificate** field in the [Certificate Store Configuration](#certificate-store-configuration) section. - -
2. Create Certificate Store Types for the Azure Application Gateway Orchestrator extension. @@ -316,7 +273,10 @@ The Azure Application Gateway Universal Orchestrator extension implements 2 Cert * **Manually**: Follow the [official Command documentation](https://software.keyfactor.com/Core-OnPrem/Current/Content/InstallingAgents/NetCoreOrchestrator/CustomExtensions.htm?Highlight=extensions) to install the latest [Azure Application Gateway Universal Orchestrator extension](https://github.com/Keyfactor/azure-appgateway-orchestrator/releases/latest). 4. Create new certificate stores in Keyfactor Command for the Sample Universal Orchestrator extension. + * [Azure Application Gateway Certificate Binding](docs/appgwbin.md#certificate-store-configuration) + +
@@ -326,8 +286,4 @@ Apache License 2.0, see [LICENSE](LICENSE). ## Related Integrations -See all [Keyfactor Universal Orchestrator extensions](https://github.com/orgs/Keyfactor/repositories?q=orchestrator). - -When creating cert store type manually, that store property names and entry parameter names are case sensitive - - +See all [Keyfactor Universal Orchestrator extensions](https://github.com/orgs/Keyfactor/repositories?q=orchestrator). \ No newline at end of file diff --git a/docs/appgwbin.md b/docs/appgwbin.md index 6f51835..66db946 100644 --- a/docs/appgwbin.md +++ b/docs/appgwbin.md @@ -27,11 +27,11 @@ The Inventory job type for `AzureAppGwBin` reports only ApplicationGatewaySslCer ## Requirements -### Azure Service Principal (Azure Resource Manager Authentication) +#### Azure Service Principal (Azure Resource Manager Authentication) The Azure Application Gateway Orchestrator extension uses an [Azure Service Principal](https://learn.microsoft.com/en-us/entra/identity-platform/app-objects-and-service-principals?tabs=browser) for authentication. Follow [Microsoft's documentation](https://learn.microsoft.com/en-us/entra/identity-platform/howto-create-service-principal-portal) to create a service principal. -#### Azure Application Gateway permissions +##### 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](https://learn.microsoft.com/en-us/azure/role-based-access-control/built-in-roles#contributor). For production environments, a custom role should be created that grants the following permissions: @@ -43,13 +43,13 @@ For quick start and non-production environments, a Role Assignment should be cre > 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 +##### 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](#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](https://learn.microsoft.com/en-us/azure/key-vault/general/rbac-guide?tabs=azure-cli) built-in role. * **Vault access policy** - [Create an Access Policy](https://learn.microsoft.com/en-us/azure/key-vault/general/assign-access-policy?tabs=azure-portal) that grants the Application/Service Principal the Get secret permission for each Azure Key Vault. -#### Client Certificate or Client Secret +##### Client Certificate or Client Secret Beginning in version 3.0.0, the Azure Application Gateway Orchestrator extension supports both [client certificate authentication](https://learn.microsoft.com/en-us/graph/auth-register-app-v2#option-1-add-a-certificate) and [client secret](https://learn.microsoft.com/en-us/graph/auth-register-app-v2#option-2-add-a-client-secret) authentication. @@ -99,37 +99,6 @@ Beginning in version 3.0.0, the Azure Application Gateway Orchestrator extension > You will use `clientcert.[pem|pfx].base64` as the **ClientCertificate** field in the [Certificate Store Configuration](#certificate-store-configuration) section. - -## 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. -- `,,...` - 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.azure.net/secrets/`), 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](https://learn.microsoft.com/en-us/dotnet/api/azure.security.keyvault.secrets.secretclient?view=azure-dotnet). Authentication to AKV via this client is configured using the exact same `TokenCredential` provided by the [Azure Identity client library for .NET](https://learn.microsoft.com/en-us/dotnet/api/overview/azure/identity-readme?view=azure-dotnet). This means that the Service Principal described in the [Azure Configuration](#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 Type Configuration The recommended method for creating the `AppGwBin` Certificate Store Type is to use [kfutil](https://github.com/Keyfactor/kfutil). After installing, use the following command to create the `` Certificate Store Type: @@ -195,24 +164,57 @@ The Custom Fields tab should look like this: + +## 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. +- `,,...` - 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.azure.net/secrets/`), 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](https://learn.microsoft.com/en-us/dotnet/api/azure.security.keyvault.secrets.secretclient?view=azure-dotnet). Authentication to AKV via this client is configured using the exact same `TokenCredential` provided by the [Azure Identity client library for .NET](https://learn.microsoft.com/en-us/dotnet/api/overview/azure/identity-readme?view=azure-dotnet). This means that the Service Principal described in the [Azure Configuration](#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 `AppGwBin` Certificate Store Type and installing the Azure Application Gateway Universal Orchestrator extension, you can create new [Certificate Stores](https://software.keyfactor.com/Core-OnPrem/Current/Content/ReferenceGuide/Certificate%20Stores.htm?Highlight=certificate%20store) to manage certificates in the remote platform. The following table describes the required and optional fields for the `AppGwBin` certificate store type. -| Attribute | Description | -| --------- | ----------- | -| Category | Select "Azure Application Gateway Certificate Binding" 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 `AppGwBin` certificates. Specifically, one with the `AzureAppGwBin` 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](#client-certificate-or-client-secret) 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. | +| Attribute | Description | Attribute is PAM Eligible | +| --------- | ----------- | ------------------------- | +| Category | Select "Azure Application Gateway Certificate Binding" 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 `AppGwBin` certificates. Specifically, one with the `AzureAppGwBin` 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](#client-certificate-or-client-secret) 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** @@ -226,4 +228,5 @@ The following table describes the required and optional fields for the `AppGwBin kfutil stores import csv --store-type-name AppGwBin --file AppGwBin.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. \ No newline at end of file +* **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. + diff --git a/docs/azureappgw.md b/docs/azureappgw.md index be302c1..a2a7b16 100644 --- a/docs/azureappgw.md +++ b/docs/azureappgw.md @@ -23,11 +23,11 @@ The Azure Application Gateway Certificate store type, `AzureAppGw`, manages `App ## Requirements -### Azure Service Principal (Azure Resource Manager Authentication) +#### Azure Service Principal (Azure Resource Manager Authentication) The Azure Application Gateway Orchestrator extension uses an [Azure Service Principal](https://learn.microsoft.com/en-us/entra/identity-platform/app-objects-and-service-principals?tabs=browser) for authentication. Follow [Microsoft's documentation](https://learn.microsoft.com/en-us/entra/identity-platform/howto-create-service-principal-portal) to create a service principal. -#### Azure Application Gateway permissions +##### 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](https://learn.microsoft.com/en-us/azure/role-based-access-control/built-in-roles#contributor). For production environments, a custom role should be created that grants the following permissions: @@ -39,13 +39,13 @@ For quick start and non-production environments, a Role Assignment should be cre > 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 +##### 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](#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](https://learn.microsoft.com/en-us/azure/key-vault/general/rbac-guide?tabs=azure-cli) built-in role. * **Vault access policy** - [Create an Access Policy](https://learn.microsoft.com/en-us/azure/key-vault/general/assign-access-policy?tabs=azure-portal) that grants the Application/Service Principal the Get secret permission for each Azure Key Vault. -#### Client Certificate or Client Secret +##### Client Certificate or Client Secret Beginning in version 3.0.0, the Azure Application Gateway Orchestrator extension supports both [client certificate authentication](https://learn.microsoft.com/en-us/graph/auth-register-app-v2#option-1-add-a-certificate) and [client secret](https://learn.microsoft.com/en-us/graph/auth-register-app-v2#option-2-add-a-client-secret) authentication. @@ -95,37 +95,6 @@ Beginning in version 3.0.0, the Azure Application Gateway Orchestrator extension > You will use `clientcert.[pem|pfx].base64` as the **ClientCertificate** field in the [Certificate Store Configuration](#certificate-store-configuration) section. - -## 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. -- `,,...` - 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.azure.net/secrets/`), 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](https://learn.microsoft.com/en-us/dotnet/api/azure.security.keyvault.secrets.secretclient?view=azure-dotnet). Authentication to AKV via this client is configured using the exact same `TokenCredential` provided by the [Azure Identity client library for .NET](https://learn.microsoft.com/en-us/dotnet/api/overview/azure/identity-readme?view=azure-dotnet). This means that the Service Principal described in the [Azure Configuration](#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 Type Configuration The recommended method for creating the `AzureAppGw` Certificate Store Type is to use [kfutil](https://github.com/Keyfactor/kfutil). After installing, use the following command to create the `` Certificate Store Type: @@ -191,24 +160,57 @@ The Custom Fields tab should look like this: + +## 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. +- `,,...` - 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.azure.net/secrets/`), 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](https://learn.microsoft.com/en-us/dotnet/api/azure.security.keyvault.secrets.secretclient?view=azure-dotnet). Authentication to AKV via this client is configured using the exact same `TokenCredential` provided by the [Azure Identity client library for .NET](https://learn.microsoft.com/en-us/dotnet/api/overview/azure/identity-readme?view=azure-dotnet). This means that the Service Principal described in the [Azure Configuration](#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](https://software.keyfactor.com/Core-OnPrem/Current/Content/ReferenceGuide/Certificate%20Stores.htm?Highlight=certificate%20store) to manage certificates in the remote platform. The following table describes the required and optional fields for the `AzureAppGw` certificate store type. -| Attribute | Description | -| --------- | ----------- | -| 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](#client-certificate-or-client-secret) 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. | +| 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](#client-certificate-or-client-secret) 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** @@ -222,4 +224,5 @@ The following table describes the required and optional fields for the `AzureApp 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. \ No newline at end of file +* **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. + diff --git a/docsource/images/AppGwBin-advanced-store-type-dialog.png b/docsource/images/AppGwBin-advanced-store-type-dialog.png index 2b71e8c..534ecb2 100644 Binary files a/docsource/images/AppGwBin-advanced-store-type-dialog.png and b/docsource/images/AppGwBin-advanced-store-type-dialog.png differ diff --git a/docsource/images/AppGwBin-basic-store-type-dialog.png b/docsource/images/AppGwBin-basic-store-type-dialog.png index d7ac55d..5068d7c 100644 Binary files a/docsource/images/AppGwBin-basic-store-type-dialog.png and b/docsource/images/AppGwBin-basic-store-type-dialog.png differ diff --git a/docsource/images/AppGwBin-custom-fields-store-type-dialog.png b/docsource/images/AppGwBin-custom-fields-store-type-dialog.png index 296cd70..c6bbf79 100644 Binary files a/docsource/images/AppGwBin-custom-fields-store-type-dialog.png and b/docsource/images/AppGwBin-custom-fields-store-type-dialog.png differ diff --git a/docsource/images/AzureAppGw-advanced-store-type-dialog.png b/docsource/images/AzureAppGw-advanced-store-type-dialog.png index 2b71e8c..534ecb2 100644 Binary files a/docsource/images/AzureAppGw-advanced-store-type-dialog.png and b/docsource/images/AzureAppGw-advanced-store-type-dialog.png differ diff --git a/docsource/images/AzureAppGw-basic-store-type-dialog.png b/docsource/images/AzureAppGw-basic-store-type-dialog.png index accfde4..642619c 100644 Binary files a/docsource/images/AzureAppGw-basic-store-type-dialog.png and b/docsource/images/AzureAppGw-basic-store-type-dialog.png differ diff --git a/docsource/images/AzureAppGw-custom-fields-store-type-dialog.png b/docsource/images/AzureAppGw-custom-fields-store-type-dialog.png index 296cd70..c6bbf79 100644 Binary files a/docsource/images/AzureAppGw-custom-fields-store-type-dialog.png and b/docsource/images/AzureAppGw-custom-fields-store-type-dialog.png differ diff --git a/integration-manifest.json b/integration-manifest.json index 9dc4c87..22d56d4 100644 --- a/integration-manifest.json +++ b/integration-manifest.json @@ -1,5 +1,5 @@ { - "$schema": "https://keyfactor.github.io/integration-manifest-schema.json", + "$schema": "https://keyfactor.github.io/v2/integration-manifest-schema.json", "name": "Azure Application Gateway Orchestrator", "integration_type": "orchestrator", "status": "production", diff --git a/readme_source.md b/readme_source.md deleted file mode 100644 index 6fc09c7..0000000 --- a/readme_source.md +++ /dev/null @@ -1,279 +0,0 @@ -

- Azure Application Gateway Universal Orchestrator Extension -

- -

- -Integration Status: production -Release -Issues -GitHub Downloads (all assets, all releases) -

- -

- - - Support - - · - - Installation - - · - - License - - · - - Related Integrations - -

- - -## Overview -The Azure Application Gateway Orchestrator extension remotely manages certificates used by Azure Application Gateways. The extension supports two different store types - one that generally manages certificates stored in the Application Gateway, and one that manages the bindings of Application Gateway certificates to HTTPS/TLS Listeners. - -> The extension manages only App Gateway Certificates, _not_ Azure Key Vault certificates. Certificates imported from Azure Key Vault to Azure Application Gateways will be downloaded for certificate inventory purposes _only_. The Azure Application Gateway orchestrator extension will _not_ perform certificate management operations on Azure Key Vault secrets. If you need to manage certificates in Azure Key Vault, use the [Azure Key Vault Orchestrator](https://github.com/Keyfactor/azurekeyvault-orchestrator). -> -> If the certificate management capabilities of Azure Key Vault are desired over direct management of certificates in Application Gateways, the Azure Key Vault orchestrator can be used in conjunction with this extension for accurate certificate location reporting via the inventory job type. This management strategy requires manual binding of certificates imported to an Application Gateway from AKV and can result in broken state in the Azure Application Gateway in the case that the secret is deleted in AKV. - - -## Installation -Before installing the Azure Application Gateway Universal Orchestrator extension, it's recommended to install [kfutil](https://github.com/Keyfactor/kfutil). Kfutil is a command-line tool that simplifies the process of creating store types, installing extensions, and instantiating certificate stores in Keyfactor Command. - -The Azure Application Gateway Universal Orchestrator extension implements 2 Certificate Store Types. Depending on your use case, you may elect to install one, or all of these Certificate Store Types. An overview for each type is linked below: -* [Azure Application Gateway Certificate](docs/azureappgw.md) -* [Azure Application Gateway Certificate Binding](docs/appgwbin.md) - -
Azure Application Gateway Certificate - - -1. Follow the [requirements section](docs/azureappgw.md#requirements) to configure a Service Account and grant necessary API permissions. - -
Requirements - - ### Azure Service Principal (Azure Resource Manager Authentication) - - The Azure Application Gateway Orchestrator extension uses an [Azure Service Principal](https://learn.microsoft.com/en-us/entra/identity-platform/app-objects-and-service-principals?tabs=browser) for authentication. Follow [Microsoft's documentation](https://learn.microsoft.com/en-us/entra/identity-platform/howto-create-service-principal-portal) 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](https://learn.microsoft.com/en-us/azure/role-based-access-control/built-in-roles#contributor). 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](#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](https://learn.microsoft.com/en-us/azure/key-vault/general/rbac-guide?tabs=azure-cli) built-in role. - * **Vault access policy** - [Create an Access Policy](https://learn.microsoft.com/en-us/azure/key-vault/general/assign-access-policy?tabs=azure-portal) 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](https://learn.microsoft.com/en-us/graph/auth-register-app-v2#option-1-add-a-certificate) and [client secret](https://learn.microsoft.com/en-us/graph/auth-register-app-v2#option-2-add-a-client-secret) authentication. - - * **Client Secret** - Follow [Microsoft's documentation](https://learn.microsoft.com/en-us/graph/auth-register-app-v2#option-2-add-a-client-secret) to create a Client Secret. This secret will be used as the **Server Password** field in the [Certificate Store Configuration](#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](#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](https://learn.microsoft.com/en-us/graph/auth-register-app-v2#option-1-add-a-certificate) 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](#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: - > - > ```shell - > # Verify that the certificate downloaded from Command contains the certificate and private key. They should be in the same file - > cat - > - > # Separate the certificate from the private key - > openssl x509 -in -out pubkeycert.pem - > - > # Base64 encode the certificate and private key - > cat | base64 > clientcertkeypair.pem.base64 - > ``` - > - > * If you downloaded the certificate in PFX format, use the commands below: - > - > ```shell - > # Export the certificate from the PFX file - > openssl pkcs12 -in -clcerts -nokeys -out pubkeycert.pem - > - > # Base64 encode the PFX file - > cat | base64 > clientcert.pfx.base64 - > ``` - > 7. Follow [Microsoft's documentation](https://learn.microsoft.com/en-us/graph/auth-register-app-v2#option-1-add-a-certificate) 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](#certificate-store-configuration) section. - - - -
- -2. Create Certificate Store Types for the Azure Application Gateway Orchestrator extension. - - * **Using kfutil**: - - ```shell - # Azure Application Gateway Certificate - kfutil store-types create AzureAppGw - ``` - - * **Manually**: - * [Azure Application Gateway Certificate](docs/azureappgw.md#certificate-store-type-configuration) - -3. Install the Azure Application Gateway Universal Orchestrator extension. - - * **Using kfutil**: On the server that that hosts the Universal Orchestrator, run the following command: - - ```shell - # Windows Server - kfutil orchestrator extension -e azure-appgateway-orchestrator@latest --out "C:\Program Files\Keyfactor\Keyfactor Orchestrator\extensions" - - # Linux - kfutil orchestrator extension -e azure-appgateway-orchestrator@latest --out "/opt/keyfactor/orchestrator/extensions" - ``` - - * **Manually**: Follow the [official Command documentation](https://software.keyfactor.com/Core-OnPrem/Current/Content/InstallingAgents/NetCoreOrchestrator/CustomExtensions.htm?Highlight=extensions) to install the latest [Azure Application Gateway Universal Orchestrator extension](https://github.com/Keyfactor/azure-appgateway-orchestrator/releases/latest). - -4. Create new certificate stores in Keyfactor Command for the Sample Universal Orchestrator extension. - * [Azure Application Gateway Certificate](docs/azureappgw.md#certificate-store-configuration) -
- -
Azure Application Gateway Certificate Binding - - -1. Follow the [requirements section](docs/appgwbin.md#requirements) to configure a Service Account and grant necessary API permissions. - -
Requirements - - ### Azure Service Principal (Azure Resource Manager Authentication) - - The Azure Application Gateway Orchestrator extension uses an [Azure Service Principal](https://learn.microsoft.com/en-us/entra/identity-platform/app-objects-and-service-principals?tabs=browser) for authentication. Follow [Microsoft's documentation](https://learn.microsoft.com/en-us/entra/identity-platform/howto-create-service-principal-portal) 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](https://learn.microsoft.com/en-us/azure/role-based-access-control/built-in-roles#contributor). 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](#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](https://learn.microsoft.com/en-us/azure/key-vault/general/rbac-guide?tabs=azure-cli) built-in role. - * **Vault access policy** - [Create an Access Policy](https://learn.microsoft.com/en-us/azure/key-vault/general/assign-access-policy?tabs=azure-portal) 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](https://learn.microsoft.com/en-us/graph/auth-register-app-v2#option-1-add-a-certificate) and [client secret](https://learn.microsoft.com/en-us/graph/auth-register-app-v2#option-2-add-a-client-secret) authentication. - - * **Client Secret** - Follow [Microsoft's documentation](https://learn.microsoft.com/en-us/graph/auth-register-app-v2#option-2-add-a-client-secret) to create a Client Secret. This secret will be used as the **Server Password** field in the [Certificate Store Configuration](#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](#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](https://learn.microsoft.com/en-us/graph/auth-register-app-v2#option-1-add-a-certificate) 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](#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: - > - > ```shell - > # Verify that the certificate downloaded from Command contains the certificate and private key. They should be in the same file - > cat - > - > # Separate the certificate from the private key - > openssl x509 -in -out pubkeycert.pem - > - > # Base64 encode the certificate and private key - > cat | base64 > clientcertkeypair.pem.base64 - > ``` - > - > * If you downloaded the certificate in PFX format, use the commands below: - > - > ```shell - > # Export the certificate from the PFX file - > openssl pkcs12 -in -clcerts -nokeys -out pubkeycert.pem - > - > # Base64 encode the PFX file - > cat | base64 > clientcert.pfx.base64 - > ``` - > 7. Follow [Microsoft's documentation](https://learn.microsoft.com/en-us/graph/auth-register-app-v2#option-1-add-a-certificate) 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](#certificate-store-configuration) section. - - - -
- -2. Create Certificate Store Types for the Azure Application Gateway Orchestrator extension. - - * **Using kfutil**: - - ```shell - # Azure Application Gateway Certificate Binding - kfutil store-types create AppGwBin - ``` - - * **Manually**: - * [Azure Application Gateway Certificate Binding](docs/appgwbin.md#certificate-store-type-configuration) - -3. Install the Azure Application Gateway Universal Orchestrator extension. - - * **Using kfutil**: On the server that that hosts the Universal Orchestrator, run the following command: - - ```shell - # Windows Server - kfutil orchestrator extension -e azure-appgateway-orchestrator@latest --out "C:\Program Files\Keyfactor\Keyfactor Orchestrator\extensions" - - # Linux - kfutil orchestrator extension -e azure-appgateway-orchestrator@latest --out "/opt/keyfactor/orchestrator/extensions" - ``` - - * **Manually**: Follow the [official Command documentation](https://software.keyfactor.com/Core-OnPrem/Current/Content/InstallingAgents/NetCoreOrchestrator/CustomExtensions.htm?Highlight=extensions) to install the latest [Azure Application Gateway Universal Orchestrator extension](https://github.com/Keyfactor/azure-appgateway-orchestrator/releases/latest). - -4. Create new certificate stores in Keyfactor Command for the Sample Universal Orchestrator extension. - * [Azure Application Gateway Certificate Binding](docs/appgwbin.md#certificate-store-configuration) -
- - -## License - -Apache License 2.0, see [LICENSE](LICENSE). - -## Related Integrations - -See all [Keyfactor Universal Orchestrator extensions](https://github.com/orgs/Keyfactor/repositories?q=orchestrator). \ No newline at end of file