Add "Configuring the PingOne Self-Service Application" example

docs/examples/index.md

@@ -7,12 +7,14 @@ The following provides a list of examples of how to use Terraform to integrate P
 ### PingOne
 
 * [PingOne Role Permission Assignment](./pingone/role-assignment)
+* [Configuring the PingOne Self-Service Application](./pingone/configuring-the-pingone-self-service-application)
 
 ## "Ready to run" Github Examples
 
 * [Configuring PingOne for Windows Passwordless Login](https://github.com/pingidentity/terraform-docs/tree/main/examples/pingone-workforce-windows-passwordless-login)
 * [Configuring PingOne Custom Domain with Cloudflare DNS](https://github.com/pingidentity/terraform-docs/tree/main/examples/pingone-custom-domain-with-cloudflare-dns)
 * [Using Postman's "OAuth 2.0" authorization type with PingOne](https://github.com/pingidentity/terraform-docs/tree/main/examples/pingone-postman-oauth2-integration)
+* [Configuring the PingOne Self-Service Application](https://github.com/pingidentity/terraform-docs/tree/main/examples/pingone-configuring-the-self-service-application)
 * [PingOne Neo - Getting Started](https://github.com/pingidentity/terraform-docs/tree/main/examples/pingone-neo-getting-started)
 
 ## Solution Integration Examples

docs/examples/pingone/configuring-the-pingone-self-service-application.md

@@ -0,0 +1,87 @@
+# Configuring the PingOne Self-Service Application
+
+The following shows an example of how to configure the PingOne Self-Service system application.
+
+The PingOne Self-Service application can be configured in the PingOne Admin Console using the [online documentation](https://docs.pingidentity.com/r/en-us/pingone/p1_c_self_service).  It is a web application and as such it's capabilities are configured by assigning resource scopes to the application, rather than through a dedicated API or Terraform resource.
+
+First, we will need to ensure that the Self-Service application itself is configured using the `pingone_system_application`<a href="https://registry.terraform.io/providers/pingidentity/pingone/latest/docs/resources/system_application" target="_blank">:octicons-link-external-16:</a> resource.
+``` terraform
+resource "pingone_system_application" "pingone_self_service" {
+  environment_id = pingone_environment.my_environment.id
+
+  type    = "PING_ONE_SELF_SERVICE"
+  enabled = true
+
+  apply_default_theme         = true
+  enable_default_theme_footer = true
+}
+```
+
+We then select which self service capabilities (the scopes) we want to apply to the self service application.  The simplest way is to create a list, and select the appropriate scope data using the `pingone_resource_scope`<a href="https://registry.terraform.io/providers/pingidentity/pingone/latest/docs/data-sources/resource_scope" target="_blank">:octicons-link-external-16:</a> data source.
+``` terraform
+locals {
+  pingone_api_scopes = [
+    # Manage Profile
+    "p1:read:user",
+    "p1:update:user",
+
+    # Manage Authentication
+    "p1:create:device",
+    "p1:create:pairingKey",
+    "p1:delete:device",
+    "p1:read:device",
+    "p1:read:pairingKey",
+    "p1:update:device",
+
+    # Enable or Disable MFA
+    "p1:update:userMfaEnabled",
+
+    # Change Password
+    "p1:read:userPassword",
+    "p1:reset:userPassword",
+    "p1:validate:userPassword",
+
+    # Manage Linked Accounts
+    "p1:delete:userLinkedAccounts",
+    "p1:read:userLinkedAccounts",
+
+    # Manage Sessions
+    "p1:delete:sessions",
+    "p1:read:sessions",
+
+    # View Agreements
+    "p1:read:userConsent",
+
+    # Manage OAuth Consents
+    "p1:read:oauthConsent",
+    "p1:update:oauthConsent",
+  ]
+}
+
+data "pingone_resource_scope" "pingone_api" {
+  for_each = toset(local.pingone_api_scopes)
+
+  environment_id = pingone_environment.my_environment.id
+  resource_type  = "PINGONE_API"
+
+  name = each.key
+}
+```
+
+We then map the appropriate scopes to enable the specific self-service features we want using the `pingone_application_resource_grant`<a href="https://registry.terraform.io/providers/pingidentity/pingone/latest/docs/resources/application_resource_grant" target="_blank">:octicons-link-external-16:</a> resource.
+``` terraform
+resource "pingone_application_resource_grant" "my_awesome_spa_pingone_api_resource_grants" {
+  environment_id = pingone_environment.my_environment.id
+  application_id = pingone_system_application.pingone_self_service.id
+
+  resource_type = "PINGONE_API"
+
+  scopes = [
+    for scope in data.pingone_resource_scope.pingone_api : scope.id
+  ]
+}
+```
+
+The Self Service application is now configured with the required capabilities.
+
+The full runable example can be found on Github [here](https://github.com/pingidentity/terraform-docs/tree/main/examples/pingone-configuring-the-self-service-application).

examples/README.md

@@ -2,6 +2,7 @@
 
 ## PingOne
 
+* [Configuring the PingOne Self-Service Application](./pingone-configuring-the-self-service-application)
 * [Windows Passwordless Login](./pingone-workforce-windows-passwordless-login)
 * [Custom Domain with Cloudflare DNS](./pingone-custom-domain-with-cloudflare-dns)
 * [PingOne Neo - Getting Started](./pingone-neo-getting-started)

examples/pingone-configuring-the-self-service-application/README.md

@@ -0,0 +1,50 @@
+# Configure the PingOne Self-Service Application
+
+The following example:
+1. Creates a demo PingOne environment named **Terraform Example - Configuring the Self-Service Application**.
+2. Sets branding settings to the PingOne Self-Service application.
+3. Applies resource grants that enable/disable features within the Self-Service application.
+
+## Before you begin
+
+* A PingOne account configured for Terraform access.  For more information, see [Getting Started - PingOne](https://terraform.pingidentity.com/getting-started/pingone/)
+
+## Setting Connection Details
+The following environment variables should be set prior to running the example.  For more information, see the registry documentation for each provider.
+
+| Variable name                                   | Schema Documentation                                                                                                | Required/Optional |
+|-------------------------------------------------|---------------------------------------------------------------------------------------------------------------------|-------------------|
+| `PINGONE_CLIENT_ID`                             | [PingOne - client_id](https://registry.terraform.io/providers/pingidentity/pingone/latest/docs#client_id)           | Required          |
+| `PINGONE_CLIENT_SECRET`                         | [PingOne - client_secret](https://registry.terraform.io/providers/pingidentity/pingone/latest/docs#client_secret)   | Required          |
+| `PINGONE_ENVIRONMENT_ID`                        | [PingOne - environment_id](https://registry.terraform.io/providers/pingidentity/pingone/latest/docs#environment_id) | Required          |
+| `PINGONE_REGION_CODE`                           | [PingOne - region_code](https://registry.terraform.io/providers/pingidentity/pingone/latest/docs#region_code)                 | Required          |
+
+
+## Setting Variables
+The following variables can be set prior to running the example:
+
+| Variable name                        | Required | Data Type | Default Value | Example Value                      | Description                                                                                                                                 |
+|--------------------------------------|----------|-----------|---------------|------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------|
+| `pingone_environment_license_id`     | Yes      | String    | *no default*  |                                    | A valid license UUID to apply to the new environment.                                                                                       |
+| `pingone_environment_name`           | No       | String    | `Terraform Example - Configuring the Self-Service Application`  | `My new environment` | A string that represents the name of the PingOne customer environment to create and manage with Terraform. |
+| `append_date_to_environment_name`    | No       | String    | `true`        | `true`                             | A boolean that determines whether to append the current date to the pingone_environment_name value.                                         |
+
+See [Finding Required IDs](https://terraform.pingidentity.com/getting-started/pingone/#license-id-organization-id-and-organization-name) for instructions on how to retrieve the `pingone_environment_license_id` value from the PingOne console.
+
+## Running the Example
+Use the following to run the example:
+
+```shell
+terraform plan -out infra.tfout
+```
+
+```shell
+terraform apply "infra.tfout"
+```
+
+## Clean up resources
+Use the following to clean up the environment:
+
+```shell
+terraform destroy
+```

examples/pingone-configuring-the-self-service-application/main.tf

@@ -0,0 +1,69 @@
+resource "pingone_system_application" "pingone_self_service" {
+  environment_id = pingone_environment.my_environment.id
+
+  type    = "PING_ONE_SELF_SERVICE"
+  enabled = true
+
+  # Set default theme styling.  Branding can be modified using the `pingone_branding_theme` and `pingone_branding_theme_default` resources.
+  apply_default_theme         = true
+  enable_default_theme_footer = true
+}
+
+locals {
+  pingone_api_scopes = [
+    # Manage Profile
+    "p1:read:user",
+    "p1:update:user",
+
+    # Manage Authentication
+    "p1:create:device",
+    "p1:create:pairingKey",
+    "p1:delete:device",
+    "p1:read:device",
+    "p1:read:pairingKey",
+    "p1:update:device",
+
+    # Enable or Disable MFA
+    "p1:update:userMfaEnabled",
+
+    # Change Password
+    "p1:read:userPassword",
+    "p1:reset:userPassword",
+    "p1:validate:userPassword",
+
+    # Manage Linked Accounts
+    "p1:delete:userLinkedAccounts",
+    "p1:read:userLinkedAccounts",
+
+    # Manage Sessions
+    "p1:delete:sessions",
+    "p1:read:sessions",
+
+    # View Agreements
+    "p1:read:userConsent",
+
+    # Manage OAuth Consents
+    "p1:read:oauthConsent",
+    "p1:update:oauthConsent",
+  ]
+}
+
+data "pingone_resource_scope" "pingone_api" {
+  for_each = toset(local.pingone_api_scopes)
+
+  environment_id = pingone_environment.my_environment.id
+  resource_type  = "PINGONE_API"
+
+  name = each.key
+}
+
+resource "pingone_application_resource_grant" "pingone_self_service_pingone_api_resource_grants" {
+  environment_id = pingone_environment.my_environment.id
+  application_id = pingone_system_application.pingone_self_service.id
+
+  resource_type = "PINGONE_API"
+
+  scopes = [
+    for scope in data.pingone_resource_scope.pingone_api : scope.id
+  ]
+}

examples/pingone-configuring-the-self-service-application/outputs.tf

@@ -0,0 +1,4 @@
+output "pingone_environment_name" {
+  description = "The environment name created by the example"
+  value       = pingone_environment.my_environment.name
+}

examples/pingone-configuring-the-self-service-application/supporting-config.tf

@@ -0,0 +1,16 @@
+locals {
+  pingone_environment_name = var.append_date_to_environment_name ? format("%s %s", var.pingone_environment_name, formatdate("YYYY-MMM-DD hhmm", time_static.current.id)) : var.pingone_environment_name
+}
+
+resource "pingone_environment" "my_environment" {
+  name        = local.pingone_environment_name
+  description = "This environment was created by Terraform as an example of how to configure the Self-Service application."
+  type        = "SANDBOX"
+  license_id  = var.pingone_environment_license_id
+
+  services = [{
+    type = "SSO"
+  }]
+}
+
+resource "time_static" "current" {}

examples/pingone-configuring-the-self-service-application/variables.tf

@@ -0,0 +1,21 @@
+variable "pingone_environment_license_id" {
+  description = "The license ID to use for the PingOne environment.  For more information about finding the license ID, see https://terraform.pingidentity.com/getting-started/pingone/#finding-required-ids"
+  type        = string
+
+  validation {
+    condition     = var.pingone_environment_license_id != null && can(regex("^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", var.pingone_environment_license_id))
+    error_message = "The pingone_environment_license_id value must be a valid PingOne resource ID, which is a UUID format."
+  }
+}
+
+variable "pingone_environment_name" {
+  description = "A string that represents the name of the PingOne customer environment to create and manage with Terraform."
+  type        = string
+  default     = "Terraform Example - Configuring the Self-Service Application"
+}
+
+variable "append_date_to_environment_name" {
+  description = "A boolean that determines whether to append the current date to the pingone_environment_name value."
+  type        = bool
+  default     = true
+}

examples/pingone-configuring-the-self-service-application/versions.tf

@@ -0,0 +1,18 @@
+terraform {
+  required_version = ">= 1.2"
+
+  required_providers {
+    pingone = {
+      source  = "pingidentity/pingone"
+      version = ">= 1.0.0, < 2.0.0"
+    }
+    time = {
+      source  = "hashicorp/time"
+      version = ">= 0.9.1, < 1.0.0"
+    }
+  }
+}
+
+provider "pingone" {}
+
+provider "time" {}