Skip to content

Commit bf5cb89

Browse files
m8rmclarenm8rmclaren
committed
Merge branch 'nullcert-53654' of github.com:Keyfactor/azure-appgateway-orchestrator into nullcert-53654
chore(rebase): Rebase nullcert-53654
2 parents d8e0a71 + 06dd91a commit bf5cb89

File tree

1 file changed

+103
-119
lines changed

1 file changed

+103
-119
lines changed

‎README.md‎

Lines changed: 103 additions & 119 deletions
Original file line numberDiff line numberDiff line change
@@ -54,6 +54,8 @@ The Azure Application Gateway Orchestrator extension remotely manages certificat
5454
Application Gateways. The extension implements the Inventory, Management Add, Management Remove,
5555
and Discovery job types.
5656

57+
> The extension manages only App Gateway Certificates, _not_ Azure Key Vault certificates. The extension cannot inventory or manage certificates imported from Azure Key Vault. If you need to manage certificates in Azure Key Vault, use the [Azure Key Vault Orchestrator](https://github.com/Keyfactor/azurekeyvault-orchestrator).
58+
5759
The Add and Remove operations create and remove _ApplicationGatewaySslCertificate_'s associated with
5860
the Application Gateway. The Add operation implements an optional enrollment field for an HTTP Listener name. If
5961
provided, the certificate will be associated with the listener. If a certificate is associated with a listener,
@@ -68,126 +70,108 @@ The Azure Application Gateway Orchestrator extension uses an Azure Service Princ
6870
[documentation](https://learn.microsoft.com/en-us/azure/purview/create-service-principal-azure) to create a service principal.
6971
For quick start, the service principal should be granted the Contributor role on the resource group that manages the Application Gateway.
7072
For production environments, the service principal should be granted the least privilege required to manage the Application Gateway.
73+
Specifically, the service principal should be granted a role that enables Read and Write for `Microsoft.Network``
74+
75+
## Creating Store Types for the Azure Application Gateway Orchestrator
76+
To get started with the Azure Application Gateway Orchestrator Extension, you'll need to create a store type in Keyfactor Command. The recommended and supported way to create store types is using the `kfutil` command line tool. Install [Kfutil](https://github.com/Keyfactor/kfutil) if it is not already installed. Once installed, use `kfutil login` to log into the target Command environment.
77+
78+
Then, use the following command to create the store types:
79+
80+
81+
```shell
82+
kfutil store-types create AzureAppGW
83+
```
84+
85+
It is not required to create all store types. Only create the store types that are needed for the integration.
86+
87+
If you prefer to create store types manually in the UI, navigate to your Command instance and follow the instructions below.
88+
<details><summary>AzureAppGW</summary>
89+
90+
Create a store type called `AzureAppGW` with the attributes in the tables below:
91+
92+
### Basic Tab
93+
| Attribute | Value | Description |
94+
| --------- | ----- | ----- |
95+
| Name | Azure Application Gateway | Display name for the store type (may be customized) |
96+
| Short Name | AzureAppGW | Short display name for the store type |
97+
| Capability | AzureAppGW | Store type name orchestrator will register with. Check the box to allow entry of value |
98+
| Supported Job Types (check the box for each) | Add, Discovery, Remove | Job types the extension supports |
99+
| Needs Server | &check; | Determines if a target server name is required when creating store |
100+
| Blueprint Allowed | | Determines if store type may be included in an Orchestrator blueprint |
101+
| Uses PowerShell | | Determines if underlying implementation is PowerShell |
102+
| Requires Store Password | | Determines if a store password is required when configuring an individual store. |
103+
| Supports Entry Password | | Determines if an individual entry within a store can have a password. |
104+
105+
106+
The Basic tab should look like this:
107+
108+
![AzureAppGW Basic Tab](.github/images/AzureAppGW-basic-store-type-dialog.png)
109+
110+
### Advanced Tab
111+
| Attribute | Value | Description |
112+
| --------- | ----- | ----- |
113+
| Supports Custom Alias | Required | Determines if an individual entry within a store can have a custom Alias. |
114+
| 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. |
115+
| 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.) |
116+
117+
118+
The Advanced tab should look like this:
119+
120+
![AzureAppGW Advanced Tab](.github/images/AzureAppGW-advanced-store-type-dialog.png)
121+
122+
### Custom Fields Tab
123+
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:
124+
125+
| Name | Display Name | Type | Default Value/Options | Required | Description |
126+
| ---- | ------------ | ---- | --------------------- | -------- | ----------- |
127+
| ServerUsername | Server Username | Secret | None | &check; | Application ID of the service principal that will be used to manage the Application Gateway. |
128+
| ServerPassword | Server Password | Secret | None | &check; | Secret of the service principal that will be used to manage the Application Gateway. |
129+
| ServerUseSsl | Use SSL | Bool | true | | Indicates whether SSL should be used |
130+
| AzureCloud | Azure Cloud | MultipleChoice | public,china,germany,government | | The Azure Cloud field, if necessary, should contain one of the following values: 'china, germany, government'. This field specifies the Azure Cloud instance used by the organization. If using the standard 'public' cloud, this field can be left blank or omitted from the store type definition. |
131+
132+
133+
The Custom Fields tab should look like this:
134+
135+
![AzureAppGW Custom Fields Tab](.github/images/AzureAppGW-custom-fields-store-type-dialog.png)
136+
137+
### Entry Parameters Tab
138+
Entry parameters are inventoried and maintained for each entry within a certificate store. They are typically used to support binding of a certificate to a resource. The following entry parameters should be added to the store type:
139+
140+
141+
142+
| Name | Display Name | Type | Default Value | Entry has a private key | Adding an entry | Removing an entry | Reenrolling an entry | Description |
143+
| ---- | ------------ | ---- | ------------- | ----------------------- | ---------------- | ----------------- | ------------------- | ----------- |
144+
| HTTPListenerName | HTTP Listener Name | String | None | | | | | The name of the HTTP listener to which the certificate will be bound. |
145+
146+
147+
The Entry Parameters tab should look like this:
148+
149+
![AzureAppGW Entry Parameters Tab](.github/images/./AzureAppGW-entry-parameters-store-type-dialog.png)
150+
151+
</details>
152+
153+
## Instantiating New Azure Application Gateway Orchestrator Stores
154+
Once the store types have been created, you can instantiate certificate stores for the store type. This section describes how to instantiate a certificate store for each store type. Creating new certificate stores is how certificates in the remote platform are inventoried and managed by the orchestrator.
155+
<details><summary>AzureAppGW</summary>
156+
157+
In Keyfactor Command, navigate to Certificate Stores from the Locations Menu. Click the Add button to create a new Certificate Store using the settings defined below.
158+
159+
| Attribute | Description |
160+
| --------- | ----------- |
161+
| Category | Select Azure Application Gateway or the customized certificate store name from the previous step. |
162+
| Container | Optional container to associate certificate store with. |
163+
| Client Machine | The Azure Tenant ID of the service principal. |
164+
| Store Path | Azure resource ID of the application gateway in the form `/subscriptions/<subscription-id>/resourceGroups/<resource-group-name>/providers/Microsoft.Network/applicationGateways/<application-gateway-name>` |
165+
| Orchestrator | Select an approved orchestrator capable of managing AzureAppGW certificates. Specifically, one with the AzureAppGW capability. |
166+
| Server Username | Application ID of the service principal that will be used to manage the Application Gateway. |
167+
| Server Password | Secret of the service principal that will be used to manage the Application Gateway. |
168+
| Use SSL | Indicates whether SSL should be used |
169+
| Azure Cloud | The Azure Cloud field, if necessary, should contain one of the following values: 'china, germany, government'. This field specifies the Azure Cloud instance used by the organization. If using the standard 'public' cloud, this field can be left blank or omitted from the store type definition. |
170+
| HTTP Listener Name | The name of the HTTP listener to which the certificate will be bound. |
171+
172+
173+
</details>
71174

72-
## Keyfactor Configuration
73-
Follow the Keyfactor Orchestrator configuration guide to install the Azure Application Gateway Orchestrator extension.
74-
75-
This guide uses the `kfutil` Keyfactor command line tool that offers convenient and powerful
76-
command line access to the Keyfactor platform. Before proceeding, ensure that `kfutil` is installed and configured
77-
by following the instructions here: [https://github.com/Keyfactor/kfutil](https://github.com/Keyfactor/kfutil)
78-
79-
Configuration is done in two steps:
80-
1. Create a new Keyfactor Certificate Store Type
81-
2. Create a new Keyfactor Certificate Store
82-
83-
### Keyfactor Certificate Store Type Configuration
84-
Keyfactor Certificate Store Types are used to define and configure the platforms that store and use certificates that will be managed
85-
by Keyfactor Orchestrators. To create the Azure Application Gateway Certificate Store Type, run the following command with `kfutil`:
86-
```bash
87-
cat << EOF > ./AzureAppGW.json
88-
{
89-
"Name": "Azure Application Gateway",
90-
"ShortName": "AzureAppGW",
91-
"Capability": "AzureAppGW",
92-
"LocalStore": false,
93-
"SupportedOperations": {
94-
"Add": true,
95-
"Create": false,
96-
"Discovery": true,
97-
"Enrollment": false,
98-
"Remove": true
99-
},
100-
"Properties": [
101-
{
102-
"Name": "ServerUsername",
103-
"DisplayName": "Server Username",
104-
"Type": "Secret",
105-
"DependsOn": null,
106-
"DefaultValue": null,
107-
"Required": true
108-
},
109-
{
110-
"Name": "ServerPassword",
111-
"DisplayName": "Server Password",
112-
"Type": "Secret",
113-
"DependsOn": null,
114-
"DefaultValue": null,
115-
"Required": true
116-
},
117-
{
118-
"Name": "AzureCloud",
119-
"DisplayName": "Azure Cloud",
120-
"Type": "MultipleChoice",
121-
"DependsOn": "",
122-
"DefaultValue": "public,china,germany,government",
123-
"Required": false
124-
},
125-
{
126-
"Name": "PrivateEndpoint",
127-
"DisplayName": "Private KeyVault Endpoint",
128-
"Type": "String",
129-
"DependsOn": "",
130-
"DefaultValue": null,
131-
"Required": false
132-
},
133-
{
134-
"Name": "ServerUseSsl",
135-
"DisplayName": "Use SSL",
136-
"Type": "Bool",
137-
"DependsOn": null,
138-
"DefaultValue": "true",
139-
"Required": false
140-
}
141-
],
142-
"EntryParameters": [
143-
{
144-
"Name": "HTTPListenerName",
145-
"DisplayName": "HTTP Listener Name",
146-
"Type": "String",
147-
"RequiredWhen": {
148-
"HasPrivateKey": false,
149-
"OnAdd": false,
150-
"OnRemove": false,
151-
"OnReenrollment": false
152-
}
153-
}
154-
],
155-
"PasswordOptions": {
156-
"EntrySupported": false,
157-
"StoreRequired": false,
158-
"Style": "Default"
159-
},
160-
"PrivateKeyAllowed": "Required",
161-
"ServerRequired": true,
162-
"PowerShell": false,
163-
"BlueprintAllowed": false,
164-
"CustomAliasAllowed": "Required",
165-
"ServerRegistration": 13,
166-
"InventoryEndpoint": "/AnyInventory/Update"
167-
}
168-
EOF
169-
kfutil store-types create --from-file AzureAppGW.json
170-
```
171-
172-
### Keyfactor Store and Discovery Job Configuration
173-
To create a new certificate store in Keyfactor Command, select the _Locations_ drop down, select _Certificate Stores_, and click the _Add_ button.
174-
To schedule a discovery job, select the _Locations_ drop down, select _Certificate Stores_, click on the _Discovery_ button, and click the _Schedule_ button. For both operations,
175-
fill the form with the following values:
176-
177-
| Parameter | Value | Description |
178-
|-----------------|---------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
179-
| Category | 'Azure Application Gateway' | Name of the Appplication Gateway store type |
180-
| Client Machine | Azure Tenant ID | The Azure Tenant ID of the service principal |
181-
| Store Path | Application Gateway resource ID | Azure resource ID of the application gateway in the form `/subscriptions/<subscription-id>/resourceGroups/<resource-group-name>/providers/Microsoft.Network/applicationGateways/<application-gateway-name>` |
182-
| Server Username | Application ID | Application ID of the service principal that will be used to manage the Application Gateway |
183-
| Server Password | Client Secret | Secret of the service principal that will be used to manage the Application Gateway |
184-
| Azure Cloud | Azure Global Cloud Authority Host | The Azure Cloud field, if necessary, should contain one of the following values: "china, germany, government". This is the Azure Cloud instance your organization uses. If using the standard "public" cloud, this field can be left blank or omitted entirely from the store type definition. |
185-
| Private Endpoint | Azure Private Endpoint URL prefix | The Private Endpoint field should be used if you have a custom url assigned to your keyvault resources and they are not accessible via the standard endpoint associated with the Azure Cloud instance (\*.vault.azure.net, \*.vault.azure.cn, etc.). This field should contain the base url for your vault instance(s), excluding the vault name. If using the standard endpoints corresponding to your Azure Cloud instance, this field can be left blank or omitted entirely from the store type definition.|
186-
187-
For the discovery job, populate the _Directories to search_ with any value. The extension will discover all Application Gateways accessible by the Azure Service Principal.
188-
189-
> :warning: Discovery jobs are not supported for KeyVaults located outside of the Azure Public cloud or Keyvaults accessed via a private url endpoint.
190-
> All other job types implemented by this integration are supported for alternate Azure clouds and private endpoints.
191175

192176
### Important note about Certificate Renewal
193177
The Azure Application Gateway Orchestrator extension supports certificate renewal. If a certificate is renewed and is associated with an HTTP Listener,

0 commit comments

Comments
 (0)