add documentation to set up OIDC auth with Ping Identity

Signed-off-by: Jessica He <[email protected]>

docs/customization.md

@@ -155,8 +155,8 @@ app:
             title: Janus Community
 ```
 
-<img src="images/example-support-button.png" alt="Example Support Configured" width="285">
+<img src="../images/example-support-button.png" alt="Example Support Configured" width="285">
 
 If support is not configured, it would look as below.
 
-<img src="images/support-not-configured.png" alt="Example Support Not Configured" width="285">
+<img src="../images/support-not-configured.png" alt="Example Support Not Configured" width="285">

docs/ping-identity-env-setup.md

@@ -1,4 +1,4 @@
-## Ping Identity Application Setup
+# Ping Identity Environment and Application Setup
 
 This script populates the Ping Identity environment with desired users/groups to test the [Ping Identity catalog plugin](https://github.com/backstage/community-plugins/tree/main/workspaces/pingidentity/plugins/catalog-backend-module-pingidentity). This would avoid the need to manually set up the environment each time the Ping Identity trial expires and a new account is required.
 

docs/ping-identity-oidc-setup.md

@@ -0,0 +1,52 @@
+# Ping Identity OIDC Authentication Provider Setup
+
+### Prerequisite: Configure Ping Identity Application
+
+Set up the Ping Identity environment and application. Refer to the [Ping Identity Application Setup](./ping-identity-env-setup.md) documentation for instructions.
+
+#### Edit Application Configuration
+
+Navigate to the `Application Overview > Configuration Tab` and click the edit button.
+
+- Check `Code` in `Response Type` and `Authorization Code` in `Grant Type`.
+
+<img src="../images/response_and_grant_type_ping_identity_app.png" alt="Response and Grant Type for Ping Identity Application" width="400">
+
+- Set Redirect URIs to `https://your-backstage.com/api/auth/oidc/handler/frame`.
+
+Navigate to the `Application Overview > Resources Tab` and click the edit button.
+
+- Add `email`, `offline_access` and `profile` to allowed scopes.
+
+<img src="../images/allowed_scopes_ping_identity_app.png" alt="Allowed Scopes for Ping Identity Application" width="800">
+
+**Note:** the display name in the RHDH instance maps to `Formatted Name` in Ping Identity user profile. If this parameter is not set, it will default to the user entity ref.
+
+- The `Formatted Name` can be set by navigating to `Directory` > `Users`, clicking on the target user then editing the user profile with the edit button.
+
+### Configuration
+
+The provider configuration can then be added to your app-config.yaml under the root auth configuration:
+
+```yaml
+auth:
+  providers:
+    oidc:
+      development:
+        metadataUrl: https://auth.pingone.ca/${PING_IDENTITY_ENV_ID}/as/.well-known/openid-configuration
+        clientId: ${PING_IDENTITY_CLIENT_ID}
+        clientSecret: ${PING_IDENTITY_CLIENT_SECRET}
+        prompt: auto #optional
+```
+
+The OIDC provider requires three mandatory configuration keys:
+
+- `clientId`: Copy from `Client ID` under `Configuration` tab.
+- `clientSecret`: Copy from `Client Secret` under `Configuration` tab.
+- `metadataUrl`: Copy from `OIDC Discovery Endpoint` under `Configuration` tab in `URLs` drop down.
+- `prompt` (optional): Recommended to use auto so the browser will request login to the IDP if the user has no active session.
+- `additionalScopes` (optional): List of scopes for the App Registration, to be requested in addition to the required ones.
+
+#### Known Issues
+
+In the resolved user profile, the profile picture is rendered properly when frontend and backend are run on separate ports (i.e. `3000` and `7007`) but not when both are on the same port (i.e. both on `7007`).