Add an Originating Identity http header

Closes #110 Signed-off-by: Doug Davis <dug@us.ibm.com>
openservicebrokerapi · Aug 29, 2017 · b8570de · b8570de
1 parent 5e4bbd3
commit b8570de
Show file tree

Hide file tree

Showing 2 changed files with 208 additions and 4 deletions.
diff --git a/profile.md b/profile.md
@@ -6,9 +6,14 @@ The [Open Service Broker API specification](spec.md) allows for extensions
 and variations based on the environments in which it is being used; this
 document contains the suggested usage pattern for some of those variants.
 
+While use of this profile is OPTIONAL, an implementation is not compliant
+with this profile if it fails to satisfy one or more of the MUST, SHALL
+or REQUIRED level requirements defined herein.
+
 ## Table of Contents
 
 - [Notations and Terminology](#notations-and-terminology)
+- [Originating Identity Header](#originating-identity-header)
 - [Context Object](#context-object)
   - [Context Object Properties](#context-object-properties)
   - [Cloud Foundry](#cloud-foundry)
@@ -55,6 +60,77 @@ the [Open Service Broker API specification](spec.md) SHALL take precedence.
 
 - *Application*: The software that uses a Service Instance via Service Binding.
 
+## Originating Identity Header
+
+In the [Open Service Broker API specification](spec.md) it defines an
+additional HTTP Header that can be included in messages from the Platform
+to identify the user that requested the action to be taken.
+
+The header consists of two parts: a `platform` string and `value` string,
+where the `value` is a Base64 encoded serialized JSON object.
+Both parts will vary based on the Platform which is being used. The
+following sections define the values to be used based on the Platform
+and which properties are expected to appear in the `value` JSON.
+
+Note that when both the originating identity HTTP Header and the Context
+object appear in the same message the `platform` value MUST be the same
+for both.
+
+### Cloud Foundry
+
+*`platform` Value*: `cloudfoundry`
+
+The following properties MUST appear within the JSON encoded `value`:
+
+| Property | Type | Description |
+| --- | --- | --- |
+| user_id | string | The `user_id` value from the Cloud Foundry JWT token. |
+
+Platforms MAY include additional properties.
+
+For example, a `value` of:
+```
+{
+  "user_id": "683ea748-3092-4ff4-b656-39cacc4d5360"
+}
+```
+would appear in the HTTP Header as:
+```
+X-Broker-API-Originating-Identity: cloudfoundry eyANCiAgInVzZXJfaWQiOiAiNjgzZWE3NDgtMzA5Mi00ZmY0LWI2NTYtMzljYWNjNGQ1MzYwIiwNCiAgInVzZXJfbmFtZSI6ICJqb2VAZXhhbXBsZS5jb20iDQp9
+```
+
+### Kubernetes
+
+*`platform` Value*: `kubernetes`
+
+The following properties MUST appear within the JSON encoded `value`:
+
+| Property | Type | Description |
+| --- | --- | --- |
+| username | string | The `username` property from the Kubenernetes `user.info` object. |
+| uid | string | The `uid` property from the Kubenernetes `user.info` object. |
+| groups | array-of-strings | The `groups` property from the Kubenernetes `user.info` object. |
+| extra | map-of-array-of-strings | The `extra` property from the Kubernetes `user.info` object. |
+
+Platforms MAY include additional properties.
+
+For example, a `value` of:
+```
+{
+  "username": "duke",
+  "uid": "c2dde242-5ce4-11e7-988c-000c2946f14f",
+  "groups": { "admin", "dev" },
+  "extra": {
+    "mydata": { "data1", "data3" }
+  }
+}
+```
+would appear in the HTTP Header as:
+```
+X-Broker-API-Originating-Identity: kubernetes eyANCiAgInVzZXJuYW1lIjogImR1a2UiLA0KICAidWlkIjogImMyZGRlMjQyLTVjZTQtMTFlNy05ODhjLTAwMGMyOTQ2ZjE0ZiIsDQogICJncm91cHMiOiB7ICJhZG1pbiIsICJkZXYiIH0NCn0=
+```
+
+
 ## Context Object
 
 In the [Open Service Broker API specification](spec.md) there are certain
@@ -69,10 +145,6 @@ it is often useful and necessary for there to be an agreed upon set of
 properties to ensure a common understanding of this data between the
 Platform and the Service Brokers.
 
-While use of this profile is OPTIONAL, an implementation is not compliant
-with this profile if it fails to satisfy one or more of the MUST, SHALL
-or REQUIRED level requirements defined herein.
-
 ### Context Object Properties
 
 The list of properties within the Context Object can vary depending on
@@ -93,6 +165,10 @@ The `platform` property MUST be a `string` and serialized as follows:
 Each section below will define the `platform` value that MUST be used based
 on the Platform and the set of additional properties that MUST be present.
 
+Note that when both the originating identity HTTP Header and the Context
+object appear in the same message the `platform` value MUST be the same
+for both.
+
 #### Cloud Foundry
 
 *`platform` Property Value*: `cloudfoundry`

diff --git a/spec.md b/spec.md
@@ -8,6 +8,7 @@
     - [Changes Since v2.11](#changes-since-v211)
   - [API Version Header](#api-version-header)
   - [Authentication](#authentication)
+  - [Originating Identity](#originating-identity)
   - [Catalog Management](#catalog-management)
     - [Adding a Broker to the Platform](#adding-a-broker-to-the-platform)
   - [Synchronous and Asynchronous Operations](#synchronous-and-asynchronous-operations)
@@ -126,6 +127,58 @@ response if the authentication fails.
 Note: Using an authentication mechanism that is agreed to via out of band
 communications could lead to interoperability issues with other platforms.
 
+## Originating Identity
+
+Often a service broker will need to know the identity of the user that
+initiated the request from the platform. For example, this might be needed
+for auditing or authorization purposes. In order to facilitate this, the
+platform will need to provide this identification information to the broker
+on each request. Platforms MAY support this feature, and if they do, they
+MUST adhere to the following:
+- for any OSB API request that is the result of an action taken by
+  a platform's user, there MUST be an associated `OriginatingIdentity` header
+  on that HTTP request,
+- any OSB API request that is not associated with an action from a platform's
+  user, such as the platform querying the marketplace, MAY
+  exclude the header from that HTTP request,
+- if present on a request, the `OriginatingIdentity` header MUST contain
+  the identify information for the platform's user that took the action
+  to cause the request to be sent.
+
+The format of the header MUST be:
+
+```
+X-Broker-API-Originating-Identity: platform value
+```
+
+`platform` MUST be a non-empty string indicating the platform from which
+the request is being sent. The specific value SHOULD match the values
+defined in the [profile](profile.md) document for the `context.platform`
+property. When `context` is sent as part of a message, this value MUST
+be the same as the `context.platform` value.
+
+`value` MUST be a Base64 encoded string. The string MUST be a serialized
+JSON object. The specific properties will be platform specific - see
+the [profile](profile.md) document for more information.
+
+For example:
+```
+X-Broker-API-Originating-Identity: cloudfoundry eyANCiAgInVzZXJfaWQiOiAiNjgzZWE3NDgtMzA5Mi00ZmY0LWI2NTYtMzljYWNjNGQ1MzYwIiwNCiAgInVzZXJfbmFtZSI6ICJqb2VAZXhhbXBsZS5jb20iDQp9
+```
+
+Where the `value`, when decoded, is:
+```
+{
+  "user_id": "683ea748-3092-4ff4-b656-39cacc4d5360"
+}
+```
+
+Note that not all messages sent to a broker are initiated by an end-user
+of the platform. For example, during orphan mitigation or during the
+querying of the broker's catalog, the platform might not have an end-user
+with which to associate the request, therefore in those cases the
+originating identity header would not be included in those messages.
+
 ## Catalog Management
 
 The first endpoint that a platform will interact with on the broker is the
@@ -163,6 +216,16 @@ Broker API.
 #### Route
 `GET /v2/catalog`
 
+#### Headers
+
+The following HTTP Headers are defined for this operation:
+
+| Header | Type | Description |
+| --- | --- | --- |
+| X-Broker-API-Version* | string | See [API Version Header](#api-version-header). |
+
+\* Headers with an asterisk are REQUIRED.
+
 #### cURL
 ```
 $ curl -H "X-Broker-API-Version: 2.12" http://username:password@broker-url/v2/catalog
@@ -393,6 +456,16 @@ The request provides these query string parameters as useful hints for brokers.
 
 Note: Although the request query parameters `service_id` and `plan_id` are not mandatory, the platform SHOULD include them on all `last_operation` requests it makes to service brokers.
 
+#### Headers
+
+The following HTTP Headers are defined for this operation:
+
+| Header | Type | Description |
+| --- | --- | --- |
+| X-Broker-API-Version* | string | See [API Version Header](#api-version-header). |
+
+\* Headers with an asterisk are REQUIRED.
+
 #### cURL
 ```
 $ curl http://username:password@broker-url/v2/service_instances/:instance_id/last_operation
@@ -450,6 +523,17 @@ broker will use it to correlate the resource it creates.
 | --- | --- | --- |
 | accepts_incomplete | boolean | A value of true indicates that the marketplace and its clients support asynchronous broker operations. If this parameter is not included in the request, and the broker can only provision a service instance of the requested plan asynchronously, the broker MUST reject the request with a `422 Unprocessable Entity` as described below. |
 
+#### Headers
+
+The following HTTP Headers are defined for this operation:
+
+| Header | Type | Description |
+| --- | --- | --- |
+| X-Broker-API-Version* | string | See [API Version Header](#api-version-header). |
+| X-Broker-API-Originating-Identity | string | See [Originating Identity](#originating-identity). |
+
+\* Headers with an asterisk are REQUIRED.
+
 #### Body
 | Request field | Type | Description |
 | --- | --- | --- |
@@ -551,6 +635,17 @@ It MUST be the ID a previously provisioned service instance.
 | --- | --- | --- |
 | accepts_incomplete | boolean | A value of true indicates that the marketplace and its clients support asynchronous broker operations. If this parameter is not included in the request, and the broker can only provision a service instance of the requested plan asynchronously, the broker SHOULD reject the request with a `422 Unprocessable Entity` as described below. |
 
+#### Headers
+
+The following HTTP Headers are defined for this operation:
+
+| Header | Type | Description |
+| --- | --- | --- |
+| X-Broker-API-Version* | string | See [API Version Header](#api-version-header). |
+| X-Broker-API-Originating-Identity | string | See [Originating Identity](#originating-identity). |
+
+\* Headers with an asterisk are REQUIRED.
+
 #### Body
 
 | Request Field | Type | Description |
@@ -710,6 +805,17 @@ It MUST be the ID of a previously provisioned service instance.
 This ID will be used for future unbind requests, so the broker will use
 it to correlate the resource it creates.
 
+#### Headers
+
+The following HTTP Headers are defined for this operation:
+
+| Header | Type | Description |
+| --- | --- | --- |
+| X-Broker-API-Version* | string | See [API Version Header](#api-version-header). |
+| X-Broker-API-Originating-Identity | string | See [Originating Identity](#originating-identity). |
+
+\* Headers with an asterisk are REQUIRED.
+
 #### Body
 
 | Request Field | Type | Description |
@@ -879,6 +985,17 @@ The request provides these query string parameters as useful hints for brokers.
 
 \* Query parameters with an asterisk are REQUIRED.
 
+#### Headers
+
+The following HTTP Headers are defined for this operation:
+
+| Header | Type | Description |
+| --- | --- | --- |
+| X-Broker-API-Version* | string | See [API Version Header](#api-version-header). |
+| X-Broker-API-Originating-Identity | string | See [Originating Identity](#originating-identity). |
+
+\* Headers with an asterisk are REQUIRED.
+
 #### cURL
 ```
 $ curl 'http://username:password@broker-url/v2/service_instances/:instance_id/
@@ -928,6 +1045,17 @@ The request provides these query string parameters as useful hints for brokers.
 
 \* Query parameters with an asterisk are REQUIRED.
 
+#### Headers
+
+The following HTTP Headers are defined for this operation:
+
+| Header | Type | Description |
+| --- | --- | --- |
+| X-Broker-API-Version* | string | See [API Version Header](#api-version-header). |
+| X-Broker-API-Originating-Identity | string | See [Originating Identity](#originating-identity). |
+
+\* Headers with an asterisk are REQUIRED.
+
 #### cURL
 ```
 $ curl 'http://username:password@broker-url/v2/service_instances/:instance_id?accepts_incomplete=true