diff --git a/spec.md b/spec.md index 861183cc..60a6c4a4 100644 --- a/spec.md +++ b/spec.md @@ -7,7 +7,7 @@ - [Change Policy](#change-policy) - [Changes Since v2.12](#changes-since-v212) - [API Version Header](#api-version-header) - - [Authentication](#authentication) + - [Platform to Service Broker Authentication](#platform-to-service-broker-authentication) - [URL Properties](#url-properties) - [Originating Identity](#originating-identity) - [Service Broker Errors](#service-broker-errors) @@ -151,7 +151,7 @@ Service Broker MAY reject the request with `412 Precondition Failed` and provide a message that informs the operator of the API version that is to be used instead. -## Authentication +## Platform to Service Broker Authentication While the communication between a Platform and Service Broker MAY be unsecure, it is RECOMMENDED that all communications between a Platform and a Service @@ -163,9 +163,19 @@ Service Broker using HTTP basic authentication (the `Authorization:` header) on every request. This specification does not specify how Platform and Service Brokers agree on other methods of authentication. +Platforms and Service Brokers MAY agree on an authentication mechanism other +than basic authentication, but the specific agreements are not covered by this +specification. Please see the +[Platform Features authentication mechanisms wiki document](https://github.com/openservicebrokerapi/servicebroker/wiki/Platform-Features) +for details on these mechanisms. + If authentication is used, the Service Broker MUST authenticate the request -using the predetermined authentication mechanism and MUST return a `401 -Unauthorized` response if the authentication fails. +using the predetermined authentication mechanism, and MUST return a `401 Unauthorized` +response if the authentication fails. + +Additionally, the Service Broker MUST secure communications with TLS. The Platform +and Service Broker SHOULD agree whether the Service Broker will use a root-signed +certificate or a self-signed certificate. Note: Using an authentication mechanism that is agreed to via out of band communications could lead to interoperability issues with other Platforms.