How to add an API with oauth2 on the top of Kong - php

Question

I'm trying to add an API on the top kong with using oauth2 authorization plugin of Kong. The steps
I have followed as per their Kong documentation :
Create an API and add oauth2 plugin
Create consumer
Create an application
I got client_id, client_secret, provision_key etc from the above steps, but I'm wondering that if I need to create oauth2 server at my end or kong itself configured it at their end and we just need to call their endpoints.
I'm building my APIs in laravel.

Answer 1

I think we spoke really briefly on Gitter, and there I already said that it depends on your use case. I'll do a brief rundown of typical use cases, and where you need which kind of additional implementation.
Machine to Machine communication
If you need two systems to talk to each other from the backends, and these systems trust each other, you can use the OAuth2 "Client Credentials Flow". In this case, there is no "end user" identity involved, only the two systems which explicitly trust each other.
For this scenario, Kong is everything you need - you just ask Kong's API Token end point (<address of kong>:8443/your_api/oauth2/token for URI based routing, or fqdn.of.kong:8443/oauth2/token if you're using host based routing) for an access token using your client ID and Secret, and you will get one back.
Example:
curl --insecure -d 'grant_type=client_credentials&client_id=<...>&client_secret=<..>' https://<address of kong>:8443/your_api/oauth2_token
Your backend service will get some extra headers injected, such as X-Consumer-Id and X-Custom-ConsumerId which maps to the consumer you created in Kong.
Confidential Web Application with End User context
In case you need to use your API from a confidential (=classic) web application, and you need to have an end user context with each call, you might want to use the OAuth2 "Authorization Code Grant". In this case, you will also need an Authorization Server which you need to implement yourself.
The Task of the Authorization Server is to establish an end user identity (mind you: This is not specified in OAuth2 how this is done, and is up to you; you can federate to some other IdP, you can ask for username and password,...) and then to decide on which rights (="scopes") the user gets when accessing the API. This is completely up to you, and part of your business logic how to decide this.
The flow goes like this:
You (re-)direct a user to the web page of the authorization server
The AS authenticates the user (by whatever means) and decides on the scopes (by whatever other means)
The AS talks to Kong on two different levels
Via the Kong Admin API, to retrieve the provision_key of the desired API
Via the [/your_api]/oauth2/authorize end point, which it uses to get a redirect URI which includes an authorization code, in the context of the authenticated user and his scope (scope and authenticated_userid); to call this end point, you will need response_type=code, client_id, client_secret, provision_key, authenticated_userid (whatever is suitable) and optionally scope (scopes need to be defined on the API as well if you want to use this)
If successful, the AS redirects back to the web application, using the redirect URI returned by Kong
The web app calls Kong's [/your_api]/oauth2/token end point with its client_id, client_secret and code, using the grant_type=code
Now you will have an access token (and a refresh token) which lets your web application access the API on behalf of the authenticated user.
The Authorization Server has to be implemented by you; this is not super complicated, but you still need to make sure you know how to authenticate a user, and/or how you delegate this to some other IdP.
Public Client (Single Page Application) with End User Context
In case you need access to an API from a Single Page Application (like from an Angular app or similar), you should look at the OAuth2 "Implicit Flow", which is a simpler flow than the authorization code grant, but which has other drawbacks, like not being able to use refresh tokens.
This flow works in the following way:
Just like for the Authorization Code grant, you redirect the user to the Authorization Server
The AS establishes identity and decides on scope (once again, this is up to you)
The AS calls the authorize end point, just like with the Authorization Code grant, but this time with response_type=token
Kong, if successful, will return a redirect URI which already contains a token
The AS redirects back to the SPA, using the redirect URI from Kong, which has the access token in the "fragment" of the URI (e.g. https://your.app.com/#access_token=<...>&token_type=bearer&...)
Your SPA will now be able to use the access token to access the API, just like with the Authorization Code grant, on behalf of the authenticated user.
The drawback with this approach is that you can't (that) easily refresh the token, and that it's somewhat less secure than the Authorization Code grant. But dealing with SPAs, there are not many other secure ways of delegating access to it.
Mobile Applications
The last scenario I would like to touch here is Mobile Applications, like Android or iOS apps. For these, the last OAuth2 flow, the "Resource Owner Password Grant" can be used. In short, with this grant you exchange the actual user credentials (username and password) against an access token and a refresh token, so that you don't have to store username and password on the mobile device more than temporarily.
This flow also needs an Authorization Server to be able to use with Kong, albeit a less complicated one this time, even though you must implement an additional token end point (in addition to the one Kong has), which is not ideally described in the Kong documentation.
It'd go like this:
The mobile app uses its client_id (NOT the secret, the secret should not be deployed with the application), the username and password to call the Authorization Server's token end point
The Authorization Server checks username and password (by whatever means, you know the story) and decides on the scope (...)
The AS talks to Kong over admin API again, getting the client_secret for the provided client_id and the provision_key for the desired API
The AS issues a call to Kong's token end point [/your_api]/oauth2/token, like this:
curl --insecure -d 'grant_type=password&provision_key=<...>&client_id=<...>&client_secret=<...>&authenticated_userid=<...>&scope=' https://:8443/your_api/oauth2/token
Note that this call does not contain username and password; those don't belong here, you must check username and password against your own source of identity, Kong will not help you with that.
This call should return both an access token and a refresh token which you then store (as safely as possible) on your device. These replace the username and password, which must not be stored on the device. The access token can as with the other end user context flows (Authorization Code Grant, Implicit Grant) be used to access the API on behalf of the authenticated user.
Using Kong with OAuth2 is tricky and involved, but Kong can really help getting this right and separate your concerns.