docs: generic oidc

docs/content/en/docs-dev/user-guide/managing-controlplane/auth.md

@@ -16,7 +16,9 @@ After logging, the project admin should change the provided username and passwor
 
 ### Single Sign-On (SSO)
 
-Single sign-on (SSO) allows users to log in to PipeCD by relying on a trusted third-party service such as GitHub, GitHub Enterprise Server, Google Gmail, Bitbucket...
+Single sign-on (SSO) allows users to log in to PipeCD by relying on a trusted third-party service such as GitHub, GitHub Enterprise Server, Google Gmail, Bitbucket, or a generic OIDC provider.
+
+#### Github
 
 Before configuring the SSO, you need an OAuth application of the using service. For example, GitHub SSO requires creating a GitHub OAuth application as described in this page:
 
@@ -26,6 +28,103 @@ The authorization callback URL should be `https://YOUR_PIPECD_ADDRESS/auth/callb
 
 ![](/images/settings-update-sso.png)
 
+#### Generic OIDC
+
+PipeCD supports any OIDC provider, with tested providers including Keycloak, Auth0, and AWS Cognito. The only supported authentication flow currently is the Authorization Code Grant.
+
+Requirements:
+
+- The IdToken will be used to decide the user's role and username.
+- The IdToken must contain information about the Username and Role.
+  - Supported Claims Key for Username (in order of priority): `username`, `preferred_username`, `cognito:username`
+  - Supported Claims Key for Role (in order of priority): `groups`, `roles`, `cognito:groups`, `custom:roles`, `custom:groups`
+  - Supported Claims Key for Avatar (in order of priority): `picture`, `avatar_url`
+
+Provider Configuration Examples:
+
+##### Keycloak
+
+- **Client authentication**: On
+- **Valid redirect URIs**: `https://YOUR_PIPECD_ADDRESS/auth/callback`
+- **Client scopes**: Add a new mapper to the `<client-id>-dedicated` scope. For instance, map Group Membership information to the groups claim (Full group path should be off).
+
+- **Control Plane configuration**:
+
+  ```yaml
+  apiVersion: "pipecd.dev/v1beta1"
+  kind: ControlPlane
+  spec:
+    sharedSSOConfigs:
+      - name: oidc
+        provider: OIDC
+        oidc:
+          clientId: <CLIENT_ID>
+          clientSecret: <CLIENT_SECRET>
+          issuer: https://<KEYCLOAK_ADDRESS>/realms/<REALM>
+          redirect_uri: https://<PIPECD_ADDRESS>/auth/callback
+          scopes:
+            - openid
+            - profile
+  ```
+
+##### Auth0
+
+- **Allowed Callback URLs**: `https://YOUR_PIPECD_ADDRESS/auth/callback`
+- **Control Plane configuration**:
+
+  ```yaml
+  apiVersion: "pipecd.dev/v1beta1"
+  kind: ControlPlane
+  spec:
+    sharedSSOConfigs:
+      - name: oidc
+        provider: OIDC
+        oidc:
+          clientId: <CLIENT_ID>
+          clientSecret: <CLIENT_SECRET>
+          issuer: https://<AUTH0_ADDRESS>
+          redirect_uri: https://<PIPECD_ADDRESS>/auth/callback
+          scopes:
+            - openid
+            - profile
+  ```
+
+- **Roles/Groups Claims**
+  For Role or Groups information mapping using Auth0 Actions, here is an example for setting `custom:roles`:
+
+  ```javascript
+  exports.onExecutePostLogin = async (event, api) => {
+    let namespace = "custom";
+    if (namespace && !namespace.endsWith("/")) {
+      namespace += ":";
+    }
+    api.idToken.setCustomClaim(namespace + "roles", event.authorization.roles);
+  };
+  ```
+
+##### AWS Cognito
+
+- **Allowed Callback URLs**: `https://YOUR_PIPECD_ADDRESS/auth/callback`
+
+- **Control Plane configuration**:
+
+  ```yaml
+  apiVersion: "pipecd.dev/v1beta1"
+  kind: ControlPlane
+  spec:
+    sharedSSOConfigs:
+      - name: oidc
+        provider: OIDC
+        oidc:
+          clientId: <CLIENT_ID>
+          clientSecret: <CLIENT_SECRET>
+          issuer: https://cognito-idp.<AWS_REGION>.amazonaws.com/<USER_POOL_ID>
+          redirect_uri: https://<PIPECD_ADDRESS>/auth/callback
+          scopes:
+            - openid
+            - profile
+  ```
+
 The project can be configured to use a shared SSO configuration (shared OAuth application) instead of needing a new one. In that case, while creating the project, the PipeCD owner specifies the name of the shared SSO configuration should be used, and then the project admin can skip configuring SSO at the settings page.
 
 ### Role-Based Access Control (RBAC)