OpenAPI-Specification
OpenAPI-Specification copied to clipboard
OAI
Multiple 'Set-Cookie' headers in one response
Is it possible to have multiple 'Set-Cookie' headers in one response? As is known there are two ways to set cookies header in the response: - Having separated headers - Folding into 1 header and using comma separated
The later way however is deprecated in (RFC6265)[http://www.rfc-editor.org/rfc/rfc6265.txt] and not supported by some latest browsers.
Origin servers SHOULD NOT fold multiple Set-Cookie header fields into
a single header field. The usual mechanism for folding HTTP headers
fields (i.e., as defined in [RFC2616]) might change the semantics of
the Set-Cookie header field because the %x2C (",") character is used
by Set-Cookie in a way that conflicts with such folding.
So that below can be valid:
responses:
200:
description: "Response with content"
headers:
Set-Cookie:
type: String
description: "eg. key1=value1"
Set-Cookie:
type: String
description: "eg. key2=value2"
You can of course have multiple headers with the same name in your HTTP response, but it looks like OpenAPI 2.0 has no way of documenting that. The way shown by you doesn't work (a JSON or YAML object can have each key just once, and if you repeat one, most parsers will retain just one of them).
I think it looks like the same with the current RC of OpenAPI 3.0 – while the handling of plural parameters changed (via style instead of collectionFormat), I didn't find anything for "multiple headers of the same name". (I guess that could be handled by adding a new style value here.)
(By the way, I think that Cookies should not be necessary in a Restful API – but the same applies to other headers too.)
Per @darrelmiller - We have a way to capture this in the request but not in the response.
@JohnnyNiu Is that sufficient for your use case?
@RobDolinMS Also, you can't have multiple cookie headers in the request. As per RFC 6265 S5.4:
When the user agent generates an HTTP request, the user agent MUST NOT attach more than one Cookie header field.
I got rid of this problem with this one simple trick:
just surround the next same header by quotation marks and add null char at the beginning.
headers:
Set-Cookie:
description: Session cookie
schema:
type: string
example: SESSIONID=abcde12345; Path=/
"\0Set-Cookie":
description: CSRF token
schema:
type: string
example: CSRFTOKEN=fghijk678910; Path=/; HttpOnly
result:
I'm interested in this issue for the purpose of using the Link header for web linking. There's an example in the RFC that shows multiple links being serialized either in a single Link header or multiple headers. It seems like it would be simpler to parse the links if they were in separate headers.
I found this issue when looking for a way to represent the ability to have multiple occurrences of the same header. In my case, the number of occurrences is unknown, and so using an array seemed ideal. It almost works, except that explode: true doesn't appear to be working,
My-Header-Example:
name: My-Header-Example
in: header
description: "Useful description goes here"
schema:
type: array
items:
type: string
explode: true
I was expecting it to generate multiple header entries like this,
-H "My-Header-Example: headerItem1" -H "My-Header-Example: headerItem2" ...
But instead ends up with a comma-delimited list within a single field,
-H "My-Header-Example: headerItem1,headerItem2" ...
Would it be possible to fix so that explode: true is honored for header? That might be one way of addressing concerns that others have raised, although they would need to comment on that themselves because you would end up with just a single description field for all of the entries, which in my case is exactly what I want, but might or might not be adequate in the other scenarios documented here.
@njr-11 How this headers are actually rendered is a function of the tool you are using, not the specification. I would suggest bringing this up with whatever tooling you are using. On the other hand, for HTTP headers that allow duplicate headers, the two forms you show are considered semantically equivalent. See https://tools.ietf.org/html/rfc7230#section-3.2.2
@RobDolinMS Also, you can't have multiple
cookieheaders in the request. As per RFC 6265 S5.4:When the user agent generates an HTTP request, the user agent MUST NOT attach more than one Cookie header field.
You definitively can, that is how the entire internet is built up. S5.1 specifies the user is sending the Set-Cookie header. Look in S3.1, there is a clear example of this being allowed if the server is sending it:
I got rid of this problem with this one simple trick:
just surround the next same header by quotation marks and add null char at the beginning.
headers: Set-Cookie: description: Session cookie schema: type: string example: SESSIONID=abcde12345; Path=/ "\0Set-Cookie": description: CSRF token schema: type: string example: CSRFTOKEN=fghijk678910; Path=/; HttpOnlyresult:
Is there really no other way of doing this?...
@RobDolinMS Also, you can't have multiple
cookieheaders in the request. As per RFC 6265 S5.4:When the user agent generates an HTTP request, the user agent MUST NOT attach more than one Cookie header field.
You definitively can, that is how the entire internet is built up. S5.1 specifies the user is sending the Set-Cookie header. Look in S3.1, there is a clear example of this being allowed if the server is sending it:
It seems what RobDolinMS means is that cookie header cannot be attached more than once while set-cookie header can according to the specification you give.
It appears it is supported (see the use of type: array above), although the implementation you are using may be doing it wrong.
Ah gotcha. I had tried allOf whic didn't work. I'll report back after I try that, thank you.
@karenetheridge The Set-Cookie response header is not well represented by type: array because each time the header is repeated it uses a different cookie name, and those names are part of the interface being documented.
Unfortunately Set-Cookie is an exception to the rule of HTTP headers https://www.rfc-editor.org/rfc/rfc9110.html#section-5.3
I wonder if we could use a schema of type object to describe the returned cookie pairs. e.g.
responses:
200:
description: ok
headers:
Set-Cookie:
schema:
type: object
properties
foo:
type: string
bar:
type: string
This doesn't help terribly if you want to be able to describe the cookie attributes. Maybe this is a case for trying to invent an extension.
responses:
200:
description: ok
headers:
Set-Cookie:
x-cookies-defn:
- name: bar
path: /
domain: example.com
- name: foo
path: /
domain: example.com
So how to respond with accessToken + csrfToken + refreshToken in one response?
Something like this? I may be missing something completely. I have never used an API that uses Set-Cookie, so I have no experience with it. Do you have any insight on why people build APIs that rely on Set-Cookie?
responses:
200:
description: ok
headers:
Set-Cookie:
x-cookies-defn:
- name: accessToken
path: /
domain: example.com
- name: csrfToken
path: /
domain: example.com
- name: refreshToken
path: /
domain: example.com
Something like this? I may be missing something completely. I have never used an API that uses Set-Cookie, so I have no experience with it. Do you have any insight on why people build APIs that rely on Set-Cookie?
responses: 200: description: ok headers: Set-Cookie: x-cookies-defn: - name: accessToken path: / domain: example.com - name: csrfToken path: / domain: example.com - name: refreshToken path: / domain: example.com
Cookies are set to store credentials, especially since they support HttpOnly flag that prevents from JS to access its contents. This is in order to mitigate XSS.
@darrelmiller It's not so much that I want to build an API that relies on cookies, so much as I want to document an API that already does, or has to, use cookies. In particular, cookies are useful for session management, especially since as @razb-viola mentioned, they can be hidden from client-side (JavaScript) code entirely. Obviously, the kind of APIs we're talking about are primarily browser-facing, though they can be server-to-server as well.
~~Also, @razb-viola, you should not be using a cookie for your (anti-)CSRF token. The whole purpose of the token is to indicate that the browser initiated the request from a legitimate origin. Since cookies are sent by the browser to the server based upon the destination and not the origin, they are useless at preventing cross-site request forgery. The CSRF token can be sent back to the server in just about any other way, though (query parameter, header, inline form parameter, etc.).~~
@kbolino The CSRF token will be stored in a cookie - without HttpOnly flag - and then be sent in the header after read from JS. The HttpOnly flag is only for the accessToken itself (and refresh token). While reading it explicitly from the cookie using JS ensures no one trying to forge this request from an email or something.
@razb-viola As long as the CSRF token is externally verifiable (e.g. by the server's state) then it shouldn't be a problem; you should still not trust cookie value == header value alone due to the risk of subdomains being able to overwrite parent domain cookies. It's probably better to return the CSRF token outside of cookies, since it can be misleading (as I was misled) even if done properly.
I check in my server using hmac crypto mechanism - the user provides his CSRF token in the headers (after reading from the cookie explicitly), then the server takes the actual accessToken and run hmac on it, the result should be equal to the user provided CSRF token in the header.
Would it make sense to add
cookiesto the OASresponseobject?
Why not? (Response headers to be precise*)
Would it make sense to add
cookiesto the OASresponseobject?Why not? (Response headers to be precise*)
Not response headers, response object :)
Set-Cookie header is a special case and could use a separate object in OpenAPI document, just like request cookies have. It would solve problems reported earlier in this discussion.