Open APIs

 View Only

  • 1.  /hub and Security

    TM Forum Member
    Posted Sep 11, 2023 12:25

    Hi all,

    I would like to know if there are internals discussions around the security of the /hub callback url. Today this URL must be accessible and public on the web. I haven't seen any mechanics that would secure these webhooks. Is there any consideration for implementing an hmac or any advice in Guidelines? (HMAC - Wikipédia)

    Thanks in advance

    Denis



    ------------------------------
    denis leclercq
    Orange
    ------------------------------


  • 2.  RE: /hub and Security

    TM Forum Member
    Posted Sep 12, 2023 04:36

    Hi Denis,

    A good point that we also stumbled upon (even if it was about the TMF688 API).

    We added an Array of SecurityCredentials to the Hub component schema and introduced a new AuthMethodHeader component.

    AuthMethodHeader is used to specify a request header value needed to authenticate to the callback URL (aka. API key). The idea was that we would establish other components as needed, for example AuthMethodBasicAuth.

    Here is an example from the OAS YAML.

    schemas:
  AuthMethodHeader:
      description: Object to specify a Request Header based authentication/authorization method.
      type: object
      required:
        - headerName
        - headerValue
      properties:
        headerName:
          type: string
          description: The name of the request header
          example: "x-api-key"
        headerValue:
          type: string
          format: password
          writeOnly: true
          description: The value for the request header
          example: "04e9cc79ad2e4756ae96a11d75cb8a06"
  Hub_Create:
      description: A Hub is used to subscribe to an event notification
      required:
        - callback
      allOf:
        - "$ref": "#/components/schemas/Extensible"
        - type: object
          properties:
            callback:
              type: string
              format: uri
              description: The URI that will be POSTed to when a notification is triggered
              example: "https://eventconsumer.example.com/ad0e09ca"
            securityCredential:
              type: array
              items:
                oneOf:
                  - $ref: "#/components/schemas/AuthMethodHeader"

    At least that's what we came up with. Of course, when implementing the API, you have to make sure that these credentials are secured and cannot be queried by anyone.

    Would certainly be nice if one could make an extension of the TMF OpenAPI here.

    Regards,
    Jan



    ------------------------------
    Jan Lemmermann
    OSS Lead Architect
    EWE TEL GmbH
    ------------------------------

    Original Message


  • 3.  RE: /hub and Security

    TM Forum Member
    Posted Sep 13, 2023 02:11

    Hi,

    In the ODA Canvas & Component workgroup we are working towards a solution that is based on Oauth 2.0. This model allows centralised administration of the security using an authorisation server (keycloak, Azure Active Directory, ...)

    For the mentioned scenario this would be based on the "client credential" flow. This flow supports secure communication between 2 applications without user interaction. The token (JWT) is simply added in the Authorization: header.

    The model using authorisation server avoids the (potentially insecure) exchange of keys between 2 applications. The solution from workgroup is still work in progress.



    ------------------------------
    Koen Peeters
    OryxGateway FZ LLC
    ------------------------------

    Original Message


  • 4.  RE: /hub and Security

    TM Forum Member
    Posted Sep 13, 2023 05:24

    Koen your reference to OAuth2 is interesting. I have the impression that two aspects need to be clarified.

    1. which technical methods should be used to secure a hub callback URL of the recipient? (no auth? BasicAuth, OAuth2 client credential flow, API keys etc.).
    2. when creating a hub, how does the "subscriber" inform the provider of the system of the necessary procedure and the associated credentials that the provider must take into account during HTTP POST against the callback URL?

    /Jan



    ------------------------------
    Jan Lemmermann
    OSS Lead Architect
    EWE TEL GmbH
    ------------------------------

    Original Message


  • 5.  RE: /hub and Security

    TM Forum Member
    Posted Sep 13, 2023 05:06

    Denis

    Very interesting question that stimulated a lot of discussion amongst some of the ODA Security and privacy team members. The team meets Wednesday and at 13:00 CET . today 13th might be rather short notice for you . Next week is DTW so we will not meet next week  but we could schedule for the 27th Sept .  Iam planning to suggest on today's ODA Sec call that we post on  an ODA security a working page on some ideas that we exchanged, Note first step is to assess the threats and risks then establish some patterns and mechanism  for addressing those threats and your proposal on HMAC stimulated a lot of discussion  



    ------------------------------
    Dave Milham
    TM Forum, Chief Architect
    ------------------------------

    Original Message


  • 6.  RE: /hub and Security

    TM Forum Member
    Posted Sep 13, 2023 08:34
    Edited by denis leclercq Sep 13, 2023 08:35

    Hi,

    The question of securing a webhook is indeed interesting.
    A client can subscribe to the /hub by consuming the Open API, logically through an API Management system, via an SSL authenticated flow. (most of the time we don't consume API on the client network)

    1. As Jan mentions, how does the "subscriber" inform the provider of the system of the procedure and the associated credentials that the provider must take into account during HTTP POST against the callback URL? Using HMAC would reverse control, and it is the provider who would provide a secret upon subscription

    2. How do we maintain flexibility when using webhook? To make an analogy, when you subscribe to a "newsletter" the issuer does not manage an authentication provisioning process with each of the receivers. Using HMAC, the provider would give the subscriber the opportunity to verify the authenticity of the message

    An interesting link on the subject:
    https://hookdeck.com/webhooks/guides/webhooks-security-checklist#security-threats-and-solution-recap

    Denis



    ------------------------------
    denis leclercq
    Orange
    ------------------------------

    Original Message


  • 7.  RE: /hub and Security

    TM Forum Member
    Posted Sep 19, 2023 10:14

    Another question, what is TMForum's position on using standards like CLoudEvents to manage webhooks rather than reinventing a new mechanism ?

    Thx

    Denis



    ------------------------------
    denis leclercq
    Orange
    ------------------------------

    Original Message


  • 8.  RE: /hub and Security

    TM Forum Member
    Posted Sep 19, 2023 16:20

    Hi,

    I am definitely not representing the official TM Forum view, the TM Forum hub mechanism seems to be much older than the founding date of Cloudevents project and the cloudevents subscription API isn't even published yet. The cloudsevents spec doesn't include any section regarding security. In that respect "reinventing a new mechanisme" when comparing with a incubator solution that is  is an exageration.

    Regards



    ------------------------------
    Koen Peeters
    OryxGateway FZ LLC
    ------------------------------

    Original Message


  • 9.  RE: /hub and Security

    TM Forum Member
    Posted Sep 20, 2023 04:21
    Edited by denis leclercq Sep 20, 2023 05:37

    No offence intended, it was just a question on a position. Each open source project is a source of inspiration, not a war of war. I have always admired the work of TMForum and the relevance of functional models

    https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/http-webhook.md#3-authorization

    We implemented the hub exactly as defined in the TMForum and currently we note that the mechanics are not yet satisfactory in terms of subscription and client security constraints. When you use https://webhook.site/ for test everything is fluid, but in reality  any hub creation requires a manual process and customer-specific configuration

    My goal is only to find an interesting, satisfactory and realistic solution

    Regards

    Denis



    ------------------------------
    denis leclercq
    Orange
    ------------------------------

    Original Message


  • 10.  RE: /hub and Security

    TM Forum Member
    Posted Sep 21, 2023 01:46

    Hi Denis,

    We have created an automated mechanism for creating hubs in an ODA canvas as part of the AsyncAPI catalyst. This will be contributed to the ODA-CA implementation in the next weeks. Security wise ODA is also including OAuth and OpenIDConnect (non-TMF standards) as part of the Canvas Specification. IG1330 provides the first details for this approach and ODA-CA reference implementation should follow this year as well. if you are interested to move this work faster you are invited to join the ODA-CA team.

    Regards



    ------------------------------
    Koen Peeters
    OryxGateway FZ LLC
    ------------------------------

    Original Message