Allow session cookie auth

[ajtowns]

Session cookies are one method of authentication available in Jira. See: https://docs.atlassian.com/jira/REST/6.2/#d2e4887

The process is that you visit a URL authenticating via some other method, and the response includes cookies that serve as your authentication for ongoing access.

A new Authorization Object type in 5.1.5 of "cookie" or "session-key" could work here, with "keyname" being required and specifying the cookie id used, and "login-url" giving a pointer to the API endpoint that needs to be accessed to set the cookie?

[andrekosak]

if would be nice to have such new feature

[mission-liao]

I just found a new CookieAuthorization obj in swaggerjs. I also wonder when will this new feature get into spec.

[JamesMessinger]

+1

It seems like it would be fairly easy... the Security Scheme Object already has an apiKey type, but the only supported locations are query and header. Seems like we just need to add cookie as another location type.

What do you think, @webron and @mohsen1?

btw... this issue is similar to another open issue.

[webron]

@BigstickCarpet - similar but not identical as one is for security and another is for parameters (while can be similar in implementation, they serve a different role).

As for the proper implementation, I'm not entirely sure how this would look like.

[retrospectacus]

Putting your cookie in the header can be done by giving your securityDefinition name "Cookie" and its actual name goes in the data. It does not yet fully work (see issue 305) and of course you must obtain the cookie elsewhere...so +1

[JamesMessinger]

@retrospectacus - The problem with {type: "apiKey", in: "header", name: "cookie"} is that there's no way to specify which cookie is the API key. The Cookie HTTP header can contain many cookies, and a typical HTTP request will include cookies for all sorts of things - ad trackers, Google analytics, session cookies, etc. So it's not sufficient to say that my API requires any cookie. I need to be able to say that I require a specific cookie. Like this: {type: "apiKey", in: "cookie", name: "myAuthCookie"}

[retrospectacus]

@BigstickCarpet I completely agree - my described method is (will be?) a very poor workaround until in:cookie is implemented.

[JamesMessinger]

Ah, ok. Then we're in agreement. I'm using the same workaround right now in all my Swagger APIs.

[cemo]

+1

[earth2marsh]

While I think this is an excellent candidate for Swagger.Next consideration, I am going to argue the other side here…

Cookies may be widely used on web applications, but they aren't a good fit for modern APIs (see references below). Swagger has taken a position on API design vis-a-vis its constraints around operation signatures, which means it already has a precedent of not aspiring to describe all possible APIs. This simplifies the tooling, and helps keep Swagger nimble. Perhaps excluding cookies should be part of Swagger's general opinion on API design?

On the pros' side, it's generally a good thing for Swagger to be a more descriptive format.

On the cons' side, supporting cookies in the spec also implies supporting cookies in the tooling, including SDK generation and Swagger-UI, etc, not to mention the documentation and example overhead. That baggage slows down future development.

References:

• Fielding's REST dissertation's section on cookies
• Should cookies be used in a restful API?
• Auth0's post on Cookies vs Tokens

[jiridanek]

My usecase: document the semipublic API of Duolingo.com with Swagger

Duolingo uses cookies to authenticate users. Some calls require authentication, otherwise they fail. At the bare minimum in my API I need to be able to say say "this method can be called only if the user is authenticated". and in the generated bindings I need to be able to keep a cookie-jar that would hold cookies set by previous requests. I don't really care what cookies are being set. What I might care about is when the cookies expire, so I can renew my session.

Currently I am giving all methods that needs authentication a tag "authed". I haven't yet looked into how generated bindings handle cookies. (I am not using generated bindings). By and large this works OK for me.

[304NotModified]

+1

[rafaelcaricio]

+1

[Santinell]

+1

[0x62ash]

+1

[andrewzk]

+1

[jiridanek]

See also swagger-api/swagger-ui#461

[webron]

Parent issue: #585

[jharmn]

For posterity, a better example of how this works https://developer.atlassian.com/jiradev/jira-apis/jira-rest-apis/jira-rest-api-tutorials/jira-rest-api-example-cookie-based-authentication

[assiso]

+1

[RobDolinMS]

@ajtowns Is this still an issue in the latest spec?

[BStramke]

as far as i have seen in 3.0rc1, the authentication still does not support that behavior, or the "in" parameter is lacking the cookie part in its description. There should atleast be an example as there isn't really an obvious way to authenticate through a session cookie.

[RobDolinMS]

Resolved with #1200. Thanks everyone!