S163 docs review

infra/examples-dev/gcp/google-workspace.tf

@@ -19,6 +19,8 @@ module "worklytics_connectors_google_workspace" {
   gcp_project_id                 = var.google_workspace_gcp_project_id
   google_workspace_example_user  = var.google_workspace_example_user
   google_workspace_example_admin = var.google_workspace_example_admin
+  config_parameter_prefix = module.psoxy.config_parameter_prefix
+
 }
 
 output "google_workspace_api_clients" {

infra/examples-dev/gcp/main.tf

@@ -31,6 +31,7 @@ module "worklytics_connectors" {
 
 
   enabled_connectors            = var.enabled_connectors
+  config_parameter_prefix       = module.psoxy.config_parameter_prefix
   jira_cloud_id                 = var.jira_cloud_id
   jira_server_url               = var.jira_server_url
   jira_example_issue_id         = var.jira_example_issue_id
@@ -81,7 +82,6 @@ module "psoxy" {
 
   gcp_project_id                    = var.gcp_project_id
   environment_name                  = var.environment_name
-  config_parameter_prefix           = var.config_parameter_prefix
   default_labels                    = var.default_labels
   worklytics_sa_emails              = var.worklytics_sa_emails
   psoxy_base_dir                    = var.psoxy_base_dir
@@ -168,4 +168,4 @@ output "todos_3" {
 #  description = "Value used to salt pseudonyms (SHA-256) hashes. If migrate to new deployment, you should copy this value."
 #  value       = module.psoxy.pseudonym_salt
 #  sensitive   = true
-#}
+#}

infra/examples-dev/gcp/msft-365.tf

@@ -4,7 +4,6 @@ module "worklytics_connectors_msft_365" {
   source = "../../modules/worklytics-connectors-msft-365"
   # source = "git::https://github.com/worklytics/psoxy//infra/modules/worklytics-connectors-msft-365?ref=rc-v0.4.43"
 
-
   enabled_connectors                  = var.enabled_connectors
   environment_id                      = var.environment_name
   msft_tenant_id                      = var.msft_tenant_id
@@ -15,6 +14,7 @@ module "worklytics_connectors_msft_365" {
   msft_teams_example_chat_guid        = var.msft_teams_example_chat_guid
   msft_teams_example_call_guid        = var.msft_teams_example_call_guid
   msft_teams_example_call_record_guid = var.msft_teams_example_call_record_guid
+  config_parameter_prefix = module.psoxy.config_parameter_prefix
   todo_step                           = 1
 }
 
@@ -61,4 +61,4 @@ locals {
 output "msft_365_api_clients" {
   description = "Map of API client identifiers. Useful for configuration of clients, terraform migration."
   value       = module.worklytics_connectors_msft_365.api_clients
-}
+}

infra/modules/gcp-host/output.tf

@@ -12,6 +12,10 @@ output "bulk_connector_instances" {
   value = local.bulk_instances
 }
 
+output "config_parameter_prefix" {
+  value = local.default_config_parameter_prefix
+}
+
 output "pseudonym_salt" {
   description = "Value used to salt pseudonyms (SHA-256) hashes. If migrate to new deployment, you should copy this value."
   value       = module.psoxy.pseudonym_salt

infra/modules/worklytics-connector-specs/main.tf

@@ -423,51 +423,52 @@ EOT
         "/repos/${local.github_organization}/${local.github_example_repository}/pulls",
       ]
       external_token_todo : <<EOT
-  1. From your organization, register a [GitHub App](https://docs.github.com/en/apps/creating-github-apps/registering-a-github-app/registering-a-github-app#registering-a-github-app)
-    with following permissions with **Read Only**:
-    - Repository:
+  1. Register a [GitHub App](https://docs.github.com/en/apps/creating-github-apps/registering-a-github-app/registering-a-github-app#registering-a-github-app)
+    from your organization with the  **Read-only** access level set to the following permissions:
+    - Repository permissions
       - Contents: for reading commits and comments
       - Issues: for listing issues, comments, assignees, etc.
       - Metadata: for listing repositories and branches
       - Pull requests: for listing pull requests, reviews, comments and commits
-    - Organization
+    - Organization permissions
       - Administration: for listing events from audit log
       - Members: for listing teams and their members
 
   NOTES:
-    - We assume that ALL the repositories are going to be listed **should be owned by the organization, not the users**.
+    - We assume that ALL the repositories to be listed **should be owned by the organization, not the users**.
     - Enterprise Cloud is required for this connector.
 
-  Apart from Github instructions please review the following:
-  - "Homepage URL" can be anything, not required in this flow but required by Github.
+  Apart from GitHub instructions please review the following:
+  - "Homepage URL" can be anything, not required in this flow but required by GitHub.
   - Webhooks check can be disabled as this connector is not using them
   - Keep `Expire user authorization tokens` enabled, as GitHub documentation recommends
-  2. Once is created please generate a new `Private Key`.
-  3. It is required to convert the format of the certificate downloaded from PKCS#1 in previous step to PKCS#8. Please run following command:
+  2. Once the App is created, please generate a new `Private Key`.
+  3. It is required to convert the format of the certificate generated in the previous step from PKCS#1 to PKCS#8. Please, run following command:
 ```shell
 openssl pkcs8 -topk8 -inform PEM -outform PEM -in {YOUR DOWNLOADED CERTIFICATE FILE} -out gh_pk_pkcs8.pem -nocrypt
 ```
 
 **NOTES**:
- - If the certificate is not converted to PKCS#8 connector will NOT work. You might see in logs a Java error `Invalid PKCS8 data.` if the format is not correct.
+ - If the certificate is not converted to PKCS#8, the connector will NOT work. You might see in the logs a Java error `Invalid PKCS8 data.` if the format is not correct.
  - Command proposed has been successfully tested on Ubuntu; it may differ for other operating systems.
 
   4. Install the application in your organization.
-     Go to your organization settings and then in "Developer Settings". Then, click on "Edit" for your "Github App" and once you are in the app settings, click on "Install App" and click on the "Install" button. Accept the permissions to install it in your whole organization.
-  5. Once installed, the `installationId` is required as it needs to be provided in the proxy as parameter for the connector in your Terraform module. You can go to your organization settings and
-click on `Third Party Access`. Click on `Configure` the application you have installed in previous step and you will find the `installationId` at the URL of the browser:
+     Go to the "Developer Settings" section of your organization. Then, click on "Edit" for your "Github App" and once you are in the app settings, click on "Install App" and click on the "Install" button. Accept the permissions to install it to your whole organization.
+  5. Once installed, the `installationId` is required as it needs to be provided in the Psoxy as parameter for the connector in your Terraform module. You can go to your organization settings and
+click on `Third Party Access`. Click on `Configure` the application you have installed in the previous step and you will find the `installationId` at the URL of the browser:
 ```
 https://github.com/organizations/{YOUR ORG}/settings/installations/{INSTALLATION_ID}
 ```
-  Copy the value of `installationId` and assign it to the `github_installation_id` variable in Terraform. You will need to redeploy the proxy again if that value was not populated before.
+  Copy the value of `installationId` and assign it to the `github_installation_id` variable in Terraform. If the variable wasn't defined before, add the following to your `terraform.tfvars` file
+  `github_installation_id="{installationId}"` replacing "installationId" by the the actual value. You will need to redeploy the Psoxy again for the changes to take effect.
 
 **NOTE**:
  - If `github_installation_id` is not set, authentication URL will not be properly formatted and you will see *401: Unauthorized* when trying to get an access token.
- - If you see *404: Not found* in logs please review the *IP restriction policies* that your organization might have; that could cause connections from psoxy AWS Lambda/GCP Cloud Functions be rejected.
+ - If you see *404: Not found* in logs please review the *IP restriction policies* that your organization might have; that could cause connections from the Psoxy AWS Lambda/GCP Cloud Functions be rejected.
 
   6. Update the variables with values obtained in previous step:
-     - `PSOXY_GITHUB_CLIENT_ID` with `App ID` value. **NOTE**: It should be `App Id` value as we are going to use authentication through the App and **not** *client_id*.
-     - `PSOXY_GITHUB_PRIVATE_KEY` with content of the `gh_pk_pkcs8.pem` from previous step. You could open the certificate with VS Code or any other editor and copy all the content *as-is* into this variable.
+     - `${var.config_parameter_prefix}GITHUB_CLIENT_ID` with `App ID` value. **NOTE**: It should be `App Id` value as we are going to use authentication through the App and **not** *client_id*.
+     - `${var.config_parameter_prefix}GITHUB_PRIVATE_KEY` with content of the `gh_pk_pkcs8.pem` from previous step. You could open the certificate with VS Code or any other editor and copy all the content *as-is* into this variable.
   7. Once the certificate has been uploaded, please remove {YOUR DOWNLOADED CERTIFICATE FILE} and `gh_pk_pkcs8.pem` from your computer or store it in a safe place.
 
 EOT
@@ -1237,4 +1238,4 @@ locals {
       } if try(secret_var.lockable, false) == true
     ]
   ]))
-}
+}

infra/modules/worklytics-connector-specs/variables.tf

@@ -3,6 +3,11 @@ variable "enabled_connectors" {
   description = "ids of connectors to enable"
 }
 
+variable "config_parameter_prefix" {
+  type        = string
+  description = "prefix used for configuration parameter names (such as secrets)"
+}
+
 variable "google_workspace_example_user" {
   type        = string
   description = "user to impersonate for Google Workspace API calls (null for none)"
@@ -116,4 +121,4 @@ variable "salesforce_example_account_id" {
   type        = string
   default     = null
   description = "(Only required if using Salesforce connector) Id of the account id for usign as an example calls for Salesforce (ex: 0015Y00002c7g95QAA)"
-}
+}

infra/modules/worklytics-connectors-google-workspace/main.tf

@@ -18,6 +18,7 @@ module "worklytics_connector_specs" {
   enabled_connectors             = var.enabled_connectors
   google_workspace_example_admin = var.google_workspace_example_admin
   google_workspace_example_user  = var.google_workspace_example_user
+  config_parameter_prefix = var.config_parameter_prefix
 }
 
 module "google_workspace_connection" {

infra/modules/worklytics-connectors-google-workspace/variables.tf

@@ -14,6 +14,11 @@ variable "enabled_connectors" {
   description = "ids of connectors to enable"
 }
 
+variable "config_parameter_prefix" {
+  type        = string
+  description = "prefix used for configuration parameter names (such as secrets)"
+}
+
 variable "gcp_project_id" {
   type        = string
   description = "id of GCP project that will host OAuth Clients for Google Workspace API connectors"

infra/modules/worklytics-connectors-msft-365/main.tf

@@ -9,6 +9,7 @@ module "worklytics_connector_specs" {
 
   enabled_connectors                  = var.enabled_connectors
   msft_tenant_id                      = var.msft_tenant_id
+  config_parameter_prefix             = var.config_parameter_prefix
   example_msft_user_guid              = var.example_msft_user_guid
   msft_teams_example_team_guid        = var.msft_teams_example_team_guid
   msft_teams_example_channel_guid     = var.msft_teams_example_channel_guid
@@ -65,4 +66,4 @@ locals {
       })
     })
   }
-}
+}

infra/modules/worklytics-connectors-msft-365/variables.tf

@@ -3,6 +3,11 @@ variable "enabled_connectors" {
   description = "ids of connectors to enable"
 }
 
+variable "config_parameter_prefix" {
+  type        = string
+  description = "prefix used for configuration parameter names (such as secrets)"
+}
+
 variable "environment_id" {
   type        = string
   description = "Qualifier to append to names/ids of resources. If not empty, A-Za-z0-9 or - characters only. Max length 10. Useful to distinguish between deployments into same GCP project."

infra/modules/worklytics-connectors/main.tf

@@ -3,6 +3,7 @@ module "worklytics_connector_specs" {
   source = "../../modules/worklytics-connector-specs"
 
   enabled_connectors            = var.enabled_connectors
+  config_parameter_prefix       = var.config_parameter_prefix
   jira_cloud_id                 = var.jira_cloud_id
   jira_server_url               = var.jira_server_url
   salesforce_domain             = var.salesforce_domain
@@ -29,4 +30,4 @@ module "source_token_external_todo" {
 locals {
   enabled_api_connectors  = module.worklytics_connector_specs.enabled_oauth_long_access_connectors
   enabled_bulk_connectors = module.worklytics_connector_specs.enabled_bulk_connectors
-}
+}

infra/modules/worklytics-connectors/variables.tf

@@ -3,6 +3,11 @@ variable "enabled_connectors" {
   description = "ids of connectors to enable"
 }
 
+variable "config_parameter_prefix" {
+  type        = string
+  description = "prefix used for configuration parameter names (such as secrets)"
+}
+
 variable "salesforce_domain" {
   type        = string
   description = "Domain of the Salesforce to connect to (only required if using Salesforce connector). To find your My Domain URL, from Setup, in the Quick Find box, enter My Domain, and then select My Domain"
@@ -68,4 +73,4 @@ variable "todo_step" {
   type        = number
   description = "of all todos, where does this one logically fall in sequence"
   default     = 1
-}
+}