Swagger-UI + OAuth2/OpenID

[Ari]

Hi,

Is there a best practice (or practice at all) for authenticating swagger-ui prior to REST calls?  I have a REST API that defers the sign-in process to an OAuth provider (Facebook) upon authentication/authorization the API returns a session token for use during REST calls. Thanks.

-Ari

[Ron Ratovsky]

You just need to integrate it in the UI. The pet store does it - http://petstore.swagger.io.

--
You received this message because you are subscribed to the Google Groups "Swagger" group.
To unsubscribe from this group and stop receiving emails from it, send an email to swagger-swaggers...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

--

-----------------------------------------

http://swagger.io
https://twitter.com/SwaggerApi
-----------------------------------------

[Ari]

To be clear, when you refer to "it" do you mean that I need to clone swagger-ui and customize it to include a (OAuth/OpenId) login dialog and flow or that there is a drop-in swagger module (a la the pet store) that does this and I need to integrate that? 

Best,

Ari

[Ron Ratovsky]

You need to make sure the OAuth2 is defined in your definition, and then hook the OAuth2 definitions as done by the pet store sample.

--
You received this message because you are subscribed to the Google Groups "Swagger" group.
To unsubscribe from this group and stop receiving emails from it, send an email to swagger-swaggers...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[Ari]

> You need to make sure the OAuth2 is defined in your definition, and then hook the OAuth2 definitions as done by the pet store sample.

Can you expand on how to add it to the definition? I've reviewed a swagger resteasy example that uses the "Swagger" class to define a security definition, but I'm unclear how to use this with the BeanConfig in the Application class and if it conflicts with the annotations (@Api(value="...")) used on the resources. I also reviewed this example, but it seems outdated.

[tony tam]

There are a bunch of different oauth 2.0 flows, the easiest thing to integrate is with the implicit flow.  You would define the security model like such:

  "securityDefinitions": {
    "petstore_auth": {
      "type": "oauth2",
      "authorizationUrl": "http://petstore.swagger.io/api/oauth/dialog",
      "flow": "implicit",
      "scopes": {
        "write:pets": "modify pets in your account",
        "read:pets": "read your pets"
      }
    }
  }

note how there is an authorizationUrl and flow type.  You would modify the index.html to suit your needs with your application id, like such:

      window.swaggerUi = new SwaggerUi({
        url: url,
        // spec: spec,
        dom_id: "swagger-ui-container",
        supportedSubmitMethods: ['get', 'post', 'put', 'delete', 'patch'],
        onComplete: function(swaggerApi, swaggerUi){
          if(typeof initOAuth == "function") {
            initOAuth({
              clientId: "your-client-id",
              clientSecret: "your-client-secret",
              realm: "your-realms",
              appName: "your-app-name",
              scopeSeparator: ","
            });
          }

And the authentication provider (facebook) would call back with a token per the oauth2 spec.  You can look at how to implement this in java by looking at this sample:

https://github.com/swagger-api/swagger-samples/blob/master/java/java-jersey-jaxrs/src/main/java/io/swagger/sample/Bootstrap.java#L31

Which has this code (this is what is used in the petstore sample):

swagger.securityDefinition("petstore_auth",
  new OAuth2Definition()
    .implicit("http://petstore.swagger.io/api/oauth/dialog")
    .scope("read:pets", "read your pets")
    .scope("write:pets", "modify pets in your account"));

I would suggest using the same URL as pasted above for testing your UI--it's a simple oauth2 service that accepts any username/password combo.