diff --git a/.github/workflows/generate-readme.yml b/.github/workflows/generate-readme.yml index 73c40a0..53f6b96 100644 --- a/.github/workflows/generate-readme.yml +++ b/.github/workflows/generate-readme.yml @@ -2,9 +2,34 @@ name: Generate README from templates and data files using doctool on: workflow_call: secrets: - token: + token: description: 'Secret token from caller workflow to approve readme' required: true + entra_username: + description: 'Entra username for authentication' + required: false + entra_password: + description: 'Entra password for authentication' + required: false + command_client_id: + description: 'Command client ID for API authentication' + required: false + command_client_secret: + description: 'Command client secret for API authentication' + required: false + inputs: + command_token_url: + type: string + description: 'URL for obtaining command tokens' + required: false + command_hostname: + type: string + description: 'Command hostname for API endpoints' + required: false + command_base_api_path: + type: string + description: 'Base API path for the Command API' + required: false permissions: contents: write @@ -20,8 +45,15 @@ jobs: path: doctool token: ${{ secrets.token }} - - name: Launch local doctool + - name: Launch local doctool uses: ./doctool id: launch-doctool with: token: ${{ secrets.token }} + entra_username: ${{ secrets.entra_username }} + entra_password: ${{ secrets.entra_password }} + command_client_id: ${{ secrets.command_client_id }} + command_client_secret: ${{ secrets.command_client_secret }} + command_token_url: ${{ vars.DOCTOOL_COMMAND_TOKEN_URL }} + command_hostname: ${{ vars.DOCTOOL_COMMAND_HOSTNAME }} + command_base_api_path: ${{ vars.DOCTOOL_COMMAND_BASE_API_PATH }} diff --git a/.github/workflows/github-release.yml b/.github/workflows/github-release.yml index 9e7a00e..6c5ed9c 100644 --- a/.github/workflows/github-release.yml +++ b/.github/workflows/github-release.yml @@ -20,7 +20,7 @@ on: jobs: call-check-file-action: - uses: keyfactor/actions/.github/workflows/check-todos-license-headers.yml@v3 + uses: keyfactor/actions/.github/workflows/check-todos-license-headers.yml@v4 create-github-release-workflow: runs-on: ubuntu-latest diff --git a/.github/workflows/starter.yml b/.github/workflows/starter.yml index a81a141..5749f49 100644 --- a/.github/workflows/starter.yml +++ b/.github/workflows/starter.yml @@ -5,11 +5,6 @@ on: token: description: 'GitHub token' required: true -## This secret 'APPROVE_README_PUSH' is not used. -## Remove when the v3 bootstrap has been updated - APPROVE_README_PUSH: - description: 'Token to add-and-commit generated readme' - required: true gpg_key: description: 'GPG Private Key' required: true @@ -25,11 +20,35 @@ on: scan_token: description: 'Polaris token' required: false - + entra_username: + description: 'Entra username for authentication' + required: false + entra_password: + description: 'Entra password for authentication' + required: false + command_client_id: + description: 'Command client ID for API authentication' + required: false + command_client_secret: + description: 'Command client secret for API authentication' + required: false + inputs: + command_token_url: + type: string + description: 'URL for obtaining command tokens' + required: false + command_hostname: + type: string + description: 'Command hostname for API endpoints' + required: false + command_base_api_path: + type: string + description: 'Base API path for the Command API' + required: false jobs: call-assign-from-json-workflow: - uses: Keyfactor/actions/.github/workflows/assign-env-from-json.yml@v3 + uses: Keyfactor/actions/.github/workflows/assign-env-from-json.yml@v4 call-get-primary-language: outputs: @@ -78,91 +97,79 @@ jobs: token: ${{ secrets.GITHUB_TOKEN }} - name: Create an array from platform_list input # id: vars - run: + run: echo "platform_matrix=`cat integration-manifest.json | jq '.platform_matrix'`" | tee -a $GITHUB_OUTPUT | tee -a $GITHUB_STEP_SUMMARY call-create-github-release-workflow: - uses: Keyfactor/actions/.github/workflows/github-release.yml@v3 + uses: Keyfactor/actions/.github/workflows/github-release.yml@v4 call-dotnet-build-and-release-workflow: - needs: [call-get-primary-language, call-assign-from-json-workflow, call-create-github-release-workflow] + needs: [ call-get-primary-language, call-assign-from-json-workflow, call-create-github-release-workflow ] if: needs.call-get-primary-language.outputs.primary_language == 'C#' - uses: keyfactor/actions/.github/workflows/dotnet-build-and-release.yml@v3 + uses: keyfactor/actions/.github/workflows/dotnet-build-and-release.yml@v4 with: release_version: ${{ needs.call-create-github-release-workflow.outputs.release_version }} release_url: ${{ needs.call-create-github-release-workflow.outputs.release_url }} release_dir: ${{ needs.call-assign-from-json-workflow.outputs.release_dir }} release_project: ${{ needs.call-assign-from-json-workflow.outputs.release_project }} - integration_type: ${{ needs.call-assign-from-json-workflow.outputs.integration_type }} - secrets: + integration_type: ${{ needs.call-assign-from-json-workflow.outputs.integration_type }} + secrets: token: ${{ secrets.token }} call-go-build-and-release-workflow: - needs: [call-get-primary-language, call-assign-from-json-workflow, call-create-github-release-workflow,call-goreleaser-exists] - if: needs.call-get-primary-language.outputs.primary_language == 'Go' && needs.call-goreleaser-exists.outputs.goreleaser-exists == 'true' - uses: keyfactor/actions/.github/workflows/go-build-and-release.yml@v3 - with: + needs: [ call-get-primary-language, call-assign-from-json-workflow, call-create-github-release-workflow,call-goreleaser-exists ] + if: needs.call-get-primary-language.outputs.primary_language == 'Go' && needs.call-goreleaser-exists.outputs.goreleaser-exists == 'true' + uses: keyfactor/actions/.github/workflows/go-build-and-release.yml@v4 + with: release_version: ${{ needs.call-create-github-release-workflow.outputs.release_version }} - secrets: + secrets: token: ${{ secrets.GITHUB_TOKEN }} gpg_key: ${{ secrets.gpg_key }} gpg_pass: ${{ secrets.gpg_pass }} - call-container-build-and-release-workflow: - needs: [call-get-primary-language, call-assign-from-json-workflow, call-create-github-release-workflow,call-goreleaser-exists,setup_platforms] - if: needs.call-get-primary-language.outputs.primary_language == 'Go' && needs.call-goreleaser-exists.outputs.goreleaser-exists == 'false' - uses: keyfactor/actions/.github/workflows/container-build-and-release.yml@v3 - with: - release_version: ${{ needs.call-create-github-release-workflow.outputs.release_version }} - platform_list: ${{ fromJson(needs.setup_platforms.outputs.platform_matrix) }} - secrets: - docker-user: ${{ secrets.docker-user }} - docker-token: ${{ secrets.docker-token }} - - call-maven-build-and-release-workflow: - needs: [call-get-primary-language, call-assign-from-json-workflow, call-create-github-release-workflow] - if: needs.call-get-primary-language.outputs.primary_language == 'Java' - uses: keyfactor/actions/.github/workflows/maven-build-and-release.yml@v3 - with: - release_version: ${{ needs.call-create-github-release-workflow.outputs.release_version }} - release_url: ${{ needs.call-create-github-release-workflow.outputs.release_url }} - release_dir: ${{ needs.call-assign-from-json-workflow.outputs.release_dir }} - secrets: - token: ${{ secrets.token }} - call-generate-readme-workflow: + permissions: + contents: write # Explicitly grant write permission if: github.event_name == 'push' || github.event_name == 'workflow_dispatch' - uses: Keyfactor/actions/.github/workflows/generate-readme.yml@v3 + uses: Keyfactor/actions/.github/workflows/generate-readme.yml@v4 + with: + command_token_url: ${{ vars.COMMAND_TOKEN_URL }} + command_hostname: ${{ vars.COMMAND_HOSTNAME }} + command_base_api_path: ${{ vars.COMMAND_API_PATH }} secrets: token: ${{ secrets.token }} + entra_username: ${{ secrets.ENTRA_USERNAME }} + entra_password: ${{ secrets.ENTRA_PASSWORD }} + command_client_id: ${{ secrets.COMMAND_CLIENT_ID }} + command_client_secret: ${{ secrets.COMMAND_CLIENT_SECRET }} call-update-catalog-workflow: needs: call-assign-from-json-workflow if: needs.call-assign-from-json-workflow.outputs.update_catalog == 'true' && github.ref_name == 'main' && (github.event_name == 'push' || github.event_name == 'workflow_dispatch') - uses: Keyfactor/actions/.github/workflows/update-catalog.yml@v3 - secrets: + uses: Keyfactor/actions/.github/workflows/update-catalog.yml@v4 + secrets: token: ${{ secrets.token }} call-repository-configuration-workflow: if: github.event_name == 'create' && startsWith(github.ref, 'refs/heads/release-') - uses: Keyfactor/actions/.github/workflows/kf-configure-repo.yml@v3 - secrets: + uses: Keyfactor/actions/.github/workflows/kf-configure-repo.yml@v4 + secrets: token: ${{ secrets.token }} - # call-polaris-scan-workflow: - # if: github.event_name == 'pull_request' && (startsWith(github.base_ref, 'release-') || github.base_ref == 'main') - # uses: Keyfactor/actions/.github/workflows/kf-polaris-scan.yml@v3 - # with: - # scan_branch: ${{ github.event.pull_request.head.ref }} - # secrets: - # token: ${{ secrets.scan_token }} + call-polaris-scan-workflow: + if: github.event_name == 'pull_request' && (startsWith(github.base_ref, 'release-') || github.base_ref == 'main') + uses: Keyfactor/actions/.github/workflows/kf-polaris-scan.yml@v4 + with: + scan_branch: ${{ github.event.pull_request.head.ref }} + secrets: + token: ${{ secrets.scan_token }} call-post-release-workflow: - needs: [call-assign-from-json-workflow, call-create-github-release-workflow] - if: needs.call-create-github-release-workflow.outputs.IS_FULL_RELEASE == 'True' - uses: Keyfactor/actions/.github/workflows/kf-post-release.yml@v3 - secrets: - token: ${{ secrets.token }} - with: - branchname: ${{ github.event.pull_request.base.ref }} - release_version: ${{ needs.call-create-github-release-workflow.outputs.release_version }} + needs: [ call-assign-from-json-workflow, call-create-github-release-workflow ] + if: needs.call-create-github-release-workflow.outputs.IS_FULL_RELEASE == 'True' + uses: Keyfactor/actions/.github/workflows/kf-post-release.yml@v4 + secrets: + token: ${{ secrets.token }} + with: + branchname: ${{ github.event.pull_request.base.ref }} + release_version: ${{ needs.call-create-github-release-workflow.outputs.release_version }} \ No newline at end of file diff --git a/README.md b/README.md index 6e68518..df8f2ae 100644 --- a/README.md +++ b/README.md @@ -1,40 +1,144 @@ -### 👨🏿‍🚀 Actions v3 Workflows +### 👨🏿‍🚀 Actions v4 Workflows -### What's new in v3 -* The v3 Actions make use of [doctool](https://github.com/Keyfactor/doctool) -* Polaris SAST/SCA scans run on push to release and main branches -* All actions are being migrated to forks in the keyfactor org for security hardening purposes. AB#55122 - * Access to 3rd party actions will be restrcited in the keyfactor org - * The keyfactor-action-staging organization can be used for developing workflows that will need to be transferred to the keyfactor org before making it public -* Post-release workflow added: Auto-create PR from release branch to main - * Additional jobs/actions may be added to the kf-post-release.yml workflow in this repository (.github/workflows folder) +### What's new in v4 +* The v4 Actions make use of [doctool](https://github.com/Keyfactor/doctool) to take Command screenshots for Universal Orchestrator extension store-type creation. -These workflows are designed to work with the latest [keyfactor-bootstrap-workflow.yml "Keyfactor Bootstrap v3 Workflow"](https://github.com/Keyfactor/.github/blob/main/workflow-templates/keyfactor-bootstrap-workflow-v3.yml) +### Usage -### 🚀The Bootstrap workflow for v3 Actions perform the following steps: +#### Prerequisites +- Ensure an `integration-manifest.json` file is present in the root of your repository. For the schema, see the v2 [integration-manifest-schema.json](https://keyfactor.github.io/v2/integration-manifest-schema.json) + +#### Example `integration-manifest.json` +```json +{ + "$schema": "https://keyfactor.github.io/v2/integration-manifest-schema.json", + "integration_type": "anyca-plugin", + "name": "Example AnyCA REST Gateway Plugin", + "status": "pilot", + "support_level": "kf-supported", + "link_github": true, + "update_catalog": true, + "description": "Example Plugin for the AnyCA REST Gateway framework", + "gateway_framework": "25.0.0", + "release_dir": "example-caplugin\\bin\\Release", + "release_project": "example-caplugin\\example_extension.csproj", + "about": { + "carest": { + "ca_plugin_config": [ + { + "name": "ApiKey", + "description": "The API Key for the The CA API" + }, + { + "name": "Username", + "description": "Username for the CA API service account" + }, + { + "name": "Password", + "description": "Password for the CA API service account" + }, + { + "name": "BaseUrl", + "description": "The Base URL for the CA API" + }, + { + "name": "Enabled", + "description": "Flag to Enable or Disable gateway functionality. Disabling is primarily used to allow creation of the CA prior to configuration information being available." + } + ], + "enrollment_config": [ + { + "name": "CertificateValidityInYears", + "description": "Number of years the certificate will be valid for" + }, + { + "name": "Email", + "description": "Email address of the requestor" + }, + { + "name": "OrganizationName", + "description": "Name of the organization to be validated against" + } + ], + "product_ids": [ + "ExampleProductSslOvBasic", + "ExampleProductSslEvBasic", + "ExampleProductSslDvGeotrust", + "ExampleProductSslDvThawte", + "ExampleProductSslOvThawteWebserver", + "ExampleProductSslEvThawteWebserver", + "ExampleProductSslOvGeotrustTruebizid", + "ExampleProductSslEvGeotrustTruebizid", + "ExampleProductSslOvSecuresite", + "ExampleProductSslEvSecuresite", + "ExampleProductSslOvSecuresitePro", + "ExampleProductSslEvSecuresitePro" + ] + } + } +} +``` + +#### Example workflow `keyfactor-bootsrap-workflow.yml` +```yaml +name: Keyfactor Bootstrap Workflow + +on: + workflow_dispatch: + pull_request: + types: [opened, closed, synchronize, edited, reopened] + push: + create: + branches: + - 'release-*.*' + +jobs: + call-starter-workflow: + uses: keyfactor/actions/.github/workflows/starter.yml@v4 + with: + command_token_url: ${{ vars.COMMAND_TOKEN_URL }} # Only required for doctool generated screenshots + command_hostname: ${{ vars.COMMAND_HOSTNAME }} # Only required for doctool generated screenshots + command_base_api_path: ${{ vars.COMMAND_API_PATH }} # Only required for doctool generated screenshots + secrets: + token: ${{ secrets.V2BUILDTOKEN}} # REQUIRED + gpg_key: ${{ secrets.KF_GPG_PRIVATE_KEY }} # Only required for golang builds + gpg_pass: ${{ secrets.KF_GPG_PASSPHRASE }} # Only required for golang builds + scan_token: ${{ secrets.SAST_TOKEN }} # REQUIRED + entra_username: ${{ secrets.DOCTOOL_ENTRA_USERNAME }} # Only required for doctool generated screenshots + entra_password: ${{ secrets.DOCTOOL_ENTRA_PASSWD }} # Only required for doctool generated screenshots + command_client_id: ${{ secrets.COMMAND_CLIENT_ID }} # Only required for doctool generated screenshots + command_client_secret: ${{ secrets.COMMAND_CLIENT_SECRET }} # Only required for doctool generated screenshots +``` + +### 🚀The Bootstrap workflow for v4 Actions perform the following steps: * Checkout integration repository -* Get values from integration-manifest.json [***assign-env-from-json***] +* Call [starter.yml](.github/workflows/starter.yml) workflow +* Get values from integration-manifest.json [assign-env-from-json](.github/workflows/assign-env-from-json.yml) * Discover primary programming language from the repository [***action-get-primary-language***] -* Determine event_name: create, push, pull_request, workflow_dispatch [***github-release]*** -* Run the workflows and conditionalized steps to produce a build. If conditions match, release artifacts are delivered [***dotnet-build-and-release | go-build-and-release***] +* Determine event_name: `create, push, pull_request, workflow_dispatch` [github-release.yml](.github/workflows/github-release.yml) +* Run the workflows and conditionalized steps to produce a build. If conditions match, release artifacts are delivered +[dotnet-build-and-release.yml](.github/workflows/dotnet-build-and-release.yml) or [go-build-and-release.yml](.github/workflows/go-build-and-release.yml) +workflow will be run depending on the `detected-primary-language` step in [starter.yml](.github/workflows/starter.yml) #### On Create: * Configure repository settings - This will use the properties from the json to update topic and description, and will set the teams permissions on the repo accordingly. If the ref created is a branch that matches "release-\*.\*", branch protection is added, autlink reference set ab# to devops [***kf-configure-repo***] #### On push or workflow_dispatch: * Just run the build on the branch with the commit without producing release artifacts -* * C#: run the dotnet-build-and-release.yml workflow +* * C#: run the [dotnet-build-and-release.yml](.github/workflows/dotnet-build-and-release.yml) workflow * * Go builds: run the go-build-and-release.yml workflow (still in progress) -* All languages: Generate a readme using doctool and (conditionally) a catalog entry [***generate-readme, update-catalog***] +* All languages: +* * Generate/Update `README.md` using `doctool` [generate-readme.yml](.github/workflows/generate-readme.yml) +* * (conditionally) a catalog entry [update-catalog](.github/workflows/update-catalog.yml) will be created/updated if the json manifest has `"update_catalog": true` in the `integration-manifest.json` file #### On pull_request[opened, closed, synchronize, edited, reopened]: -[***dotnet-build-and-release | go-build-and-release***] -* If the pr destination is a release-*.* branch, set flags to produce release artifacts -* If the pr is determined to be open or merged but not closed (synchronize), a prerelease artifact will be uploaded -* If the pr is determined to be merged and closed, a final release is built -* Polaris SAST/SCAN scans run when push to release-* or main occurs -* If PR to release branch is merged/closed, a new PR will be automatically generated. This will need to be approved manually and **should not** be approved for hotfix branches +[dotnet-build-and-release.yml](.github/workflows/dotnet-build-and-release.yml) workflow or [go-build-and-release.yml](.github/workflows/go-build-and-release.yml) workflow will be run depending on the detected primary language +* If the pr destination is a `release-*.*` branch, set flags to produce release artifacts +* If the pr is determined to be `open` or `merged` but not `closed` (synchronize), a prerelease artifact will be uploaded +* If the pr is determined to be `merged` and `closed`, a final "official" release is built and published to GitHub releases, and if `"update_catalog": true` is set in the json manifest, a catalog entry will be created/updated +* Polaris SAST/SCAN scans run when push to `release-*` or main occurs +* If PR to release branch is `merged/closed`, a new PR will be automatically generated. This will need to be approved manually and **should not** be approved for hotfix branches diff --git a/readme-templates/readme.md.tpl b/readme-templates/readme.md.tpl deleted file mode 100644 index 9f25dc3..0000000 --- a/readme-templates/readme.md.tpl +++ /dev/null @@ -1,40 +0,0 @@ -{# Boilerplate section #} -# {{ name }} - -{{ description }} - -#### Integration status: {{ shared.integration_status[status] }} - -## About the Keyfactor {{ shared.display_names[integration_type] }} - -{{ shared.descriptions[integration_type] }} - -## Support for {{ name }} - -{{ name }} {{ shared.support_statement[support_level] }} - -###### 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. -{# End of Boilerplate section #} ---- -{# Important information can go in the readme-pre.md to appear near the top of the document #} -{% include "./readme-src/readme-pre.md" ignore missing %} ---- -{# Additional {{ integration_type }} platform template includes will go in this next section #} -{% if ((integration_type == "ca-gateway") or (integration_type == "anyca-gateway") or (integration_type == "orchestrator") or (integration_type == "pam") or (integration_type == "terraform-provider")) %} -{% if (integration_type == "orchestrator") %} -{% include "./actions/readme-templates/readme_platform_orchestrator.md" %} -{% endif %} -{% if (integration_type == "pam") and (about is defined) %} -{% include "./actions/readme-templates/readme_platform_pam.md" %} -{% endif %} -{% if ((integration_type == "ca-gateway") or (integration_type == "anyca-gateway")) %} -{% include "./actions/readme-templates/readme_platform_cagateway.md" %} -{% endif %} ---- -{% endif %} -{# the readme_source.md file should be the general README content in markdown form #} -{% include "readme_source.md" %} -{% if (integration_type == "orchestrator") %} -When creating cert store type manually, that store property names and entry parameter names are case sensitive -{% endif %} - diff --git a/readme-templates/readme_platform_cagateway.md b/readme-templates/readme_platform_cagateway.md deleted file mode 100644 index c20c1dc..0000000 --- a/readme-templates/readme_platform_cagateway.md +++ /dev/null @@ -1,15 +0,0 @@ -## Keyfactor AnyCA Gateway Framework Supported -The Keyfactor gateway framework implements common logic shared across various gateway implementations and handles communication with Keyfactor Command. The gateway framework hosts gateway implementations or plugins that understand how to communicate with specific CAs. This allows you to integrate your third-party CAs with Keyfactor Command such that they behave in a manner similar to the CAs natively supported by Keyfactor Command. - - - - -This gateway extension was compiled against version {{ gateway_framework }} of the AnyCA Gateway -{%- if (integration_type == "ca-gateway") %} DCOM{% endif %} -{%- if (integration_type == "anyca-plugin") %} REST{% endif %} Framework. You will need at least this version of the framework Installed. -{%- if (integration_type == "ca-gateway") %} If you have a later AnyGateway Framework Installed you will probably need to add binding redirects in the CAProxyServer.exe.config file to make things work properly.{% endif %} - - -[Keyfactor CAGateway Install Guide](https://software.keyfactor.com/Guides/AnyGateway_Generic/Content/AnyGateway/Introduction.htm) - - diff --git a/readme-templates/readme_platform_orchestrator.md b/readme-templates/readme_platform_orchestrator.md deleted file mode 100644 index bca6129..0000000 --- a/readme-templates/readme_platform_orchestrator.md +++ /dev/null @@ -1,62 +0,0 @@ -## Keyfactor Version Supported - -The minimum version of the Keyfactor Universal Orchestrator Framework needed to run this version of the extension is {{ about.orchestrator.UOFramework }} -## 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|{% if about.orchestrator.win.supportsManagementAdd %}✓{% else %} {% endif %} |{% if about.orchestrator.linux.supportsManagementAdd %}✓{% else %} {% endif %} | -|Supports Management Remove|{% if about.orchestrator.win.supportsManagementRemove %}✓{% else %} {% endif %} |{% if about.orchestrator.linux.supportsManagementRemove %}✓{% else %} {% endif %} | -|Supports Create Store|{% if about.orchestrator.win.supportsCreateStore %}✓{% else %} {% endif %} |{% if about.orchestrator.linux.supportsCreateStore %}✓{% else %} {% endif %} | -|Supports Discovery|{% if about.orchestrator.win.supportsDiscovery %}✓{% else %} {% endif %} |{% if about.orchestrator.linux.supportsDiscovery %}✓{% else %} {% endif %} | -|Supports Reenrollment|{% if about.orchestrator.win.supportsReenrollment %}✓{% else %} {% endif %} |{% if about.orchestrator.linux.supportsReenrollment %}✓{% else %} {% endif %} | -|Supports Inventory|{% if about.orchestrator.win.supportsInventory %}✓{% else %} {% endif %} |{% if about.orchestrator.linux.supportsInventory %}✓{% else %} {% endif %} | - -{% if about.orchestrator.pam_support %} -## 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: - -{% include "./readme-src/readme-pam-support.md" %} - -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. - -
General PAM Provider Configuration -

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

-
-{% endif %} diff --git a/readme-templates/readme_platform_pam.md b/readme-templates/readme_platform_pam.md deleted file mode 100644 index cc4a44f..0000000 --- a/readme-templates/readme_platform_pam.md +++ /dev/null @@ -1,51 +0,0 @@ -### Initial Configuration of PAM Provider -In order to allow Keyfactor to use the new {{ name }}, the definition needs to be added to the application database. -This is done by running the provided `kfutil` tool to install the PAM definition, which only needs to be done one time. It uses API credentials to access the Keyfactor instance and create the PAM definition. - -The `kfutil` tool, after being [configured for API access](https://github.com/Keyfactor/kfutil#quickstart), can be run in the following manner to install the PAM definition from the Keyfactor repository: - -``` -kfutil pam types-create -r {{ about.pam.assemblyName }} -n {{ about.pam.dbName }} -``` - -### Configuring Parameters -The following are the parameter names and a description of the values needed to configure the {{ name }}. - -{% include "./readme-src/readme-paramtable.md" %} - -![](images/config.png) - -{% include "./readme-src/readme-config.md" %} - -#### In Keyfactor - PAM Provider -##### Installation -In order to setup a new PAM Provider in the Keyfactor Platform for the first time, you will need to run the `kfutil` tool (see Initial Configuration of PAM Provider). - -After the installation is run, the DLLs need to be installed to the correct location for the PAM Provider to function. From the release, the {{ about.pam.assemblyName }}.dll should be copied to the following folder locations in the Keyfactor installation. Once the DLL has been copied to these folders, edit the corresponding config file. You will need to add a new Unity entry as follows under ``, next to other `` tags. - -| Install Location | DLL Binary Folder | Config File | -| --- | --- | --- | -| WebAgentServices | WebAgentServices\bin\ | WebAgentServices\web.config | -| Service | Service\ | Service\CMSTimerService.exe.config | -| KeyfactorAPI | KeyfactorAPI\bin\ | KeyfactorAPI\web.config | -| WebConsole | WebConsole\bin\ | WebConsole\web.config | - -When enabling a PAM provider for Orchestrators only, the first line for `WebAgentServices` is the only installation needed. - -The Keyfactor service and IIS Server should be restarted after making these changes. - -```xml - -``` - - -{% include "./readme-src/readme-register.md" %} - -##### Usage -In order to use the PAM Provider, the provider's configuration must be set in the Keyfactor Platform. In the settings menu (upper right cog) you can select the ___Priviledged Access Management___ option to configure your provider instance. - -![](images/setting.png) - -After it is set up, you can now use your PAM Provider when configuring certificate stores. Any field that is treated as a Keyfactor secret, such as server passwords and certificate store passwords can be retrieved from your PAM Provider instead of being entered in directly as a secret. - -![](images/password.png) diff --git a/readme-templates/readme_shared_data.json b/readme-templates/readme_shared_data.json deleted file mode 100644 index 22e7399..0000000 --- a/readme-templates/readme_shared_data.json +++ /dev/null @@ -1,36 +0,0 @@ -{ - "shared": { - "display_names": { - "orchestrator": "Universal Orchestrator Extension", - "pam": "PAM Provider", - "windows-orchestrator": "Windows Orchestrator AnyAgent", - "ca-gateway": "AnyCA Gateway DCOM Connector", - "anyca-gateway": "AnyCA Gateway REST Connector", - "terraform-provider": "Terraform Provider", - "terraform-module": "Terraform Module", - "api-client": "API Client", - "integ-template": "Integration Template" - }, - "descriptions": { - "api-client": "This API client allows for programmatic management of Keyfactor resources.", - "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.\n\nThe 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.\n\nThe 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.", - "pam": "Keyfactor supports the retrieval of credentials from 3rd party Privileged Access Management (PAM) solutions. Secret values can normally be stored, encrypted at rest, in the Keyfactor Platform database. A PAM Provider can allow these secrets to be stored, managed, and rotated in an external platform. This integration is usually configured on the Keyfactor Platform itself, where the platform can request the credential values when needed. In certain scenarios, a PAM Provider can instead be run on a remote location in conjunction with a Keyfactor Orchestrator to allow credential requests to originate from a location other than the Keyfactor Platform.", - "windows-orchestrator": "This repository contains a Windows Orchestrator AnyAgent, which is a plugin to the Keyfactor Windows 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.\n\nThe Windows Orchestrator is part of the Keyfactor software distribution and is available via the Keyfactor customer portal. For general instructions on installing AnyAgents, see the “Keyfactor Command Orchestrator Installation and Configuration Guide” section of the Keyfactor documentation. For configuration details of this specific AnyAgent, see below in this readme.\n\nNote that in Keyfactor Version 9, the Windows Orchestrator have been replaced by the Universal Orchestrator. While this AnyAgent continues to work with the Windows Orchestrator, and the Windows Orchestrator is supported alongside the Universal Orchestrator talking to Keyfactor version 9, AnyAgent plugins cannot be used with the Universal Orchestrator.", - "ca-gateway": "This repository contains an AnyCA Gateway Connector, which is a plugin to the Keyfactor AnyGateway. AnyCA Gateway Connectors allow Keyfactor Command to be used for inventory, issuance, and revocation of certificates from a third-party certificate authority.", - "anyca-gateway": "This repository contains an AnyCA Gateway Connector, which is a plugin to the Keyfactor AnyGateway. AnyCA Gateway Connectors allow Keyfactor Command to be used for inventory, issuance, and revocation of certificates from a third-party certificate authority.", - "terraform-provider": "The Terraform provider enables management of Keyfactor resources utilizing HashiCorp Terraform.", - "terraform-module": "This repository contains a Terraform module intended to be used with the Keyfactor Terraform provider.", - "integ-template": "This repository can be used to generate a boilerplate integration project for PAM and Orchestrator types" - }, - "integration_status": { - "prototype": "Prototype - Demonstration quality. Not for use in customer environments.", - "pilot": "Pilot - Ready for use in test environments. Not for use in production.", - "production": "Production - Ready for use in production environments." - }, - "support_statement": { - "community": "is open source and community supported, meaning that there is no support guaranteed from Keyfactor Support for these tools.", - "kf-community": "is open source and supported on best effort level for this tool/library/client. This means customers can report Bugs, Feature Requests, Documentation amendment or questions as well as requests for customer information required for setup that needs Keyfactor access to obtain. Such requests do not follow normal SLA commitments for response or resolution. If you have a support issue, please open a support ticket via the Keyfactor Support Portal at https://support.keyfactor.com/", - "kf-supported": "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" - } - } -}