add opaque Bearer Token to approved authentication methods #398

jboyd01 · 2017-12-19T14:19:22Z

fixes #381

per https://tools.ietf.org/html/rfc6750 I explicitly called out that when using bearer tokens you must be using TLS.

cfdreddbot · 2017-12-19T14:19:22Z

Hey jboyd01!

Thanks for submitting this pull request!

All pull request submitters and commit authors must have a Contributor License Agreement (CLA) on-file with us. Please sign the appropriate CLA (individual or corporate).

When sending signed CLA please provide your github username in case of individual CLA or the list of github usernames that can make pull requests on behalf of your organization.

If you are confident that you're covered under a Corporate CLA, please make sure you've publicized your membership in the appropriate Github Org, per these instructions.

Once you've publicized your membership, one of the owners of this repository can close and reopen this pull request, and dreddbot will take another look.

duglin · 2017-12-19T15:00:19Z

I'm not sure we can do it this way w/o breaking backwards compat. Rather I think we can get the same net results by adding a subsection that basically talks about how "if" bearer tokens are used then this is how you do it.

arschles · 2017-12-19T18:36:10Z

+1 to @duglin. It would be nice to keep the MUST language under the "If bearer tokens are used" subsection though.

cfdreddbot · 2017-12-19T21:05:46Z

Hey jboyd01!

Thanks for submitting this pull request! I'm here to inform the recipients of the pull request that you and the commit authors have already signed the CLA.

jboyd01 · 2017-12-19T21:07:11Z

@duglin , @arschles I've attempted a rework on this, happy to go a different direction if you think there is something better.

arschles

I think this looks ok, thanks @jboyd01. LGTM

mattmcneeney · 2018-01-05T10:14:35Z

This looks good to me too.

As a side note @jboyd01, do you have any documentation outlining how you see this working generally?

mattmcneeney · 2018-01-05T10:42:44Z

spec.md

+An alternative to carrying basic authentication on every request is to utilize a
+bearer token via the `Authorization: Bearer` header.  When a bearer token is
+used additional processes are often required to deal with token expiration and
+renewal.  These are details not covered by this specification and must be worked


Travis will complain about lowercase must

mattmcneeney · 2018-01-05T10:43:23Z

spec.md

@@ -165,6 +165,13 @@ 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.

+An alternative to carrying basic authentication on every request is to utilize a
+bearer token via the `Authorization: Bearer` header.  When a bearer token is
+used additional processes are often required to deal with token expiration and


Travis will complain about lowercase required

jboyd01 · 2018-01-08T15:44:08Z

@mattmcneeney, thanks for the review. regarding your question above about "any documentation outlining how you see this working generally" - I don't think we have any doc, but as a concrete example:

Service Catalog uses opaque tokens on Open Shift for authenticating with our service brokers such as the Ansible Service Broker. When a new Broker is created, the broker authentication information specifies to use a specific secret whose content contains the necessary bearer token. The bearer token secret is created external to Catalog by the Broker installation and the token does not expire.

If you desire token expiration, you would need a mechanism to update the K8s secret. The updated secret would automatically be picked up by Service Catalog the next time it is referenced.

duglin · 2018-01-09T13:56:43Z

The text itself looks good. Just one higher-level question... why are we calling out this one specific security mechanism? Will this open the door to people wanted to add guidance for others as well? For now I guess its ok, but I'm not keen on duplicating what should really be part of the "out of bands agreement(spec)" that we say the platform and broker decide on. Its kind of like we're saying "its none of our business, but we're gonna tell you want to do anyway" :-)

n3wscott · 2018-01-11T23:10:44Z

spec.md

+used additional processes are often needed to deal with token expiration and
+renewal.  These are details not covered by this specification and need to be
+worked out by the Platform.  If bearer tokens are used communication with the
+Broker MUST be secured over TLS.


Broker -> Service Broker

duglin · 2018-01-12T15:00:17Z

Per our last call, I believe Jay, Aaron and Alex are going to talk off-line about rewording this. I think to mainly focus on how using TLS is good when any auth mechanism is used.

jboyd01 · 2018-01-23T20:36:41Z

Alex, Aaron and I are doing some additional rework on this removing the specifics about opaque token and clarifying some aspects around authentication. Marked as Work In Progress for now, not ready for review.

mattmcneeney · 2018-01-24T15:16:43Z

Hey @jboyd01 You may want to rebase this PR on top of master as I believe it's showing many changes that aren't part of this change!

… paragraph

…ation

jboyd01 · 2018-01-24T15:59:49Z

@mattmcneeney Yes, it was a rebase gone bad, got it straightened out now. Thanks

duglin · 2018-01-24T17:11:18Z

spec.md

@@ -163,9 +163,15 @@ 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 brokers may agree on an authentication mechanism other than


s/brokers/Service Brokers/
s/may/MAY/

duglin · 2018-01-29T13:34:25Z

profile.md

+
+The [specification](spec.md) requires that brokers implement HTTP Basic authentication, but also allows for other mechanisms if the platform and the broker agree upon them outside of the specification. This section contains a list of supported mechanisms that platforms and brokers support. The list will be growing as time goes on.
+
+- The [Kubernetes Service Catalog](https://github.com/kubernetes-incubator/service-catalog) supports arbitrary HTTP Bearer tokens over TLS as an authentication mechanism


I'm not sure we want to add this to the profile - it feels kind of awkward since each time an impl changes what it supports we'd need to publish a new version of the profile. Putting it in our wiki might be ok though. Or just pointing people to the docs for each impl.

If we wanted to add something to the Profile about auth, then I think having auth-specific rules or guidance would be appropriate - stuff that all impls should adhere to.

As a service author, where can I go to learn how to build a broker against this? The service-catalog readme doesn't direct me anywhere to learn this

This is why the info here shouldn't really be platform specific, rather, if anything, it would be auth specific. E.g. I don't think svc-cat's use of HTTP bearer tokens is unique, or at least I hope not, otherwise we wouldn't have interop.

I kind of wonder what the purpose of this text is. I don't think we should just reiterate what each platform's docs say w.r.t. which auth mechanisms it supports. That's not only duplicate info but requires us to keep things in sync. I'd prefer for this section to be more about any OSB API specific aspects of the various auth mechanisms Platforms support that people will need to know about if they want to write code - that way the odds of having interop go up.

re Matt's comment

As a service author, where can I go to learn how to build a broker against this? The service-catalog readme doesn't direct me anywhere to learn this

We've got a general documentation issue we hope to address for the next major release which will help, but you are right, presently there isn't much doc on this

+1 to ^^ - we don't have much to put here yet, but it would be nice to set the precedent. if we don't want to put specific systems in here, I would be ok with something like a "coming soon" in this section

Per offline conversation with @duglin, @jboyd01 and myself, we will:

move this section into the spec.md, replacing it with the link to profile.md

link to a wiki page which @duglin will create

the wiki page will be non-normative and contain at least a non-exhaustive list of known platforms (and possibly brokers in the future?) that implement other auth. mechanisms

mattmcneeney · 2018-01-29T13:37:42Z

profile.md

@@ -232,6 +233,12 @@ part of a Kubernetes API call:
  }
  ```

+## Platform to Service Broker Authentication
+
+The [specification](spec.md) requires that brokers implement HTTP Basic authentication, but also allows for other mechanisms if the platform and the broker agree upon them outside of the specification. This section contains a list of supported mechanisms that platforms and brokers support. The list will be growing as time goes on.


s/brokers/Service Brokers

mattmcneeney · 2018-01-29T13:39:29Z

profile.md

+
+The [specification](spec.md) requires that brokers implement HTTP Basic authentication, but also allows for other mechanisms if the platform and the broker agree upon them outside of the specification. This section contains a list of supported mechanisms that platforms and brokers support. The list will be growing as time goes on.
+
+- The [Kubernetes Service Catalog](https://github.com/kubernetes-incubator/service-catalog) supports arbitrary HTTP Bearer tokens over TLS as an authentication mechanism


As a service author, where can I go to learn how to build a broker against this? The service-catalog readme doesn't direct me anywhere to learn this

fmui · 2018-01-30T09:18:29Z

spec.md

-using the predetermined authentication mechanism and MUST return a `401
-Unauthorized` response if the authentication fails.
+using the predetermined authentication mechanism, securing communications
+via TLS, and MUST return a `401 Unauthorized` response if the authentication


A dependency on TLS makes service broker development more difficult. For production TLS is a must, for development not necessarily. If we insist on TLS, do we allow self-signed certificates?

I'd be ok with self-signed certs for non-production deployments, or honestly even not requiring TLS in those cases

Per offline conversation with @duglin, @jboyd01 and myself, we will change this language to require TLS only in production, and say that it's a decision between the broker and the platform whether they use root or self signed certs

duglin · 2018-02-06T15:59:04Z

rebase needed

duglin · 2018-02-07T00:38:32Z

there are a ton of other changes in here, did you mean to make those?

arschles · 2018-02-07T20:23:06Z

sorry @duglin @jboyd01 - my markdown linter went nuts in f50a287. I'm gonna back that out and this should be ready to go

arschles · 2018-02-08T17:47:11Z

@duglin @jboyd01 I have removed the lame commit I made that linted all the markdown. This should be good to go now

pmorie · 2018-02-20T17:56:15Z

spec.md

+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)


I don't understand why this isn't in the spec, but I'm happy with this for now.

pmorie · 2018-02-20T17:56:43Z

LGTM

jboyd01 · 2018-02-21T18:18:17Z

@duglin this should be all set, PTAL.

duglin · 2018-02-21T19:26:43Z

LGTM!

fmui · 2018-02-27T17:32:30Z

LGTM

mattmcneeney · 2018-02-27T17:37:16Z

spec.md

+using the predetermined authentication mechanism, and MUST return a `401 Unauthorized`
+response if the authentication fails.
+
+Additionally, the Service Broker MUST secure communucations with TLS. The Platform


communucations -> communications

duglin · 2018-03-06T06:27:15Z

LGTM
3 more needed

fmui · 2018-03-06T14:18:53Z

LGTM

mattmcneeney · 2018-03-06T15:02:47Z

LGTM

n3wscott · 2018-03-06T16:29:12Z

LGTM

jboyd01 closed this Dec 19, 2017

jboyd01 reopened this Dec 19, 2017

arschles approved these changes Dec 19, 2017

View reviewed changes

mattmcneeney added this to the 2.14 milestone Jan 5, 2018

mattmcneeney added this to Top priorities in Roadmap & Release Planning Jan 5, 2018

mattmcneeney reviewed Jan 5, 2018

View reviewed changes

mattmcneeney added the needs rebase/work label Jan 5, 2018

duglin removed the needs rebase/work label Jan 9, 2018

avade self-assigned this Jan 9, 2018

n3wscott reviewed Jan 11, 2018

View reviewed changes

jboyd01 changed the title ~~add opaque Bearer Token to approved authentication methods~~ [WIP] add opaque Bearer Token to approved authentication methods Jan 23, 2018

Jay Boyd added 4 commits January 24, 2018 10:26

add opaque Bearer Token to approved authentication methods

3f51ecd

rework the bearer token as a follow on to the original authentication…

22face4

… paragraph

use alternate wording for 'required' and 'must'

bc5d9f8

removed opaque token text, added some clarifications around authentic…

d207c2e

…ation

jboyd01 force-pushed the bearer-token branch from 76cf066 to d207c2e Compare January 24, 2018 15:48

duglin reviewed Jan 24, 2018

View reviewed changes

duglin reviewed Jan 29, 2018

View reviewed changes

mattmcneeney reviewed Jan 29, 2018

View reviewed changes

fmui reviewed Jan 30, 2018

View reviewed changes

duglin added the needs rebase/work label Feb 6, 2018

Adding text to direct to the auth wiki page

99c458a

Adding language regarding the TLS certificates

2619553

arschles force-pushed the bearer-token branch from d9e00f2 to 2619553 Compare February 8, 2018 17:46

arschles and others added 2 commits February 8, 2018 10:20

removing platform to service broker auth section

df3cdd2

fix lint issues

ed95067

jboyd01 force-pushed the bearer-token branch from 8bee608 to ed95067 Compare February 8, 2018 18:50

pmorie reviewed Feb 20, 2018

View reviewed changes

mattmcneeney reviewed Feb 27, 2018

View reviewed changes

spelling: communications

4aaf6e9

n3wscott removed the needs rebase/work label Mar 6, 2018

n3wscott merged commit cd84faa into openservicebrokerapi:master Mar 6, 2018

mattmcneeney moved this from Top priorities to Ready for 2.14 in Roadmap & Release Planning Jul 12, 2018

williammartin mentioned this pull request Aug 17, 2018

Is the spec contradictory around TLS requirements? #571

Closed

teddyking mentioned this pull request Mar 13, 2020

Add support for OSBAPI 2.14 kubernetes-retired/go-open-service-broker-client#144

Closed


		The [specification](spec.md) requires that brokers implement HTTP Basic authentication, but also allows for other mechanisms if the platform and the broker agree upon them outside of the specification. This section contains a list of supported mechanisms that platforms and brokers support. The list will be growing as time goes on.

		- The [Kubernetes Service Catalog](https://github.com/kubernetes-incubator/service-catalog) supports arbitrary HTTP Bearer tokens over TLS as an authentication mechanism

add opaque Bearer Token to approved authentication methods #398

add opaque Bearer Token to approved authentication methods #398

Conversation

jboyd01 commented Dec 19, 2017

cfdreddbot commented Dec 19, 2017

duglin commented Dec 19, 2017

arschles commented Dec 19, 2017

cfdreddbot commented Dec 19, 2017

jboyd01 commented Dec 19, 2017

arschles left a comment

Choose a reason for hiding this comment

mattmcneeney commented Jan 5, 2018

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jboyd01 commented Jan 8, 2018

duglin commented Jan 9, 2018

Choose a reason for hiding this comment

duglin commented Jan 12, 2018

jboyd01 commented Jan 23, 2018

mattmcneeney commented Jan 24, 2018

jboyd01 commented Jan 24, 2018

Choose a reason for hiding this comment

duglin Jan 29, 2018 • edited Loading

Choose a reason for hiding this comment

duglin Jan 29, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

duglin commented Feb 6, 2018

duglin commented Feb 7, 2018

arschles commented Feb 7, 2018

arschles commented Feb 8, 2018

Choose a reason for hiding this comment

pmorie commented Feb 20, 2018 • edited by avade Loading

jboyd01 commented Feb 21, 2018

duglin commented Feb 21, 2018 • edited by avade Loading

fmui commented Feb 27, 2018 • edited by avade Loading

Choose a reason for hiding this comment

duglin commented Mar 6, 2018 • edited by avade Loading

fmui commented Mar 6, 2018 • edited by avade Loading

mattmcneeney commented Mar 6, 2018 • edited by avade Loading

n3wscott commented Mar 6, 2018 • edited by avade Loading

duglin Jan 29, 2018 •

edited

Loading

duglin Jan 29, 2018 •

edited

Loading

pmorie commented Feb 20, 2018 •

edited by avade

Loading

duglin commented Feb 21, 2018 •

edited by avade

Loading

fmui commented Feb 27, 2018 •

edited by avade

Loading

duglin commented Mar 6, 2018 •

edited by avade

Loading

fmui commented Mar 6, 2018 •

edited by avade

Loading

mattmcneeney commented Mar 6, 2018 •

edited by avade

Loading

n3wscott commented Mar 6, 2018 •

edited by avade

Loading