diff --git a/README.md b/README.md index 6df5ad7e..e30732a2 100644 --- a/README.md +++ b/README.md @@ -24,29 +24,10 @@ Profile created. Update additional profile attributes via 'pingcli config set' o Profile 'dev' set as active. - Success ``` -Run `pingcli config view-profile` to generate a set of empty configuration. +The newly create profile can now be configured via the `pingcli config set` command. General Ping Identity service connection settings are found under the `service` key, and settings relevant to individual commands are found under their command names e.g. `export` and `request`. -```text -$ pingcli config view-profile -Profile: dev - -color: true -description: configuration for development environment -export: - format: HCL - outputdirectory: /Users/samirgandhi/projects/terraform/UAT/pingcli-uat/export - overwrite: false - pingone: - environmentid: "" -# additional configuration trimmed -``` - -The available settings can be configured by editing the empty fields within the generated `~/.pingcli/config.yaml`. General Ping Identity service connection settings are found under the `service` key, and settings relevant to individual commands are found under their command names e.g. `export` and `request`. - -To see descriptions for the settings the `export` command's help option. -``` -pingcli platform export --help -``` +See [Configuration Key Documentation](./docs/tool-configuration/configuration-key.md) for more information on configuration keys +and their purposes. ## Commands diff --git a/docs/tool-configuration/configuration-key.md b/docs/tool-configuration/configuration-key.md new file mode 100644 index 00000000..9431a594 --- /dev/null +++ b/docs/tool-configuration/configuration-key.md @@ -0,0 +1,51 @@ +## Configuration File + +The following parameters can be configured in Ping CLI's static configuration file, usually located at $HOME/.pingcli/config.yaml. The following describes the properties that can be set, and an example can be found at [example-configuration.md](./example-configuration.md) + + +#### General Properties + +| Config File Property | Type | Equivalent Parameter | Purpose | +|---|---|---|---| +| activeProfile | ENUM_STRING | --active-profile / -P | The name of the stored custom configuration profile to use. | +| color | ENUM_BOOL | --color | Show text output in color. | +| outputFormat | ENUM_OUTPUT_FORMAT | --output-format / -O | Specify the console output format.

Options are: json, text.

Example: `json` | + +#### Ping Platform Service Properties + +| Config File Property | Type | Equivalent Parameter | Purpose | +|---|---|---|---| +| service.pingfederate.adminAPIPath | ENUM_STRING | --pingfederate-admin-api-path | The PingFederate API URL path used to communicate with PingFederate's admin API.

Example: `/pf-admin-api/v1` | +| service.pingfederate.authentication.accessTokenAuth.accessToken | ENUM_STRING | --pingfederate-access-token | The PingFederate access token used to authenticate to the PingFederate admin API when using a custom OAuth 2.0 token method. | +| service.pingfederate.authentication.basicAuth.password | ENUM_STRING | --pingfederate-password | The PingFederate password used to authenticate to the PingFederate admin API when using basic authentication. | +| service.pingfederate.authentication.basicAuth.username | ENUM_STRING | --pingfederate-username | The PingFederate username used to authenticate to the PingFederate admin API when using basic authentication. Example: `administrator` | +| service.pingfederate.authentication.clientCredentialsAuth.clientID | ENUM_STRING | --pingfederate-client-id | The PingFederate OAuth client ID used to authenticate to the PingFederate admin API when using the OAuth 2.0 client credentials grant type. | +| service.pingfederate.authentication.clientCredentialsAuth.clientSecret | ENUM_STRING | --pingfederate-client-secret | The PingFederate OAuth client secret used to authenticate to the PingFederate admin API when using the OAuth 2.0 client credentials grant type. | +| service.pingfederate.authentication.clientCredentialsAuth.scopes | ENUM_STRING_SLICE | --pingfederate-scopes | The PingFederate OAuth scopes used to authenticate to the PingFederate admin API when using the OAuth 2.0 client credentials grant type.

Accepts a comma-separated string to delimit multiple scopes.

Example: `openid,profile` | +| service.pingfederate.authentication.clientCredentialsAuth.tokenURL | ENUM_STRING | --pingfederate-token-url | The PingFederate OAuth token URL used to authenticate to the PingFederate admin API when using the OAuth 2.0 client credentials grant type. | +| service.pingfederate.authentication.type | ENUM_PINGFEDERATE_AUTH_TYPE | --pingfederate-authentication-type | The authentication type to use when connecting to the PingFederate admin API.

Options are: accessTokenAuth, basicAuth, clientCredentialsAuth.

Example: `basicAuth` | +| service.pingfederate.caCertificatePemFiles | ENUM_STRING_SLICE | --pingfederate-ca-certificate-pem-files | Relative or full paths to PEM-encoded certificate files to be trusted as root CAs when connecting to the PingFederate server over HTTPS.

Accepts a comma-separated string to delimit multiple PEM files. | +| service.pingfederate.httpsHost | ENUM_STRING | --pingfederate-https-host | The PingFederate HTTPS host used to communicate with PingFederate's admin API.

Example: `https://pingfederate-admin.bxretail.org` | +| service.pingfederate.insecureTrustAllTLS | ENUM_BOOL | --pingfederate-insecure-trust-all-tls | Trust any certificate when connecting to the PingFederate server admin API.

This is insecure and should not be enabled outside of testing. | +| service.pingfederate.xBypassExternalValidationHeader | ENUM_BOOL | --pingfederate-x-bypass-external-validation-header | Bypass connection tests when configuring PingFederate (the X-BypassExternalValidation header when using PingFederate's admin API). | +| service.pingone.authentication.type | ENUM_PINGONE_AUTH_TYPE | --pingone-authentication-type | The authentication type to use to authenticate to the PingOne management API.

Options are: worker.

Example: `worker` | +| service.pingone.authentication.worker.clientID | ENUM_UUID | --pingone-worker-client-id | The worker client ID used to authenticate to the PingOne management API. | +| service.pingone.authentication.worker.clientSecret | ENUM_STRING | --pingone-worker-client-secret | The worker client secret used to authenticate to the PingOne management API. | +| service.pingone.authentication.worker.environmentID | ENUM_UUID | --pingone-worker-environment-id | The ID of the PingOne environment that contains the worker client used to authenticate to the PingOne management API. | +| service.pingone.regionCode | ENUM_PINGONE_REGION_CODE | --pingone-region-code | The region code of the PingOne tenant.

Options are: AP, AU, CA, EU, NA.

Example: `NA` | + +#### Platform Export Properties + +| Config File Property | Type | Equivalent Parameter | Purpose | +|---|---|---|---| +| export.format | ENUM_STRING | --format / -f | Specifies the export format.

Options are: HCL.

Example: `HCL` | +| export.outputDirectory | ENUM_STRING | --output-directory / -d | Specifies the output directory for export. Example: `$HOME/pingcli-export` | +| export.overwrite | ENUM_BOOL | --overwrite / -o | Overwrite the existing generated exports in output directory. | +| export.pingone.environmentID | ENUM_UUID | --pingone-export-environment-id | The ID of the PingOne environment to export. Must be a valid PingOne UUID. | +| export.services | ENUM_EXPORT_SERVICES | --services / -s | Specifies the service(s) to export. Accepts a comma-separated string to delimit multiple services.

Options are: pingfederate, pingone-mfa, pingone-platform, pingone-protect, pingone-sso.

Example: `pingone-sso,pingone-mfa,pingfederate` | + +#### Custom Request Properties + +| Config File Property | Type | Equivalent Parameter | Purpose | +|---|---|---|---| +| request.service | ENUM_REQUEST_SERVICE | --service / -s | The Ping service (configured in the active profile) to send the custom request to.

Options are: pingone.

Example: `pingone` | \ No newline at end of file diff --git a/docs/tool-configuration/example-configuration.md b/docs/tool-configuration/example-configuration.md new file mode 100644 index 00000000..04a0bf5a --- /dev/null +++ b/docs/tool-configuration/example-configuration.md @@ -0,0 +1,52 @@ +## Example Ping CLI configuration file + +``` +activeprofile: default +default: + color: true + description: Default profile created by pingcli + export: + format: HCL + outputdirectory: /Users/me/pingcli/export + overwrite: false + pingone: + environmentid: 12345678-1234-1234-1234-123456789012 + services: + - pingfederate + - pingone-mfa + - pingone-platform + - pingone-protect + - pingone-sso + outputformat: text + request: + service: pingone + service: + pingfederate: + adminapipath: /pf-admin-api/v1 + authentication: + accesstokenauth: + accesstoken: token + basicauth: + password: password + username: administrator + clientcredentialsauth: + clientid: clientID + clientsecret: secret + scopes: + - openid + - profile + tokenurl: https://pingfederate-admin.bxretail.org/as/token.oauth2 + type: clientcredentialsauth + cacertificatepemfiles: [] + httpshost: https://pingfederate-admin.bxretail.org + insecuretrustalltls: false + xbypassexternalvalidationheader: false + pingone: + authentication: + type: worker + worker: + clientid: 12345678-1234-1234-1234-123456789012 + clientsecret: secret + environmentid: 12345678-1234-1234-1234-123456789012 + regioncode: NA +``` \ No newline at end of file diff --git a/internal/configuration/options/options_test.go b/internal/configuration/options/options_test.go new file mode 100644 index 00000000..1686aa2d --- /dev/null +++ b/internal/configuration/options/options_test.go @@ -0,0 +1,63 @@ +package options_test + +import ( + "fmt" + "slices" + "strings" + "testing" + + "github.com/pingidentity/pingcli/internal/configuration/options" + "github.com/pingidentity/pingcli/internal/testing/testutils_viper" +) + +func Test_outputOptionsMDInfo(t *testing.T) { + + // Skip this test. Use only to generate markdown table for documentation + t.SkipNow() + + testutils_viper.InitVipers(t) + + propertyCategoryInformation := make(map[string][]string) + + for _, option := range options.Options() { + if option.ViperKey == "" || option.Flag == nil { + continue + } + + var flagInfo string + if option.Flag.Shorthand != "" { + flagInfo = fmt.Sprintf("--%s / -%s", option.CobraParamName, option.Flag.Shorthand) + } else { + flagInfo = fmt.Sprintf("--%s", option.CobraParamName) + } + + usageString := option.Flag.Usage + // Replace newlines with '

' + usageString = strings.ReplaceAll(usageString, "\n", "

") + + if !strings.Contains(option.ViperKey, ".") { + propertyCategoryInformation["general"] = append(propertyCategoryInformation["general"], fmt.Sprintf("| %s | %s | %s | %s |", option.ViperKey, option.Type, flagInfo, usageString)) + } else { + rootKey := strings.Split(option.ViperKey, ".")[0] + propertyCategoryInformation[rootKey] = append(propertyCategoryInformation[rootKey], fmt.Sprintf("| %s | %s | %s | %s |", option.ViperKey, option.Type, flagInfo, usageString)) + } + } + + var outputString string + for category, properties := range propertyCategoryInformation { + outputString += fmt.Sprintf("#### %s Properties\n\n", category) + + outputString += "| Config File Property | Type | Equivalent Parameter | Purpose |\n" + outputString += "|---|---|---|---|\n" + + slices.Sort(properties) + + for _, property := range properties { + outputString += property + "\n" + } + + outputString += "\n" + } + + fmt.Println(outputString) +}