diff --git a/docs/user/04-10-custom-oidc-configuration.md b/docs/user/04-10-custom-oidc-configuration.md index e2cb18968d..9ebf981dcc 100644 --- a/docs/user/04-10-custom-oidc-configuration.md +++ b/docs/user/04-10-custom-oidc-configuration.md @@ -1,11 +1,49 @@ # Custom OIDC Configuration -To create an SAP BTP, Kyma runtime with a custom Open ID Connect (OIDC) configuration, specify the additional `oidc` provisioning parameters. +To create an SAP BTP, Kyma runtime with a custom Open ID Connect (OIDC) configuration, specify either a list of `oidc` objects or a single `oidc` object as a provisioning parameter. While both options are supported, using a list of `oidc` objects is the recommended approach, even if you are defining only one OIDC configuration. The list allows you to define multiple OIDC configurations. The single `oidc` object is only supported for backward compatibility. + +See the example with the OIDC list: > [!NOTE] -> `clientID` and `issuerURL` values are mandatory for custom OIDC configuration. +> All fields except `requiredClaims` are mandatory when using the `oidc` list for custom OIDC configuration. + +```bash + export VERSION=1.15.0 + curl --request PUT "https://$BROKER_URL/oauth/v2/service_instances/$INSTANCE_ID?accepts_incomplete=true" \ + --header 'X-Broker-API-Version: 2.14' \ + --header 'Content-Type: application/json' \ + --header "$AUTHORIZATION_HEADER" \ + --header 'Content-Type: application/json' \ + --data-raw "{ + \"service_id\": \"47c9dcbf-ff30-448e-ab36-d3bad66ba281\", + \"plan_id\": \"4deee563-e5ec-4731-b9b1-53b42d855f0c\", + \"context\": { + \"globalaccount_id\": \"$GLOBAL_ACCOUNT_ID\" + }, + \"parameters\": { + \"name\": \"$NAME\", + \"region\": \"$REGION\", + \"oidc\": { + \"list\": [ + { + \"clientID\": \"9bd05ed7-a930-44e6-8c79-e6defeb7dec5\", + \"issuerURL\": \"https://kymatest.accounts400.ondemand.com\", + \"groupsClaim\": \"groups\", + \"groupPrefix\": \"-\", + \"signingAlgs\": [\"RS256\"], + \"usernamePrefix\": \"-\", + \"usernameClaim\": \"sub\", + \"requiredClaims\": [], + } + ] + } + } + }" +
+See an example configuration with a single OIDC object (not recommended): -See the example: +> [!NOTE] +> `clientID` and `issuerURL` values are mandatory when using a single `oidc` object for custom OIDC configuration. ```bash export VERSION=1.15.0 @@ -35,9 +73,17 @@ See the example: }" ``` -If you do not provide the `oidc` object in the provisioning request or leave all object's properties empty, the default OIDC configuration is used. -However, if you do not provide the `oidc` object in the update request or leave all object’s properties empty, the saved OIDC configuration stays untouched. -See the following JSON example without the `oidc` object: +
+ +If you do not include an `oidc` list or a single `oidc` object in the provisioning request, the default OIDC configuration is applied. However, if you provide an empty `oidc` list with zero elements, no OIDC configuration is applied to the instance. Unlike the single `oidc` object, which defaults to the predefined values when its properties are left empty, the `oidc` list does not inherit default values for its items and they must be explicitly defined. + +## Examples + +### Configuration with No `oidc` Object and No List + +This example demonstrates a request without specifying any `oidc` configuration. The default OIDC configuration is applied automatically. + +**Request:** ```json { @@ -53,7 +99,91 @@ See the following JSON example without the `oidc` object: } ``` -See the following JSON example with the `oidc` object whose properties are empty: +**Applied OIDC Configuration:** + +```json +{ + ... + "oidc" : { + "clientID" : "9bd05ed7-a930-44e6-8c79-e6defeb7dec9", + "issuerURL" : "https://kymatest.accounts400.ondemand.com", + "groupsClaim" : "groups", + "groupsPrefix" : "-", + "signingAlgs" : ["RS256"], + "usernamePrefix" : "-", + "usernameClaim" : "sub", + "requiredClaims" : [] + } + ... +} +``` + +--- + +### Configuration with the `oidc` List + +This example shows a request with an `oidc` list containing a single configuration. The list allows defining multiple OIDC configurations. + +**Request:** + +```json +{ + "service_id" : "47c9dcbf-ff30-448e-ab36-d3bad66ba281", + "plan_id" : "4deee563-e5ec-4731-b9b1-53b42d855f0c", + "context" : { + "globalaccount_id" : {GLOBAL_ACCOUNT_ID} + }, + "parameters" : { + "region": {REGION}, + "name" : {CLUSTER_NAME}, + "oidc" : { + "list": [ + { + "clientID" : "9bd05ed7-a930-44e6-8c79-e6defeb7dec9", + "issuerURL" : "https://kymatest.accounts400.ondemand.com", + "groupsClaim" : "groups", + "groupsPrefix" : "-", + "signingAlgs" : ["RS256"], + "usernamePrefix" : "-", + "usernameClaim" : "sub", + "requiredClaims" : ["first-claim=value", "second-claim=value"] + } + ] + } + } +} +``` + +**Applied OIDC Configuration:** + +```json +{ + ... + "oidc" : { + "list": [ + { + "clientID" : "9bd05ed7-a930-44e6-8c79-e6defeb7dec9", + "issuerURL" : "https://kymatest.accounts400.ondemand.com", + "groupsClaim" : "groups", + "groupsPrefix" : "-", + "signingAlgs" : ["RS256"], + "usernamePrefix" : "-", + "usernameClaim" : "sub", + "requiredClaims" : ["first-claim=value", "second-claim=value"] + } + ] + } + ... +} +``` + +--- + +### Configuration with an Empty `oidc` Object + +This example illustrates a request with an `oidc` object where all properties are left empty. The default OIDC configuration is applied. + +**Request:** ```json { @@ -69,75 +199,191 @@ See the following JSON example with the `oidc` object whose properties are empty "clientID" : "", "issuerURL" : "", "groupsClaim" : "", + "groupsPrefix" : "", "signingAlgs" : [], "usernamePrefix" : "", - "usernameClaim" : "" + "usernameClaim" : "", + "requiredClaims" : [] } } } ``` -This is the default OIDC configuration in JSON: +**Applied OIDC Configuration:** ```json { ... - "oidc" : { - "clientID" : "9bd05ed7-a930-44e6-8c79-e6defeb7dec9", - "issuerURL" : "https://kymatest.accounts400.ondemand.com", - "groupsClaim" : "groups", - "signingAlgs" : ["RS256"], - "usernamePrefix" : "-", - "usernameClaim" : "sub" - } + "oidc" : { + "clientID" : "9bd05ed7-a930-44e6-8c79-e6defeb7dec9", + "issuerURL" : "https://kymatest.accounts400.ondemand.com", + "groupsClaim" : "groups", + "groupsPrefix" : "-", + "signingAlgs" : ["RS256"], + "usernamePrefix" : "-", + "usernameClaim" : "sub", + "requiredClaims" : [] + } ... } ``` -To update the OIDC configuration, provide values for the mandatory properties. Without these values, a validation error occurs. -The update operation overwrites the OIDC configuration values provided in JSON. It means that OIDC properties with empty values are considered valid. See the following scenario: +## Updating the OIDC Configuration + +To update the OIDC configuration, provide values for the mandatory properties. Without these values, a validation error occurs. If you omit the `oidc` list or the single `oidc` object in the update request, the existing OIDC configuration remains unchanged. Providing an empty `oidc` list clears the OIDC configuration for the instance. The update operation overwrites the OIDC configuration values provided in JSON for the `oidc` list, meaning that OIDC properties with empty values are considered valid and replace the existing values. However, for a single `oidc` object, empty values do not change the configuration, and only the provided values are updated. It is possible to update the configuration from a single `oidc` object to an `oidc` list. However, updating from an `oidc` list to a single `oidc` object is not supported. - 1. An existing instance has the following OIDC configuration: +--- - ``` - ClientID: 9bd05ed7-a930-44e6-8c79-e6defeb7dec9 - IssuerURL: https://kymatest.accounts400.ondemand.com - GroupsClaim: groups - UsernameClaim: sub - UsernamePrefix: - - SigningAlgs: RS256 - ``` +### Updating an Instance with an OIDC Object List + +1. The instance has the following OIDC object list configuration: + + ```json + [ + { + "clientID": "9bd05ed7-a930-44e6-8c79-e6defeb7dec9", + "issuerURL": "https://kymatest.accounts400.ondemand.com", + "groupsClaim": "groups", + "groupsPrefix": "-", + "usernameClaim": "sub", + "usernamePrefix": "-", + "signingAlgs": ["RS256"], + "requiredClaims": ["first-claim=value", "second-claim=value"] + }, + { + "clientID": "3f2a1c8e-7b4d-4e2f-9a6b-2d8e5f7c9d12", + "issuerURL": "https://foo.bar.com", + "groupsClaim": "groups", + "groupsPrefix": "-", + "usernameClaim": "sub", + "usernamePrefix": "acme-", + "signingAlgs": ["RS256"], + "requiredClaims": [] + } + ] + ``` - 2. A user sends an update request (HTTP PUT) with the following JSON in the payload: +2. To update the OIDC configuration, the user sends an HTTP PATCH request with the following payload: - ```json + ```json + { + "service_id": "47c9dcbf-ff30-448e-ab36-d3bad66ba281", + "plan_id": "4deee563-e5ec-4731-b9b1-53b42d855f0c", + "context": { + "globalaccount_id": "{GLOBAL_ACCOUNT_ID}" + }, + "parameters": { + "name": "{CLUSTER_NAME}", + "oidc": { + "list": [ { - "service_id" : "47c9dcbf-ff30-448e-ab36-d3bad66ba281", - "plan_id" : "4deee563-e5ec-4731-b9b1-53b42d855f0c", - "context" : { - "globalaccount_id" : {GLOBAL_ACCOUNT_ID} - }, - "parameters" : { - "name" : {CLUSTER_NAME}, - "oidc" : { - "clientID" : "new-client-id", - "issuerURL" : "https://new-issuer-url.local.com", - "groupsClaim" : "", - "signingAlgs" : [], - "usernamePrefix" : "", - "usernameClaim" : "" - } - } + "clientID": "9bd05ed7-a930-44e6-8c79-e6defeb7dec9", + "issuerURL": "https://kymatest.accounts400.ondemand.com", + "groupsClaim": "groups", + "groupsPrefix": "-", + "signingAlgs": ["RS256"], + "usernameClaim": "sub", + "usernamePrefix": "-", + "requiredClaims": [] + }, + { + "clientID": "test", + "issuerURL": "https://test.com", + "groupsClaim": "groups", + "groupsPrefix": "-", + "usernameClaim": "sub", + "usernamePrefix": "acme-", + "signingAlgs": ["RS256"], + "requiredClaims": [] } - ``` - - 3. The OIDC configuration is updated to include the values of the `oidc` object from JSON provided in the update request: - - ``` - ClientID: new-client-id - IssuerURL: https://new-issuer-url.local.com - GroupsClaim: - UsernameClaim: - UsernamePrefix: - SigningAlgs: - ``` + ] + } + } + } + ``` + +3. After the update, the OIDC configuration is modified to reflect the values provided in the request: + + ```json + [ + { + "clientID": "9bd05ed7-a930-44e6-8c79-e6defeb7dec9", + "issuerURL": "https://kymatest.accounts400.ondemand.com", + "groupsClaim": "groups", + "groupsPrefix": "-", + "usernameClaim": "sub", + "usernamePrefix": "-", + "signingAlgs": ["RS256"], + "requiredClaims": [] + }, + { + "clientID": "test", + "issuerURL": "https://test.com", + "groupsClaim": "groups", + "groupsPrefix": "-", + "usernameClaim": "sub", + "usernamePrefix": "acme-", + "signingAlgs": ["RS256"], + "requiredClaims": [] + } + ] + ``` + +--- + +### Updating an Instance with a Single OIDC Object + +1. The instance has the following OIDC object configuration: + + ```json + { + "clientID": "9bd05ed7-a930-44e6-8c79-e6defeb7dec9", + "issuerURL": "https://kymatest.accounts400.ondemand.com", + "groupsClaim": "groups", + "groupsPrefix": "-", + "usernameClaim": "sub", + "usernamePrefix": "-", + "signingAlgs": ["RS256"], + "requiredClaims": [] + } + ``` + +2. To update the OIDC configuration, the user sends an HTTP PATCH request with the following payload: + + ```json + { + "service_id": "47c9dcbf-ff30-448e-ab36-d3bad66ba281", + "plan_id": "4deee563-e5ec-4731-b9b1-53b42d855f0c", + "context": { + "globalaccount_id": "{GLOBAL_ACCOUNT_ID}" + }, + "parameters": { + "name": "{CLUSTER_NAME}", + "oidc": { + "clientID": "new-client-id", + "issuerURL": "https://new-issuer-url.local.com", + "groupsClaim": "", + "groupsPrefix": "", + "signingAlgs": [], + "usernamePrefix": "", + "usernameClaim": "", + "requiredClaims": [] + } + } + } + ``` + +3. After the update, the OIDC configuration is modified to reflect the values provided in the request: + + ```json + { + "clientID": "new-client-id", + "issuerURL": "https://new-issuer-url.local.com", + "groupsClaim": "groups", + "groupsPrefix": "-", + "usernameClaim": "sub", + "usernamePrefix": "-", + "signingAlgs": ["RS256"], + "requiredClaims": [] + } + ```