certification clarification request: location of discovery document

Issue #255 resolved
Joseph Heenan created an issue

The FAPI conformance suite currently has a test that checks the following clause from https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderConfig :

OpenID Providers supporting Discovery MUST make a JSON document available at the path formed by concatenating the string /.well-known/openid-configuration to the Issuer.

The check retrieves the discovery document, gets the issuer, then checks if url the discovery document came from is ISSUER/.well-known/openid-configuration

The reason for adding this check was that previous discussions on the FAPI WG had revealed that this spec clause was a protection against phishing attacks where the client developer could be fooled into using an incorrect discovery doc which would then (for example) allow man-in-the-middle attacks by changing the token endpoint to an attacker-controlled one.

This check seems to be causing issues within the UK OpenBanking ecosystem. Banks are frequently defining multiple discovery endpoints, all of which ultimately point at one authorization server that has a single issuer.

For example:





all have the issuer value https://auth.obapi.bankofireland.com and hence fail the check. Other banks (e.g. Barclays) appear to have similar setups.

The reason banks are doing this is I believe primarily because they have different brands on the same backend systems, and hence want to show the correct branding to the user for the brand the user is trying to log in to - the problem becomes particularly acute with app2app, where there are different apps for each brand and hence the Authorization Endpoint url must be unique for each brand so that the correct app is launched (as each url must be claimed by no more than one app so the mobile OS knows which app to launch).

I am not sure if the check is an overreach (the above spec clause doesn’t appear to rule out that other discovery documents are made available at different paths); but it that was the case then there’s no protection against the potential phishing attacks.

Clarification on how the FAPI WG views this situation would be greatly appreciated.

Comments (28)

  1. Joseph Heenan reporter

    Other relevant notes:

    1. I don’t believe the OIDCC python certification tests check this clause
    2. It seems many clients don’t perform this check and hence are open to the attack (it may we need a clause in FAPI part 1 and/or part 2 and/or FAPI-CIBA requiring clients to do the check to make it more prominent)
  2. Joseph Heenan reporter

    Discussed briefly on the 24th July 2019 WG call. Hopefully WG members will provide more detailed thoughts on this ticket in due course, but to very quickly summarise:

    Ralph: This was also an issue in the OB directory. Most vendors now support mechanisms for a single server to have multiple issuers, which is the correct way to do this.

    Torsten: reiterated that this is an important security feature.

    (Apologies if I have mis-quoted anyone, please feel free to correct me.)

  3. Tom Jones

    I have been working with the us health care system where they addressed the problem with a distinction made between a capability statement and an endpoint statement. The difficulty here is that iss is not defined in legal terms, but only as an actor at an endpoint. This will need a more robust solution than is currently available in openID. One discussion in another group is adding the concept of legal entity which is needed in any case for compliance reporting. It is past time for overloading the meaning of iss, the other fields need to be included now.

  4. Joseph Heenan reporter

    This check seems to consistently be an issue for UK banks.

    I think at least in the banking cases we’re considering (where there is a dedicated AS that does not host any user generated content or anything even close to that) there’s no security issue with weakening the requirement so that the discovery document and issuer just have to have the same scheme and hostname/port number.

    @Torsten Lodderstedt I believe it was you that previously commented about this being an important security feature, how would you feel about weakening it to same host rather than the very strict matching including the url path currently required?

  5. Torsten Lodderstedt

    It’s a security. The rationale is given in https://openid.net/specs/openid-connect-discovery-1_0.html#Impersonation.

    It basically prevents an attacker from impersonating an OP. DNS and HTTPS are the underpinnings of the rest of the OpenID Connect security model. If a RP does not enforce the strict binding between the iss in the ID token and the openid-configuration, an attacker can for example plant its JWK URI meaning the attacker can make up signed ID tokens.

    Banks with several brands should use separate Issuer URLs per brand. This also makes a lot of sense since the brand is most likely the namespace for user accounts (and sub values).

  6. Joseph Heenan reporter

    Thanks Torsten! I had not previously noticed that MUST clause.

    It appears not many RPs implement that check, or that anyone in the OB ecosystem has disabled the check without raising it as a non-compliance. (I suspect the former.)

    The problem is that using separate issuers is a massive change to make if you only become aware of the need after you’ve got a live system that is in active use by many RPs, which is the situation for most of the banks.

  7. Torsten Lodderstedt

    What shall I say. They have broken OIDC security.

    I think the underlying problem is they potentially use a single OP (instance) to serve multiple user bases. They should have used a multi-tenancy instead.

  8. Joseph Heenan reporter

    Discussed on the 16th October WG bug call.

    There seemed to be consensus to add a spec clause requiring that clients perform the check that the issuer and discovery document location are consistent, as (although it seems to be an existing requirement in the underlying OpenID discovery spec to check this) it seems the majority of clients do not.

  9. Dave Tonge

    We discussed this again and I said I’d leave a comment about the potential user benefits of having a single issuer with multiple authorization endpoints.

    In the case of multiple brands this allows the choice of which brand , to take place at either the Client or the AS, e.g.

    At a TPP I could choose Barclays Business (Brand) and get taken straight to Barclays Business login page / app


    At the TPP I could choose Barclays (ASPSP) and get taken to a page at Barclays where I could choose whether I wanted to connect my Business account or my personal account.

    The second behaviour can’t work in conjunction with the first behaviour if there are different issuers.

    Personally I think that an addition to the Discovery spec that allows a server to specify multiple auth urls would be useful.

    I think there is already some discussion about allowing multiple token endpoints (for MTLS).

    Obviously that would need to go through the right analysis.

  10. Torsten Lodderstedt

    thanks Dave.

    I would like to conduct a litmus test (I hope my dictionary gave me the right translation :-)).

    The issuer URL plays an important role when distinguishing IDPs/user realms, since it functions as namespace of the sub claims (user ids). If we would be talking about an OpenID Connect setup for identity federation, what would be the granularity for assigning issuers (IDPs). The ASPSP or the brands?

  11. Dave Tonge

    Hi Torsten, yep its a good phrase 🙂

    So the way it currently works is that is the ASPSP that has the single issuer.

    So no matter which brand I connect to, any ID Tokens I get back have the issuer of the ASPSP not the brand.

  12. Torsten Lodderstedt

    Hi Dave,

    that’s the current situation. I’m trying to find out what the best setup would be.

    If you use the ASPSP authz endpoint, do you need to select the brand? Or are the user names/ids unique across all the brands and the mapping happens automatically?

  13. Dave Tonge

    I don’t think usernames are unique across all brands. Or more likely the auth factors required are different for each brand. e.g personal may require “customer id” but business may require “business username”.

    We also have the following example of Newday (a white label credit card provider):

    I think in that case the issuer should clearly be different - as there is no “ASPSP” authz endpoint, and they’ve already implemented separate token endpoints for each brand. The above examples all share the same resource server (https://api.newdaycards.com/open-banking/), but that is fine - the RS can accept tokens from different issuers.

    As a TPP I suppose I would actually prefer your suggestion of completely separate issuers for each brand, as this gives me as a TPP more control over the user experience of selecting which Brand/ASPSP to connect to.

    Unfortunately the current situation is I think the result of ASPSPs going live with a single discovery doc and now struggling to migrate to a situation where they support multiple.

    I will raise it as an issue.

  14. Joseph Heenan reporter

    I think there is already some discussion about allowing multiple token endpoints (for MTLS).

    I think this is actually relatively final, mtls_endpoint_aliases as per https://tools.ietf.org/html/draft-ietf-oauth-mtls-13#section-5

    As a TPP I suppose I would actually prefer your suggestion of completely separate issuers for each brand, as this gives me as a TPP more control over the user experience of selecting which Brand/ASPSP to connect to.

    I think app2app would tend to agree, pretty much the only way I can see to avoid it become app2web2app (where the middle ‘web’ is a ASPSP page to select the correct brand / customer segment) is to have one issuer per mobile app.

    Some banks currently requires TPPs to manually override the Authorization Endpoint when using app2app, which seems undesirable as it makes it susceptible to the phishing/developer error type attack that correct use of discovery could otherwise protect against.

  15. Dave Tonge

    We discussed on the call today and there was agreement on the following:

    • Discovery docs should/shall be used
    • There must be a separate issuer per brand - the same issuer should not be used across multiple openid-configs (this is already a requirement of the discovery specs but may need to be emphasised)
    • Metadata such as authorization_endpoints must only be retrieved from discovery docs and not changed based on emails / other communication

    There was some discussion that having multiple auth endpoints on a discovery doc wouldn’t be that bad from a security perspective, however I’m not sure if there is enough of a need to define a spec for it, and its questionable if FAPI would be the right place to define that extra metadata.

  16. Tom Jones

    Your still on bit-bucket? Is that going to be discontinued next month?

    I am sorry to hear that you have one issuer per brand. The approach AFAICT in TXAuth is to separate the redirect from the identity. Is that the only reason your a mandating this? If so i think you should just break that dependency now, rather than later.

  17. Dave Tonge

    Hi Tom

    We use git, I think its only mercurial that Bitbucket is discontinuing.

    At the moment our main concern is ensuring the link between issuer and discovery docs. Adding extra auth urls in the future isn’t out of the question but probably shouldn’t take place in this WG

  18. Torsten Lodderstedt

    I wouldn’t say multiple authorization endpoints is a terrible idea. The question is how does a client/RP determine the endpoint to be used in a certain transaction.

    Any idea?

  19. Joseph Heenan reporter

    The question is how does a client/RP determine the endpoint to be used in a certain transaction.

    They could be marked with freeform text, or possibly even some kind of rich text or image - the selection would essentially be upto the user.

    It’s maybe helpful to make a very simple example:

    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 [The case some banks are currently doing and failing certification tests]

    The “how does a client/RP determine the <thing> to be used in a certain transaction” problem happens in all 3 scenarios, and to some extent goes back to “how does a client/RP get the discovery endpoint in the first place”. Arguably ‘2' is better for security/etc as there is a single discovery endpoint per organisation that’s a single source of truth.

  20. Tom Jones

    Great, the discussion is getting to the root of the problem which I would characterize as a binding between the digital world and the real world. For commercial activity of any sort whatsoever the individual user needs some method to make a trust decision, typically based on branding. Eventually that brand needs to be backed by a legal entity. My assertion is that this dichotomy between brand and legal entity needs to be captured. I was hoping to merge the discovery document with the entity statement from the federation spec. I will be doing that with in healthcare and would appreciate some guidance from financial as the problems seem to be the same.

  21. Joseph Heenan reporter

    Here’s the latest suggestion as to how the discovery document could look to cover this:

      “issuer”: “https://somebank.example.com/“,
      “authorization_endpoint” : "https://somebank.example.com/auth”,
      "alternative_authorization_endpoints": {
        “business": {
          "authorization_endpoint":  "https://somebank.example.com/auth/business",
          "description": “somebank business banking customers",
          "logo_uri": "https://somebank.example.com/auth/business/logo.png"
        "personal": {
          "authorization_endpoint": "https://somebank.example.com/auth/consumer",
          "description": “somebank personal customers",
          "logo_uri": "https://somebank.example.com/auth/consumer/logo.png"

    We’re awaiting feedback from OB / UK banks or TPPs to see if there’s interest in moving this proposal forward.

  22. Joseph Heenan reporter

    Freddi is raising this at OpenBanking UK TDA today, as a “here’s the OIDC/FAPI spec as it stands today, CMA9 need to conform” (i.e. without the extension outlined above). So we’ll see if we get any pushback from that.

  23. Log in to comment