Merge pull request #12 from Keyfactor/sdk-default-auth

ab#54216 - release 2.0 - support Default SDK auth

CHANGELOG.md

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

README.md

@@ -1,6 +1,6 @@
-# AWS Orchestrator
+# AWS Certificate Manager (ACM) Orchestrator
 
-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.
+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.
 
 #### Integration status: Production - Ready for use in production environments.
 
@@ -14,9 +14,9 @@ The Universal Orchestrator is part of the Keyfactor software distribution and is
 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 AWS Orchestrator
+## Support for AWS Certificate Manager (ACM) Orchestrator
 
-AWS Orchestrator 
+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
 
 ###### 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.
 
@@ -43,6 +43,55 @@ The Keyfactor Universal Orchestrator may be installed on either Windows or Linux
 |Supports Inventory|✓ |✓ |
 
 
+## PAM Integration
+
+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.
+
+The secrets that this orchestrator extension supports for use with a PAM Provider are:
+
+| Name | Description |
+| - | - |
+| ServerUsername | The AWS Access Key for an IAM User or Client ID for OAuth. Depends on Auth method in use. |
+| ServerPassword | The AWS Access Secret for an IAM User or Client Secret for OAuth. Depends on Auth method in use. |
+
+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.
+
+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.
+
+<details><summary>General PAM Provider Configuration</summary>
+<p>
+
+
+
+### Example PAM Provider Setup
+
+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.
+
+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:
+
+~~~ json
+  "Keyfactor:PAMProviders:Hashicorp-Vault:InitializationInfo": {
+    "Host": "http://127.0.0.1:8200",
+    "Path": "v1/secret/data",
+    "Token": "xxxxxx"
+  }
+~~~
+
+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.
+
+### Use the PAM Provider
+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.
+
+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:
+
+~~~ json
+{"Secret":"my-kv-secret","Key":"myServerPassword"}
+~~~
+
+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.
+</p>
+</details> 
+
 
 
 
@@ -75,7 +124,111 @@ AWS Certificate Manager is a service that lets you easily provision, manage, and
 ## **Installation**
 Depending on your choice of authentication providers, choose the appropriate configuration section
 <details>
-<summary>AWS Certificate Manager with Okta Auth Configuration</summary>
+<summary>AWS Certificate Manager <code>AWS-ACM</code></summary>
+
+### AWS Setup
+Options for authenticating:
+1. Okta or other OAuth configuration (refer to `AwsCerManO` below)
+2. IAM User Auth configuration (refer to `AwsCerManA` below)
+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)
+
+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__.
+1. Assign or note the existing IAM Role assigned to the EC2 instance running
+2. Make sure that role has access to ACM
+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.
+
+<details>
+<summary><code>AWS-ACM</code> Cert Store Type and Cert Store Setup</summary>
+
+Cert Store Type Settings
+===============
+**Basic Settings:**
+
+CONFIG ELEMENT | VALUE | DESCRIPTION
+--|--|--
+Name | AWS Certificate Manager | Display name for the store type (may be customized)
+Short Name| AWS-ACM | Short display name for the store type
+Custom Capability | N/A | Store type name orchestrator will register with. Check the box to allow entry of value
+Supported Job Types | Inventory, Add, Remove | Job types the extension supports
+Needs Server | Checked | Determines if a target server name is required when creating store
+Blueprint Allowed | Checked | Determines if store type may be included in an Orchestrator blueprint
+Uses PowerShell | Unchecked | Determines if underlying implementation is PowerShell
+Requires Store Password	| Unchecked | Determines if a store password is required when configuring an individual store.
+Supports Entry Password	| Unchecked | Determines if an individual entry within a store can have a password.
+
+
+**Advanced Settings:**
+
+CONFIG ELEMENT | VALUE | DESCRIPTION
+--|--|--
+Store Path Type	| Freeform | Determines what restrictions are applied to the store path field when configuring a new store.
+Store Path Value | N/A | This is reserved for the AWS Account Id when setting up the store.
+Supports Custom Alias | Optional | Determines if an individual entry within a store can have a custom Alias.
+Private Keys | Optional | This determines if Keyfactor can send the private key associated with a certificate to the store.
+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.)
+
+**Custom Fields:**
+
+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
+
+Name|Display Name|Type|Default Value|Depends On|Required|Description
+---|---|---|---|---|---|---
+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
+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
+OAuthScope | OAuth Scope | string | N/A | Use OAuth 2.0 Provider | No | This is the OAuth Scope needed for Okta OAuth, defined in Okta
+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`
+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.
+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.
+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.
+
+
+**Entry Parameters:**
+
+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.
+
+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.
+You can instead make this a String type in order to allow the region to be specified later without knowing all valid regions now.
+
+Name|Display Name| Type|Default Value|Required When|Description
+---|---|---|---|---|---
+AWS Region | AWS Region | Multiple Choice | us-east-1 | Adding | When adding, this is the Region that the Certificate will be added to.
+
+
+
+Cert Store Settings
+===============
+| Name | Value | Description |
+| ----------- | ----------- | ----------- |
+| 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. |
+| User Name | See Below | See Below |
+| Password | See Below | See Below |
+| 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. |
+| 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 |
+| 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. |
+| 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 |
+| 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. |
+| 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. |
+| 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) |
+| 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) |
+
+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.
+
+| Auth Method | Field | Value |
+| - | - | - |
+| IAM User | User Name | Set to the IAM User's AWS `Access Key` |
+| IAM User | Password | Set to the IAM User's AWS `Access Secret` |
+| OAuth 2.0 | User Name | Set to the OAuth `Client ID` |
+| OAuth 2.0 | Password | Set to the OAuth `Client Secret` |
+| Default (SDK) | User Name | No Value |
+| Default (SDK) | Password | No Value |
+
+</details>
+</details>
+
+<details>
+<summary>[Deprecated] AWS Certificate Manager with Okta Auth Configuration <code>AwsCerManO</code></summary>
 
 ### AWS Setup
 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
 
 
 <details>
-<summary>Cert Store Type and Cert Store Setup</summary>
+<summary><code>AwsCerManO</code> Cert Store Type and Cert Store Setup</summary>
 
 Cert Store Type Settings
 ===============
@@ -125,8 +278,8 @@ target server containing the certificate store to be managed
 
 Name|Display Name|Type|Default Value / Options|Required|Description
 ---|---|---|---|---|---
-scope | Okta OAuth Scope | string | N/A | Yes | This is the OAuth Scope needed for Okta OAuth
-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
+scope | Okta OAuth Scope | string | N/A | Yes | This is the OAuth Scope needed for Okta OAuth, defined in Okta
+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`
 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.
 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
 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
 </details>
 
 <details>
-	<summary>AWS Certificate Manager with IAM Auth Configuration</summary>
+	<summary>[Deprecated] AWS Certificate Manager with IAM Auth Configuration <code>AwsCerManA</code></summary>
 
 ### AWS Setup
 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
 
 
 <details>
-<summary>Cert Store Type and Cert Store Setup</summary>
+<summary><code>AwsCerManA</code> Cert Store Type and Cert Store Setup</summary>
 
 Cert Store Type Settings
 ===============