Skip to content

Commit b2810a6

Browse files
fiddlermikeyfiddlermikey
authored
Merge pull request #12 from Keyfactor/sdk-default-auth
ab#54216 - release 2.0 - support Default SDK auth
2 parents 5c0e8e4 + 1975107 commit b2810a6

20 files changed

+1503
-1155
lines changed

‎CHANGELOG.md

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,18 @@
1+
2.0.0
2+
* Consolidate all AWS auth types under one Store Type: `AWS-ACM`
3+
* Continues to provide backwards support for previous Store Types `AwsCerManO` and `AwsCerManA`
4+
* This support will be removed in a future version, it is now considered `DEPRECATED`
5+
* Support choosing auth type:
6+
* OAuth Provider
7+
* AWS IAM User
8+
* Inferred credentials present on an EC2 instance running the orchestrator
9+
* The valid sources for credentials received in this manner can be found here:
10+
https://docs.aws.amazon.com/sdk-for-net/v3/developer-guide/creds-assign.html
11+
* PAM Provider support for the following fields:
12+
* `ServerUsername`
13+
* `ServerPassword`
14+
* These fields are supported on all Store Types (including backwards support): `AWS-ACM`, `AwsCerMan0` and `AwsCerManA`
15+
116
1.2.0
217
* Added OTKA Auth Path to support Authentication Servers outside of the default server.
318

‎README.md

Lines changed: 163 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
1-
# AWS Orchestrator
1+
# AWS Certificate Manager (ACM) Orchestrator
22

3-
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.
3+
The AWS ACM Orchestrator supports Inventory and Management of certificates in the AWS Certificate Manager. It supports three methods of authentication: Environmental Credentials loaded via the AWS SDK e.g. inside an EC2 instance; IAM User Credentials for assuming a Role as a specific user; OAuth-based Credentials to authenticate with an OAuth provider to assume a Role.
44

55
#### Integration status: Production - Ready for use in production environments.
66

@@ -14,9 +14,9 @@ The Universal Orchestrator is part of the Keyfactor software distribution and is
1414
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.
1515

1616

17-
## Support for AWS Orchestrator
17+
## Support for AWS Certificate Manager (ACM) Orchestrator
1818

19-
AWS Orchestrator
19+
AWS Certificate Manager (ACM) 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
2020

2121
###### 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.
2222

@@ -43,6 +43,55 @@ The Keyfactor Universal Orchestrator may be installed on either Windows or Linux
4343
|Supports Inventory|✓ |✓ |
4444

4545

46+
## PAM Integration
47+
48+
This orchestrator extension has the ability to connect to a variety of supported PAM providers to allow for the retrieval of various client hosted secrets right from the orchestrator server itself. This eliminates the need to set up the PAM integration on Keyfactor Command which may be in an environment that the client does not want to have access to their PAM provider.
49+
50+
The secrets that this orchestrator extension supports for use with a PAM Provider are:
51+
52+
| Name | Description |
53+
| - | - |
54+
| ServerUsername | The AWS Access Key for an IAM User or Client ID for OAuth. Depends on Auth method in use. |
55+
| ServerPassword | The AWS Access Secret for an IAM User or Client Secret for OAuth. Depends on Auth method in use. |
56+
57+
It is not necessary to use a PAM Provider for all of the secrets available above. If a PAM Provider should not be used, simply enter in the actual value to be used, as normal.
58+
59+
If a PAM Provider will be used for one of the fields above, start by referencing the [Keyfactor Integration Catalog](https://keyfactor.github.io/integrations-catalog/content/pam). The GitHub repo for the PAM Provider to be used contains important information such as the format of the `json` needed. What follows is an example but does not reflect the `json` values for all PAM Providers as they have different "instance" and "initialization" parameter names and values.
60+
61+
<details><summary>General PAM Provider Configuration</summary>
62+
<p>
63+
64+
65+
66+
### Example PAM Provider Setup
67+
68+
To use a PAM Provider to resolve a field, in this example the __Server Password__ will be resolved by the `Hashicorp-Vault` provider, first install the PAM Provider extension from the [Keyfactor Integration Catalog](https://keyfactor.github.io/integrations-catalog/content/pam) on the Universal Orchestrator.
69+
70+
Next, complete configuration of the PAM Provider on the UO by editing the `manifest.json` of the __PAM Provider__ (e.g. located at extensions/Hashicorp-Vault/manifest.json). The "initialization" parameters need to be entered here:
71+
72+
~~~ json
73+
"Keyfactor:PAMProviders:Hashicorp-Vault:InitializationInfo": {
74+
"Host": "http://127.0.0.1:8200",
75+
"Path": "v1/secret/data",
76+
"Token": "xxxxxx"
77+
}
78+
~~~
79+
80+
After these values are entered, the Orchestrator needs to be restarted to pick up the configuration. Now the PAM Provider can be used on other Orchestrator Extensions.
81+
82+
### Use the PAM Provider
83+
With the PAM Provider configured as an extenion on the UO, a `json` object can be passed instead of an actual value to resolve the field with a PAM Provider. Consult the [Keyfactor Integration Catalog](https://keyfactor.github.io/integrations-catalog/content/pam) for the specific format of the `json` object.
84+
85+
To have the __Server Password__ field resolved by the `Hashicorp-Vault` provider, the corresponding `json` object from the `Hashicorp-Vault` extension needs to be copied and filed in with the correct information:
86+
87+
~~~ json
88+
{"Secret":"my-kv-secret","Key":"myServerPassword"}
89+
~~~
90+
91+
This text would be entered in as the value for the __Server Password__, instead of entering in the actual password. The Orchestrator will attempt to use the PAM Provider to retrieve the __Server Password__. If PAM should not be used, just directly enter in the value for the field.
92+
</p>
93+
</details>
94+
4695

4796

4897

@@ -75,7 +124,111 @@ AWS Certificate Manager is a service that lets you easily provision, manage, and
75124
## **Installation**
76125
Depending on your choice of authentication providers, choose the appropriate configuration section
77126
<details>
78-
<summary>AWS Certificate Manager with Okta Auth Configuration</summary>
127+
<summary>AWS Certificate Manager <code>AWS-ACM</code></summary>
128+
129+
### AWS Setup
130+
Options for authenticating:
131+
1. Okta or other OAuth configuration (refer to `AwsCerManO` below)
132+
2. IAM User Auth configuration (refer to `AwsCerManA` below)
133+
3. EC2 Role Auth or other default method supported by the [AWS SDK](https://docs.aws.amazon.com/sdk-for-net/v3/developer-guide/creds-assign.html)
134+
135+
As one option for #3, to set up Role Auth for an EC2 instance, follow the steps below. Note, this applies specifically __when the orchestrator is running `ACM-AWS` inside of an EC2 instance__.
136+
1. Assign or note the existing IAM Role assigned to the EC2 instance running
137+
2. Make sure that role has access to ACM
138+
3. When configuring the `AWS-ACM` store, do not select either IAM or OAuth methods in the store's settings. This will make it use the AWS SDK to lookup EC2 credentials.
139+
140+
<details>
141+
<summary><code>AWS-ACM</code> Cert Store Type and Cert Store Setup</summary>
142+
143+
Cert Store Type Settings
144+
===============
145+
**Basic Settings:**
146+
147+
CONFIG ELEMENT | VALUE | DESCRIPTION
148+
--|--|--
149+
Name | AWS Certificate Manager | Display name for the store type (may be customized)
150+
Short Name| AWS-ACM | Short display name for the store type
151+
Custom Capability | N/A | Store type name orchestrator will register with. Check the box to allow entry of value
152+
Supported Job Types | Inventory, Add, Remove | Job types the extension supports
153+
Needs Server | Checked | Determines if a target server name is required when creating store
154+
Blueprint Allowed | Checked | Determines if store type may be included in an Orchestrator blueprint
155+
Uses PowerShell | Unchecked | Determines if underlying implementation is PowerShell
156+
Requires Store Password | Unchecked | Determines if a store password is required when configuring an individual store.
157+
Supports Entry Password | Unchecked | Determines if an individual entry within a store can have a password.
158+
159+
160+
**Advanced Settings:**
161+
162+
CONFIG ELEMENT | VALUE | DESCRIPTION
163+
--|--|--
164+
Store Path Type | Freeform | Determines what restrictions are applied to the store path field when configuring a new store.
165+
Store Path Value | N/A | This is reserved for the AWS Account Id when setting up the store.
166+
Supports Custom Alias | Optional | Determines if an individual entry within a store can have a custom Alias.
167+
Private Keys | Optional | This determines if Keyfactor can send the private key associated with a certificate to the store.
168+
PFX Password Style | Default or Custom | "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.)
169+
170+
**Custom Fields:**
171+
172+
Custom fields operate at the certificate store level and are used to control how the orchestrator connects to the remote
173+
target server containing the certificate store to be managed
174+
175+
Name|Display Name|Type|Default Value|Depends On|Required|Description
176+
---|---|---|---|---|---|---
177+
UseOAuth | Use OAuth 2.0 Provider | boolean | False | N/A | Yes | A switch to enable the store to use an OAuth provider workflow to authenticate with AWS ACM
178+
UseIAM | Use IAM User Auth | boolean | False | N/A | Yes | A switch to enable the store to use IAM User auth to assume a role when authenticating with AWS ACM
179+
OAuthScope | OAuth Scope | string | N/A | Use OAuth 2.0 Provider | No | This is the OAuth Scope needed for Okta OAuth, defined in Okta
180+
OAuthGrantType | OAuth Grant Type | string | client_credentials | Use OAuth 2.0 Provider | No | In OAuth 2.0, the term “grant type” refers to the way an application gets an access token. In Okta this is `client_credentials`
181+
OAuthUrl | OAuth URL | string | https://***/oauth2/default/v1/token | Use OAuth 2.0 Provider | No | The URL to request a token from your OAuth Provider. Fill this out with the correct URL.
182+
OAuthAccountId | OAuth AWS Account Id | string | N/A | Use OAuth 2.0 Provider | No | The AWS account ID to use after getting an OAuth token to assume the associated Role.
183+
IamAccountId | IAM AWS Account ID | string | N/A | Use IAM User Auth | No | The AWS account ID to use when assuming a role as the IAM User.
184+
185+
186+
**Entry Parameters:**
187+
188+
Entry parameters are inventoried and maintained for each entry within a certificate store.
189+
They are typically used to support binding of a certificate to a resource.
190+
191+
While `AWS Region` can be set to multiple choice as noted below, you will need to list all regions you want available for adding certificates.
192+
You can instead make this a String type in order to allow the region to be specified later without knowing all valid regions now.
193+
194+
Name|Display Name| Type|Default Value|Required When|Description
195+
---|---|---|---|---|---
196+
AWS Region | AWS Region | Multiple Choice | us-east-1 | Adding | When adding, this is the Region that the Certificate will be added to.
197+
198+
199+
200+
Cert Store Settings
201+
===============
202+
| Name | Value | Description |
203+
| ----------- | ----------- | ----------- |
204+
| Client Machine | AWS Role | This is the AWS Role that will be used for access. This role will be assumed and its permissions will apply to all actions taken by the orchestrator. |
205+
| User Name | See Below | See Below |
206+
| Password | See Below | See Below |
207+
| Store Path | us-east-1,us-east-2,...,etc. | The AWS Region, or a comma-separated list of multiple regions, the store will operate in. |
208+
| Use OAuth 2.0 Provider | Use an OAuth provider to authenticate with AWS | Set to true to enable OAuth usage and display additional OAuth fields |
209+
| Use IAM User Auth | Use an IAM user's credentials to assume a role | Set to true to enable IAM user auth and the IAM Account ID field. |
210+
| OAuth Scope | Look in OAuth provider for Scope | Displayed and required when using OAuth 2.0 Provider. OAuth scope setup in the Okta Application or other OAuth provider |
211+
| OAuth Grant Type | client_credentials | Displayed and required when using OAuth 2.0 Provider. This may vary depending on Okta setup but will most likely be this value. |
212+
| OAuth URL | https://***/oauth2/default/v1/token | Displayed and required when using OAuth 2.0 Provider. URL to request token from OAuth provider. Example given is for an Okta token. |
213+
| OAuth AWS Account Id | AWS account ID number | Displayed and required when using OAuth 2.0 Provider. This account ID is used in conjunction with the OAuth token to assume a role (set in the Client Machine parameter) |
214+
| IAM AWS Account Id | AWS account ID number | Displayed and required when using IAM User Auth. This account ID is used to assume a role (set in the Client Machine parameter) |
215+
216+
The User Name and Password fields are used differently based on the auth method you intend to use. The three options for auth are IAM User, OAuth, or default auth.
217+
218+
| Auth Method | Field | Value |
219+
| - | - | - |
220+
| IAM User | User Name | Set to the IAM User's AWS `Access Key` |
221+
| IAM User | Password | Set to the IAM User's AWS `Access Secret` |
222+
| OAuth 2.0 | User Name | Set to the OAuth `Client ID` |
223+
| OAuth 2.0 | Password | Set to the OAuth `Client Secret` |
224+
| Default (SDK) | User Name | No Value |
225+
| Default (SDK) | Password | No Value |
226+
227+
</details>
228+
</details>
229+
230+
<details>
231+
<summary>[Deprecated] AWS Certificate Manager with Okta Auth Configuration <code>AwsCerManO</code></summary>
79232

80233
### AWS Setup
81234
1. A 3rd party [identity provider](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_create_oidc.html) similar to [this](/Images/AWSIdentityProvider.gif) needs to be setup in AWS for each account.
@@ -89,7 +242,7 @@ Depending on your choice of authentication providers, choose the appropriate con
89242

90243

91244
<details>
92-
<summary>Cert Store Type and Cert Store Setup</summary>
245+
<summary><code>AwsCerManO</code> Cert Store Type and Cert Store Setup</summary>
93246

94247
Cert Store Type Settings
95248
===============
@@ -125,8 +278,8 @@ target server containing the certificate store to be managed
125278

126279
Name|Display Name|Type|Default Value / Options|Required|Description
127280
---|---|---|---|---|---
128-
scope | Okta OAuth Scope | string | N/A | Yes | This is the OAuth Scope needed for Okta OAuth
129-
grant_type | Okta OAuth Grant Type | string | N/A | Yes | In OAuth 2.0, the term “grant type” refers to the way an application gets an access token
281+
scope | Okta OAuth Scope | string | N/A | Yes | This is the OAuth Scope needed for Okta OAuth, defined in Okta
282+
grant_type | Okta OAuth Grant Type | string | N/A | Yes | In OAuth 2.0, the term “grant type” refers to the way an application gets an access token. In Okta this is `client_credentials`
130283
oauthpath | OKTA OAuth Path | string | /oauth2/default/v1/token | Yes | In path to the OAuth Server. It will Default to the Default Server. If you use something outside of the Default, change this.
131284
awsrole | AWS Assume Identity Role | string | N/A | Yes | This role has to be created in AWS IAM so you can assume an identity and get temp credentials
132285
awsregions | AWS Regions | string | N/A | Yes | This will be the list of regions for the account the store iterates through when doing inventory.
@@ -164,7 +317,7 @@ Cert Store Settings
164317
</details>
165318

166319
<details>
167-
<summary>AWS Certificate Manager with IAM Auth Configuration</summary>
320+
<summary>[Deprecated] AWS Certificate Manager with IAM Auth Configuration <code>AwsCerManA</code></summary>
168321

169322
### AWS Setup
170323
1. An Aws [Role](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-user.html) Needs Added for the permissions you want to grant, see [sample](/Images/AWSRole1.gif).
@@ -173,7 +326,7 @@ Cert Store Settings
173326

174327

175328
<details>
176-
<summary>Cert Store Type and Cert Store Setup</summary>
329+
<summary><code>AwsCerManA</code> Cert Store Type and Cert Store Setup</summary>
177330

178331
Cert Store Type Settings
179332
===============

0 commit comments

Comments
 (0)