Adds documentation for managing keycloak instance via API

docs/deployment/authorization-and-authentication/Keycloak-API-Access-and-User-Creation.md

@@ -0,0 +1,95 @@
+# Keycloak Management via API Access and User Creation
+
+**⚠️ This documentation is for keycloak <v20, see related [ticket](https://github.com/cBioPortal/cbioportal/issues/10360) ⚠️**
+
+## Introduction
+You may wish to programmatically manage aspects of your Keycloak setup via the Keycloak API. 
+This is particularly useful for tasks such as:
+1. Bulk User Creation
+2. Modifying group membership
+3. Assigning roles to many users
+
+The following instructions will show you how to configure a Keycloak Client Service Account and assign appropriate permissions required for the management task.
+
+> [!NOTE]
+> Important URLS
+> https://\<KEYCLOAK_HOST\>/auth/admin/master/console/#/realms/\<REALM\>/clients
+> https://\<KEYCLOAK_HOST\>/auth/realms/\<REALM\>/protocol/openid-connect/token
+
+## Configure a Keycloak Client
+Navigate to: <Realm> -> Clients -> Select Client: `realm-management` -> Settings tab
+
+We’re using the `realm-management` client here but you can configure any other client. Make sure the following options are set.
+
+![](/images/previews/keycloak-api-access-settings.png)
+
+| parameter        | value  | comment  |
+| ------------- |:-------------:| -----:|
+| Enabled | true ||
+| Client Protocol | openid-connect | (default value) |
+| Access Type | confidential | This will allow us to make a call to the token service endpoint and follow an openid login flow. |
+| Valid Redirect URIs | _url_ | _url_ refers to base url of keycloak instance. Access Type must be set to confidential for this option to show |
+| Service Accounts Enabled | true | (default value). Access Type must be set to confidential for this option to show |
+
+> [!NOTE]
+> 1. The redirect url and service accounts enabled options will not appear on the UI until the Access Type -> confidential
+> 2. The Service Account Roles TAB will not show until Service Accounts Enabled: True
+
+> [!TIP]
+> 1. Configure ONE client per application/script (set of scripts) that will make calls against the Keycloak API. That way you can manage/revoke permissions and also regenerate the client_secret if needed. 
+
+## Obtain Client Credentials
+Navigate to: <Realm> -> Clients -> Select Client: `realm-management` -> Credentials tab
+
+1. Select `Client Id and Secret`
+2. Click `Regenerate Secret` to generate a secret
+3. Keep `ClientId` and `Secret` for obtaining an access token from keycloak
+
+![](/images/previews/keycloak-api-access-credentials.png)
+
+| parameter        | value  | comment  |
+| ------------- |:-------------:| -----:|
+| Client Authenticator | Client Id and Secret |  |
+
+## Configure Service Account Roles
+Navigate to: <Realm> -> Clients -> Select Client: `realm-management` -> `Service Account Roles` Tab
+
+Under `Client Roles` -> Select the `realm-management` from the dropdown menu
+
+From here scroll through the available roles for the `view-users` roles. Click `Add selected >>` 
+Assign additional roles if needed.
+
+![](/images/previews/keycloak-api-access-service-account.png)
+
+> [!NOTE]
+> 1. For managing users, we want to assign “manage-users” and “view-users” roles to “realm-management”
+> 2. Only add the permissions you require for the tasks that will be performed.
+
+
+## Make API calls to the Keycloak 12 REST API
+See Keycloak REST-API [documentation](https://www.keycloak.org/docs-api/latest/rest-api/index.html)
+
+Provide `client_id`, `client_secret`, `grant_type=”client_credentials”` as `x-www-form-urlencoded`
+
+1. Make a call to the token service to obtain an access token
+```bash
+# Obtain an access token
+curl -X POST https://<KEYCLOAK_HOST>/auth/realms/<REALM>/protocol/openid-connect/token \
+    -H 'Content-type: application/x-www-form-urlencoded' \
+    -d "client_id=$(KC_CLIENT_ID)" \
+    -d "client_secret=$(KC_CLIENT_SECRET)" \
+    -d "grant_type=$(KC_GRANT_TYPE)" | jq '.access_token'
+```
+
+2. Send the token which each request
+```bash
+# Get keycloak users
+curl -X GET https://<KEYCLOAK_HOST>/auth/admin/realms/<REALM>/users \
+    -H "Authorization: Bearer ${ACCESS_TOKEN}" \
+    -H 'cache-control: no-cache'
+```
+
+
+> [!NOTE]
+> 1. The access token by default only has a life of 300s (5min). This can be adjusted under the Settings Tab -> Advanced Settings Access Token Lifespan.
+> 2. These calls were made against Keycloak version 12 so they must include <KEYCLOAK_HOST>`/auth/`