Subject: [OAUTH-WG] Issuers, Discovery Docs & Brands

From: Dave Tonge <[email-masked]>
Date: Wed, 20 May 2020 14:07:09 +0200

Dear OAuth WG

We have an issue
<https://bitbucket.org/openid/fapi/issues/255/certification-clarification-request>
in the OpenID FAPI Working Group that we believe affects the wider OAuth
community.

In summary: *what is the recommended approach to discovery (RFC8414) for
Authorization Servers who support multiple "brands" .*

If brands are completely separate, then it seems sensible that each brand
must have its own `issuer` and therefore its own discovery document at the
correct location (i.e. brand 1 would have an issuer of "https://as/brand1"
and a discovery document available at  https://as/.well-known/
oauth-authorization-server/brand1).

However in the real world it is not always so simple. We have many existing
implementations in UK open banking that support multiple authorization
endpoints. Here is an example (thanks to @Joseph Heenan
<[email-masked]> )

> Bank “loadsamoney” has one idp and, for internet banking, one “login
page” for both business and personal customers.

> They have separate mobile apps for business/personal, and are required to
support app2app. This means they will definitely be exposing multiple
authorization endpoints (as there’s a 1:1 mapping of authorization
endpoints to mobile apps) - the choice is how they do this.

> Their choices are:

> 1. Multiple discovery endpoints (one for business, one for personal),
each with a different authorization endpoint, multiple issuers (if their
vendor allows this)
> 2. Single discovery endpoint, single issuer, multiple authorization
endpoints listed in one discovery doc (one for business, one for personal)
some of which are hardcoded by the 3rd party
> 3. Multiple discovery endpoints each with a different authorization
endpoint, same issuer in all cases (breaks RFC8414 and OIDC Discovery)

Option 3 is invalid and that leaves us with options 1 and 2.
Option 1 can be problematic as often it is in reality the same `issuer`
behind the scenes.

We would like to get feedback on this issue and potentially an extension to
RFC8414 to allow the definition of multiple authorization endpoints.

Thanks in advance

Dave Tonge
Co-Chair FAPI WG
Open ID Foundation

---

From: Vladimir Dzhuvinov <[email-masked]>
Date: Wed, 20 May 2020 18:07:57 +0300

Hi Dave,

In the absence of such a "multi-brand" spec we have tackled this issue
in the past by letting the "brand" be encoded in the client_id. An
alternative scenario is to do a "brand" lookup by client_id. Then let
the AS render the "branded" authZ endpoint.

You're probably aware the mTLS spec is allowing for endpoint aliases, so
this is not the first time such as need has occurred:

https://tools.ietf.org/html/rfc8705#section-5

One could devise a similar JSON object with mappings "label" -
"authorization_endpoint".

Clients that are aware of the new spec will look it up, those that are
not will fall back to the std "authorization_endpoint".

Speaking of mTLS, I'm not sure how the "mtls_endpoint_aliases" can be
sensibly combined with the proposed multi-brand spec.

Vladimir

On 20/05/2020 15:07, Dave Tonge wrote:
> in the OpenID FAPI Working Group that we believe affects the wider
> OAuth community.
>
> In summary: *what is the recommended approach to discovery (RFC8414)
> for Authorization Servers who support multiple "brands" .*
>
> If brands are completely separate, then it seems sensible that each
> brand must have its own `issuer` and therefore its own discovery
> document at the correct location (i.e. brand 1 would have an issuer of
> "https://as/brand1" and a discovery document available at 
> https://as/.well-known/oauth-authorization-server/brand1).
>
> However in the real world it is not always so simple. We have many
> existing implementations in UK open banking that support multiple
> authorization endpoints. Here is an example (thanks to @Joseph Heenan
> <mailto:[email-masked]> )
>
> > They have separate mobile apps for business/personal, and are
> required to support app2app. This means they will definitely be
> exposing multiple authorization endpoints (as there’s a 1:1 mapping of
> authorization endpoints to mobile apps) - the choice is how they do this.
>
> > Their choices are:
>
> > 1. Multiple discovery endpoints (one for business, one for
> personal), each with a different authorization endpoint, multiple
> issuers (if their vendor allows this)
> endpoints listed in one discovery doc (one for business, one for
> personal) some of which are hardcoded by the 3rd party
> Option 1 can be problematic as often it is in reality the same
> `issuer` behind the scenes.
>
> We would like to get feedback on this issue and potentially an
> extension to RFC8414 to allow the definition of multiple authorization
> endpoints.
>
> Thanks in advance
>
> Dave Tonge
> Co-Chair FAPI WG
> Open ID Foundation
>
>

---

From: Joseph Heenan <[email-masked]>
Date: Wed, 20 May 2020 17:16:44 +0100

Thanks for your thoughts Vladimir!

The client_id based solution I wasn’t previously aware of - unfortunately it doesn’t solve the problem for app2app, as the mobile OS selects the app to use based purely on the URL (and in at least the iOS case will not offer the user a choice if multiple apps claim to handle the same url).

I think some kind of mapping like you suggest will work and fallback, I wonder about a structure in the authorization server metadata something like this:

{
  ...
  "alternative_authorization_endpoints": [
    {
      "authorization_endpoint": "https://loadsamoney/business/auth",
      "description": "loadsmoney business banking customers",
      "logo_url": "https://loadsamoney/business/logo.png"
    },
    {
      "authorization_endpoint": "https://loadsamoney/consumer/auth",
      "description": "loadsmoney personal customers",
      "logo_url": "https://loadsamoney/consumer/logo.png"
    }
  ]
}

And as you say, the existing authorization_endpoint can be a fallback for clients that are unaware of the new spec or prefer the simpler option of just using a single authorization endpoint. Supporting the new spec would allow a better UX though so there’s advantages to client to do so.
> Speaking of mTLS, I'm not sure how the "mtls_endpoint_aliases" can be sensibly combined with the proposed multi-brand spec.
> 

I think that particular part is not really an issue as mtls isn’t used at the authorization endpoint.

Thanks

Joseph

> On 20 May 2020, at 16:07, Vladimir Dzhuvinov <[email-masked]> wrote:
> 
> Hi Dave,
> 
> In the absence of such a "multi-brand" spec we have tackled this issue in the past by letting the "brand" be encoded in the client_id. An alternative scenario is to do a "brand" lookup by client_id. Then let the AS render the "branded" authZ endpoint.
> 
> You're probably aware the mTLS spec is allowing for endpoint aliases, so this is not the first time such as need has occurred:
> 
> https://tools.ietf.org/html/rfc8705#section-5 <https://tools.ietf.org/html/rfc8705#section-5>
> One could devise a similar JSON object with mappings "label" - "authorization_endpoint".
> 
> Clients that are aware of the new spec will look it up, those that are not will fall back to the std "authorization_endpoint".
> 
> Speaking of mTLS, I'm not sure how the "mtls_endpoint_aliases" can be sensibly combined with the proposed multi-brand spec.
> 
> 
> 
> Vladimir
> 
> 
> 
>> We have an issue <https://bitbucket.org/openid/fapi/issues/255/certification-clarification-request> in the OpenID FAPI Working Group that we believe affects the wider OAuth community.
>> 
>> In summary: what is the recommended approach to discovery (RFC8414) for Authorization Servers who support multiple "brands" .
>> 
>> If brands are completely separate, then it seems sensible that each brand must have its own `issuer` and therefore its own discovery document at the correct location (i.e. brand 1 would have an issuer of "https://as/brand1 <https://as/brand1>" and a discovery document available at  https://as/.well-known/ <https://as/.well-known/>oauth-authorization-server/brand1).
>> 
>> However in the real world it is not always so simple. We have many existing implementations in UK open banking that support multiple authorization endpoints. Here is an example (thanks to @Joseph Heenan <mailto:[email-masked]> )
>> 
>> > Bank “loadsamoney” has one idp and, for internet banking, one “login page” for both business and personal customers.
>> 
>> > They have separate mobile apps for business/personal, and are required to support app2app. This means they will definitely be exposing multiple authorization endpoints (as there’s a 1:1 mapping of authorization endpoints to mobile apps) - the choice is how they do this.
>> 
>> > Their choices are:
>> 
>> > 1. Multiple discovery endpoints (one for business, one for personal), each with a different authorization endpoint, multiple issuers (if their vendor allows this)
>> > 2. Single discovery endpoint, single issuer, multiple authorization endpoints listed in one discovery doc (one for business, one for personal) some of which are hardcoded by the 3rd party
>> > 3. Multiple discovery endpoints each with a different authorization endpoint, same issuer in all cases (breaks RFC8414 and OIDC Discovery)
>> 
>> Option 1 can be problematic as often it is in reality the same `issuer` behind the scenes.
>> 
>> We would like to get feedback on this issue and potentially an extension to RFC8414 to allow the definition of multiple authorization endpoints.
>> 
>> Thanks in advance
>> 
>> Dave Tonge
>> Co-Chair FAPI WG
>> Open ID Foundation
>> 
>> 
>

---

From: Vladimir Dzhuvinov <[email-masked]>
Date: Fri, 22 May 2020 09:10:16 +0300

A mapping like the one you propose can definitely work. Since the user
will be making the choice which endpoint to take with the client app,
having the logo_uri is a good idea. If the branded endpoints differ
somehow in policy one could also allow inclusion of the op_policy_uri
and op_tos_uri params from Discovery.

https://openid.net/specs/openid-connect-discovery-1_0.html#IssuerDiscovery

Vladimir

On 20/05/2020 19:16, Joseph Heenan wrote:
> The client_id based solution I wasn’t previously aware of -
> unfortunately it doesn’t solve the problem for app2app, as the mobile
> OS selects the app to use based purely on the URL (and in at least the
> iOS case will not offer the user a choice if multiple apps claim to
> handle the same url).
>
> I think some kind of mapping like you suggest will work and fallback,
> I wonder about a structure in the authorization server metadata
> something like this:
>
> {
>   ...
> And as you say, the existing authorization_endpoint can be a fallback
> for clients that are unaware of the new spec or prefer the simpler
> option of just using a single authorization endpoint. Supporting the
> new spec would allow a better UX though so there’s advantages to
> client to do so.
>>
>> On 20 May 2020, at 16:07, Vladimir Dzhuvinov <[email-masked]
>> <mailto:[email-masked]>> wrote:
>>
>> Hi Dave,
>>
>> In the absence of such a "multi-brand" spec we have tackled this
>> issue in the past by letting the "brand" be encoded in the client_id.
>> An alternative scenario is to do a "brand" lookup by client_id. Then
>> let the AS render the "branded" authZ endpoint.
>>
>> You're probably aware the mTLS spec is allowing for endpoint aliases,
>> so this is not the first time such as need has occurred:
>>
>> Clients that are aware of the new spec will look it up, those that
>> are not will fall back to the std "authorization_endpoint".
>>
>>> document at the correct location (i.e. brand 1 would have an issuer
>>> of "https://as/brand1" and a discovery document available at 
>>> authorization endpoints. Here is an example (thanks to @Joseph
>>> Heenan <mailto:[email-masked]> )
>>>
>>> > Bank “loadsamoney” has one idp and, for internet banking, one
>>> “login page” for both business and personal customers.
>>>
>>> exposing multiple authorization endpoints (as there’s a 1:1 mapping
>>> of authorization endpoints to mobile apps) - the choice is how they
>>> do this.
>>>
>>> > Their choices are:
>>>
>>> > 2. Single discovery endpoint, single issuer, multiple
>>> authorization endpoints listed in one discovery doc (one for
>>> business, one for personal) some of which are hardcoded by the 3rd party
>>> > 3. Multiple discovery endpoints each with a different
>>> authorization endpoint, same issuer in all cases (breaks RFC8414 and
>>> OIDC Discovery)
>>>
>>> extension to RFC8414 to allow the definition of multiple
>>> authorization endpoints.
>>>
>>> Thanks in advance
>>>
>>> Dave Tonge
>>> Co-Chair FAPI WG
>>> Open ID Foundation
>>>
>>>
>>
>
-- 
Vladimir Dzhuvinov

---

From: Torsten Lodderstedt <[email-masked]>
Date: Fri, 22 May 2020 08:59:03 +0200

I think an id or label per endpoint set would be needed to determine the set of endpoints to be used by a certain client.

On the conceptual side, I’m asking myself how the complete process is supposed to work. Who is deciding what issuer/endpoint set combination to use. I assume in an open banking scenario, there will always be some kind of bank chooser. Will this chooser provide the client with issuer and brand id? 

> On 22. May 2020, at 08:10, Vladimir Dzhuvinov <[email-masked]> wrote:
> 
> A mapping like the one you propose can definitely work. Since the user will be making the choice which endpoint to take with the client app, having the logo_uri is a good idea. If the branded endpoints differ somehow in policy one could also allow inclusion of the op_policy_uri and op_tos_uri params from Discovery.
> 
>>>> We have an issue in the OpenID FAPI Working Group that we believe affects the wider OAuth community.
>>>> 
>>>> If brands are completely separate, then it seems sensible that each brand must have its own `issuer` and therefore its own discovery document at the correct location (i.e. brand 1 would have an issuer of "https://as/brand1" and a discovery document available at  https://as/.well-known/oauth-authorization-server/brand1).
>>>> 
>>>> However in the real world it is not always so simple. We have many existing implementations in UK open banking that support multiple authorization endpoints. Here is an example (thanks to @Joseph Heenan )
>>>> 
> _______________________________________________
> OAuth mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/oauth

---

From: Vladimir Dzhuvinov <[email-masked]>
Date: Fri, 22 May 2020 10:52:07 +0300

With that said it makes sense to devise a structure which can
accommodate UI driven as well as automatic choice.

  * The UI driven chooser will need a human readable description and
    other UI hints. This can work for instance with "classic" OIDC
    Discovery.

  * The "auto" chooser will need some sort of an ID. For a bank chooser
    this means providing the issuer URI and an optional brand ID and
    both must get registered together. Or, one could define a standard
    brand ID (label) for banking operations and if the
    "alternative_authorization_endpoints" is present look for it in the
    structure, else fall back to the default "authorization_endpoint".

Here is one possible layout which has IDs and UI hints:

{
  ...
  "alternative_authorization_endpoints": {
    "banking": {
    "personal": {

-- 
Vladimir Dzhuvinov

---

From: Joseph Heenan <[email-masked]>
Date: Fri, 22 May 2020 09:32:02 +0100

Thanks Vladimir/Torsten.

I agree, it would make sense to have some form of static id for each entry. My first attempt started out similar but for some reason I decided to simplify…

On the conceptual side for choosers (and biased towards how the UK openbanking ecosystem works as that’s what I know best), what this allows for is:

client chooser -> authorisation endpoint

Where the list is:

“Bank a”
“Loadsamoney personal”
“Loadsamoney business”
“Bank c"

Instead of the only ’standards compliant’ way to do app2app in this case today of:

client chooser -> AS interstitial chooser on authorization endpoint -> real authorization endpoint

Where the first chooser is:

“Bank a”
“Loadsamoney”
“Bank c”

And the second:

“Personal"
“Business"

The first case is much better, particularly for the real multi-brand case where the end user might not even associate the two bank brandnames with each other.

What actually happens today is the first case (single RP chooser), but based on banks emailing around lists of alternative authorization endpoints to the RP, or publishing the details on obscure developer portals - which destroys much of the convenience / agility / security the server metadata RFC was trying achieve.

The issue of how the RP finds the server metadata document is unchanged from today. (In the UK, we have a centralised directory that lists them.)

Joseph

> On 22 May 2020, at 08:52, Vladimir Dzhuvinov <[email-masked]> wrote:
> 
> With that said it makes sense to devise a structure which can accommodate UI driven as well as automatic choice.
> 
> The UI driven chooser will need a human readable description and other UI hints. This can work for instance with "classic" OIDC Discovery.
> 
> The "auto" chooser will need some sort of an ID. For a bank chooser this means providing the issuer URI and an optional brand ID and both must get registered together. Or, one could define a standard brand ID (label) for banking operations and if the "alternative_authorization_endpoints" is present look for it in the structure, else fall back to the default "authorization_endpoint".
>       "authorization_endpoint": "https://loadsamoney/business/auth" <https://loadsamoney/business/auth>,
>       "logo_url": "https://loadsamoney/business/logo.png" <https://loadsamoney/business/logo.png>
>     },
>     "personal": {
>       "authorization_endpoint": "https://loadsamoney/consumer/auth" <https://loadsamoney/consumer/auth>,
>       "logo_url": "https://loadsamoney/consumer/logo.png" <https://loadsamoney/consumer/logo.png>
>     }
>   }
> }
> 
> 
>>> On 22. May 2020, at 08:10, Vladimir Dzhuvinov <[email-masked]> <mailto:[email-masked]> wrote:
>>> 
>>> https://openid.net/specs/openid-connect-discovery-1_0.html#IssuerDiscovery <https://openid.net/specs/openid-connect-discovery-1_0.html#IssuerDiscovery>
>>> 
>>> Vladimir
>>> 
>>>>       "authorization_endpoint": "https://loadsamoney/business/auth" <https://loadsamoney/business/auth>,
>>>>       "logo_url": "https://loadsamoney/business/logo.png" <https://loadsamoney/business/logo.png>
>>>>     },
>>>>     {
>>>>       "authorization_endpoint": "https://loadsamoney/consumer/auth" <https://loadsamoney/consumer/auth>,
>>>>       "logo_url": "https://loadsamoney/consumer/logo.png" <https://loadsamoney/consumer/logo.png>
>>>>     }
>>>>   ]
>>>> }
>>>> 
>>>>> On 20 May 2020, at 16:07, Vladimir Dzhuvinov <[email-masked]> <mailto:[email-masked]> wrote:
>>>>> 
>>>>> Hi Dave,
>>>>> 
>>>>>> If brands are completely separate, then it seems sensible that each brand must have its own `issuer` and therefore its own discovery document at the correct location (i.e. brand 1 would have an issuer of "https://as/brand1" <https://as/brand1> and a discovery document available at  https://as/.well-known/oauth-authorization-server/brand1 <https://as/.well-known/oauth-authorization-server/brand1>).
>>>>>> 
>>> [email-masked] <mailto:[email-masked]>
>>> https://www.ietf.org/mailman/listinfo/oauth <https://www.ietf.org/mailman/listinfo/oauth>
> -- 
> Vladimir Dzhuvinov

---

From: Joseph Heenan <[email-masked]>
Date: Fri, 22 May 2020 09:34:56 +0100

I just realised that “client chooser” in the below is a very ambiguous term.

Please read it to mean “a chooser presented by the client”. (And in the UK today, that chooser is manually populated by the client developer based on the central directory.)

Joseph

> On 22 May 2020, at 09:32, Joseph Heenan <[email-masked]> wrote:
> 
> Thanks Vladimir/Torsten.
> 
>> On 22 May 2020, at 08:52, Vladimir Dzhuvinov <[email-masked] <mailto:[email-masked]>> wrote:
>>

---

From: Torsten Lodderstedt <[email-masked]>
Date: Fri, 22 May 2020 10:38:40 +0200

The first case looks better to me as well. It would require a chooser that provides both the issuer url and the brand id. 

BTW: I would prefer a more generic term in order to facilitate other use cases. I think it could be useful to have a discriminator for selecting a set of endpoints. For example, an AS could then support different versions or flavours of OAuth/OpenID in the same deployment. Just thinking aloud :-)

> On 22. May 2020, at 10:32, Joseph Heenan <[email-masked]> wrote:
> 
> Thanks Vladimir/Torsten.
> 
>> 	• The UI driven chooser will need a human readable description and other UI hints. This can work for instance with "classic" OIDC Discovery.
>> 
>> 	• The "auto" chooser will need some sort of an ID. For a bank chooser this means providing the issuer URI and an optional brand ID and both must get registered together. Or, one could define a standard brand ID (label) for banking operations and if the "alternative_authorization_endpoints" is present look for it in the structure, else fall back to the default "authorization_endpoint".
>>       "authorization_endpoint": 
>> "https://loadsamoney/business/auth"
>> ,
>>       "authorization_endpoint": 
>> "https://loadsamoney/consumer/auth"
>> ,
>>>>>       "authorization_endpoint": 
>>>>> "https://loadsamoney/business/auth"
>>>>> ,
>>>>>       "authorization_endpoint": 
>>>>> "https://loadsamoney/consumer/auth"
>>>>> ,
>>>>>>> If brands are completely separate, then it seems sensible that each brand must have its own `issuer` and therefore its own discovery document at the correct location (i.e. brand 1 would have an issuer of 
>>>>>>> "https://as/brand1" and a discovery document available at  https://as/.well-known/oauth-authorization-server/brand1
>>>>>>> ).
>>>>>>>