auth: improve TokenHandling

[arcuri82]

No description provided.

[arcuri82]

hi @en-milie @Stranger6667 ,

I added some fields to the TokenHandling declaration.
You can check if you agree or not with this, or if you want to suggest changes.

[Stranger6667]

Looks good to me!

[ludovicianul]

To be honest I'll make this a bit more generic and easier to extend for the future. Something like:

TokenHandling:
  type: object
  properties:
    extractFrom:
      type: string
      enum: ["body", "header"]
    extractPath:
      type: string
      description: "JSON Pointer for body extraction, or header name for header extraction"
    sendIn:
      type: string
      enum: ["header", "query", "cookie"]
    sendName:
      type: string
      description: "Header/query/cookie name where token should be sent"
    sendFormat:
      type: string
      description: "Template with {token} placeholder. Default: '{token}'"
      default: "{token}"
  required: ["extractFrom", "extractPath", "sendIn", "sendName"]

[arcuri82]

hi @ludovicianul ,

thanks for your input. Let me discuss it point by point:

extractFrom:
   type: string
   enum: ["body", "header"]

that's good

extractPath:
   type: string
   description: "JSON Pointer for body extraction, or header name for header extraction" 

having same field for body and header handling is fine, but I do not particularly like the name Path, as it makes sense for body but not much for a header name. But not sure what would be a good alternative. extractKey? selector? any other idea?

   sendIn:
       type: string
       enum: ["header", "query", "cookie"]

good for header and query. but not sure about cookie. Right now cookies are handled outside TokenHandling in the field expectCookies:

      expectCookies:
           description: "Specify if we are expecting to get cookies from the login endpoint. \
                                  If so, a fuzzer can use those as auth info in following requests, instead of trying to extract \
                                  an auth token from the response payload."

the idea was that, if you expect a cookie, you can just use a boolean to say send back all cookies received when doing authenticated calls. or are the cases in which this would be too limited?

 sendFormat:
          type: string
          description: "Template with {token} placeholder. Default: '{token}'"
          default: "{token}"

yep, that's a good idea, and likely easier to handle than separated suffix and prefix.

@Stranger6667 what do you think?

[ludovicianul]

Yes, apologies, I've missed the expectCookies field. So sendIn it's just query and header.
extractSelector sounds better than extractPath. :)

[arcuri82]

@ludovicianul @Stranger6667
how does this new version look like?

  TokenHandling:
    description: "Specify how to extract the token from the HTTP response, and how to use it for auth in following requests. \
                  Not needed if rather expect to get back a cookie."
    type: object
    properties:
      extractFrom:
        description: "Specify from where the token should be extracted in the HTTP response."
        type: string
        enum: ["body", "header"]
      extractSelector:
        description: "How to extract the token from the HTTP response. \
                      This depends on where the token is located. \ 
                      For a 'body' location, the returned body payload like a JSON could have few fields, possibly nested. \ 
                      In this case, this selector is expressed as a JSON Pointer (RFC 6901). \
                      For a 'header' location, this selector would represent the name of the HTTP header (e.g., 'X-Auth-Token')."
        type: string
      sendIn:
        description: "The obtained auth token could be send for authentication in following requests in different ways. \
                      For example, in a HTTP header (e.g., 'Authorization') or a query parameter."
        type: string
        enum: ["header", "query"]
      sendName:
        description: "Header or query name where the token should be put in the authenticated requests. \
                      Typically, for a header, this would be 'Authorization'."
        type: string
        examples:
          - "Authorization"
      sendFormat:
        description: "Template with {token} placeholder. \ 
                      The placeholder will be interpolated with the actual token value.  \
                      When sending out the obtained token in an HTTP request, specify if there should be any other \
                      text information around it. \    
                      For example, when sending the token in an 'Authorization' header, possible \
                      values could be 'Bearer {token}' and 'JWT {token}'."
        type: string
        default: "{token}"
        examples:
          - "Bearer {token}"
          - "JWT {token}"
    required: ["extractFrom", "extractSelector", "sendIn", "sendName"]

[ludovicianul]

Looks good!

[Stranger6667]

Minor bikeshedding with the property name, but otherwise it is a really nice improvement :)

[Stranger6667]

nit: sendTemplate maybe? as it is described as a template below.

[arcuri82]

@Stranger6667 good point. i updated it

[arcuri82]

@Stranger6667 @ludovicianul
thanks for your feedback. this branch is now merged.

recall that, while going through the specs, feel free to suggests improvements/changes. we can then discuss them