Kong Kong Tutorials, 8 Mar 2021

Previous Meeting Next Meeting

⏯

youtube image

►

From YouTube: How to Use Kong Gateway OAuth2 Plugin

Description

Learn how to add OAuth 2.0 authorization and authentication to your service by integrating Kong Gateway and its OAuth 2.0 plugin. View the full tutorial on our blog: https://bit.ly/3sPuMNZ

What Does the Kong Gateway OAuth2 Plugin Do?
As Kong Gateway sits in front of a resource server, the OAuth 2.0 plugin adds authorization server functionality to that resource server — handling authorization requests, inspecting and refreshing tokens, and permitting or forbidding access to resources.

A

In this walk through video, we'll be adding oauth2 authorization on top of a small api server.

A

We'll do that using kong gateway and kong's oauth2 plugin.

A

For our example, project, we have an online fitness site called step on which stores its users daily step counts from their pedometer.

A

We have a user named clark who has an account and data with step, on.

A

We'll build an api server endpoint that serves up clark's data to an authorized requester.

A

Clark also has an account with shoe fly, shoe, and online store that offers bonus rewards when its customers reach certain fitness milestones.

A

Shoe fly shoe can connect to its customers. Fitness app accounts like step on to download their pedometer step, counts.

A

For shoe fly shoe to do this for clark,. It needs clark to tell step on that. He authorizes shoefly shoe to access his data.

A

We're using oauth2 to facilitate that authorization, process.

A

To get started,, we will create our project folder.

A

And we will initialize a new node.js project using yarn init.

A

Accept all the defaults, and then we'll add two packages to our project: express and https.

A

Because oauth2 requires https connections,, we will need to create a self signed certificate and store it on our local machine so that we can serve up.

A

Localhost with https.

A

We'll do that now by creating a certificate subfolder in our project.

A

And then we have some open ssl commands that we need to run.

A

You can just copy these directly from the article.

A

What we do is we create a certificate file as well as a temporary key.

A

We make sure to put in a passphrase for that temporary key.

A

Accept all these defaults for the certificate.

A

And then we retrieve that key using that passphrase.

A

Using that passphrase, we get the key, and now we have a cert.pem and a key.pem, which we will use in spinning up our express server.

A

Next, we're going to create some dummy data for our api server.

A

We just need one json file with that data..

A

So back in our project, folder, we're going to open a new file called data.jason.

A

And this is really just going to be an object. and I'm just copy pasting. Some data in here.

A

basically,. Each of the keys for this object is a user name, and each user name has an array of data.

A

We have just objects in there with dates and step counts.

A

We save that file and we get ready to use it in our server.

A

With that, we're now ready to implement our server and endpoint.

A

In our project, folder, we're going to need to open up a new file called index.js and I'll walk through what we do. Here.

A

First, we require fs because we need to read in our ssl key and our ssl cert.

A

We'll read those in from the two files that we just generated in that certificate: subfolder.

A

Next, we'll require the https package,, which will use a bit.

A

And our server will be listening on port three thousand.

A

Next, we require express and we instantiate it as app.

A

And then we also read in our data from that data.json file that we just wrote.

A

Then we'll be creating a function called get current user.

A

Get current user helps us just kind of mock out what it looks like for somebody to be authorized or logged in.

A

So this is going to look for either a header called mock logged in, as which we're going to set to maybe something like clark, or it's gonna. Look for a header called x.

A

Authenticated user id,, which is related to oauth., we're going to get to that one in a little bit.

A

next, we create our endpoint,, which listens for get requests on /stepcounts.

A

In this end, point, we're going to first log the request headers.

A

We're going to check to see if there's an authorized user by calling get current user.

A

And if there isn't a user,, then we're going to send back a 401, not authorized.

A

If there is an authorized user found,, then we will look in that data object that we had imported in and we'll send back the data for that user.

A

If not,, then, would you send back an empty array.

A

Lastly, we create our server,. We use that https package to prepare our application with this ssl key and ssl cert.

A

And then we set up our server to listen on port three thousand.

A

After saving our file,, we start up our server by calling node index.js.

A

And there our server is running and we just leave that running in a terminal in the background.

A

For testing our api with requests, we'll be using a desktop application called insomnia.

A

But we have to remember that we're using self signed certificates to serve up localhost as https,. So we need to tell insomnia not to validate certificates.

A

So opening the preferences, you want to make sure that box for validate certificates is not checked, because we don't want insomnia to complain when it sees the self signed.

A

Certificate. after we've done that,, we want to create a new request.

A

This request is going to try to get those step. Counts.

A

So we're going to be sending a request to port three thousand.

A

We'll send our request to https localhost port 3000 / step counts.

A

We send the request. and we get back401 not authorized. That's because nobody has been authenticated and so authorized to hit this endpoint.

A

. remember,, we mocked up that log in by having this header that we can accept, mock logged in as header where, if we set the value as,, let's say,, to clark.

A

, then, our server thinks, oh,, this person who's visiting, is clark and clark is authorized to hit this data and we find clark's data and we serve it. Up.

A

So there it is there. the steps needed for installing kong gateway to your.

A

System depend on your system and your environment, setup.

A

You'll need to visit kong's website and choose the appropriate option for yourself for downloading and installing.

A

The oauth2 to plug in for kong does require that kong have access to a database for it to use,. The simplest setup is to have postgresql installed on your local system.

A

So back in our terminal window,, we have to set that up as well.

A

We're going to log in to our database client.

A

And what we need to do is we need to create a user for kong.

A

So we do create user kong and we set his password also as kong.

A

And then we need to create a database called kong and we're going to let the owner of this database be kong..

A

Next, we need to configure kong with proper startup options.

A

So we want to go to /etc/kong.

A

And in that folder there, there is a kong.conf.default template, which we need to copy as kong.conf, and then we're going to open that file and edit it.

A

This configuration file has lots of options. there's a couple that we just need to set. one at around line 268..

A

This is for the actual gateway proxy,, which normally listens on port eight thousand.

A

We're going to have it listen to localhost port eight thousand,, but we're going to set it as ssl, so that we can visit that one with https.

A

Similarly, the admin api for kong,, which is normally at port, eight thousand one.

A

We'll keep it on port eight thousand one,, but we're going to add on that ssl there so that we access it with https.

A

Now, for both the gateway proxy at 8000 and the admin api, eight thousand one.

A

Because we're using ssl,, we need to set up the certificate for localhost.

A

And so actually we're just take that ssl, cert and ssl cert key and we're going to point it to that certificate, slash cert ptm file and that.

A

Certificate / key.pem file that we generated earlier.

A

So we want to set ssl cert and ssl cert key to the absolute path to those two files.

A

This allows our port 8000 gateway proxy to see those certificate files.

A

We're going to do the same thing for admin, ssl, cert and admin ssl cert key at around line 542.

A

We can just copy those above ssl cert lines and we just tack on admin. At the beginning there, since they're, pointing to those same localhost certificate, files.

A

Now,, our proxy and our admin api are set up to also serve up on https.

A

Last thing we want to configure is our database., that's at around eight hundred and forty three or so.

A

We set our database to use postgresql,, we set our host, our ports, our user,, our password,, which has been set to kong, and our database,, which has been set to kong.

A

And those are all of our kong configuration options,. We save that file.

A

And then we also need kong to prepare the database that it now has access to.

A

So we're going to run a command called kong, migrations, bootstrap.

A

And it's going to use those database credentials. log into the database and prepare the database.

A

And then lastly, we can start up kong.

A

make sure you have route privileges to do this.

A

Now that kong is up and running,, let's go back to insomnia.

A

We're going to send some requests to the admin rest api so that we can set up our service.

A

We'll be sending a post request., and this is going to be adding our api server as a service that the gateway has to listen and route for.

A

This post request will be going to https localhost, eight thousand one /services.

A

And in that request, body, we're going to get the name for our service,, we'll just call it to step on api server.

A

And we'll set a url for this service.

A

And that's normally serving up at at https local host three thousand,, which is what our express server is set to do.

A

We will send that request.

A

And there our service has been added.

A

Next,, we need to add a route to kong, gateway.

A

Kong needs to know what path it should be listening on and when it receives requests on that path. To redirect that to our service.

A

This is a post request to routes.

A

It's going to have a json body,, it's going to be going to https local host, eight thousand one.

A

Again,, that's the admin rest api, /routes.

A

The body for this request will have the name for this route,, which we will just call step on routes.

A

And the service that will be pointing to has the name step on api server,, which we set up in the previous step.

A

And the path that kong should be listening, on.

A

Normally,, it's an array,, so we're going to have just one entry in that array and that will be /stepon.

A

So when kong sees requests that come to it at /stepon,, it knows now to route those requests on to our api server.

A

Now that we have our service and our routes added,, we can test sending a request through kong to our api server.

A

This is a request: that's going to be going to the proxy at port 8000 to the gateway.

A

Our request goes to https localhost port, eight thousand /stepon,, because that was the path that we set up in our route, /.

A

Our endpoint step counts.

A

And when we send that request now, we get a 401 unauthorized because there's no authenticated user.

A

That's authorized to access the resources here,, but if we have that mocked up header of mock logged in as,, we set that to clark and we send the request now,. It goes through.

A

Kong through the gateway onto our endpoint, and it sees that, oh,. This is clark.

A

He's authorized to hit clark's data and it serves up clark's data. There.

A

Now, that kong gateway has been set up to sit in front of our api server,. We can add the os to plug in.

A

We do this by sending a new request to the admin rest api.

A

It will be a post, request.

A

This post request is going to go to https localhost port 8001, / services.

A

Slash the name of our service,, which is step on api server.

A

/Plugins, so we'll be adding a new plugin to this service.

A

And in the json body, we'll have the name for this plugin,, which is oauth2.

A

And then we'll set up some configs.

A

We have scopes.

A

Mandatory scope. and enable authorization code.

A

And then we'll have a protocol which we'll set to https.

A

Scopes in oauth2 to refer to a way of limiting the kinds of resources that a client application can access.

A

So, for example, step on the resource server has different kinds of data resources that belong to clark.

A

It might have his user profile, biometric data, step counts.

A

And so, when shoe fly shoe the client application asks for clark's authorization to access his resources,. It needs to specify the scope of that.

A

Authorization., it will just be asking for step counts only because it doesn't need to see his biometric data or his user profile.

A

Now that we've set up oauth2 authorization on top of our api server through kong,, let's see what happens if we try to make that request again to.

A

8000/Stepon/Stepcounts. we send that same request,, which succeeded just a little while ago.

A

But now when we send it,, we get a 401 unauthorized.

A

And the error message that we see there is the access token is missing.

A

Because our server now has oauth2 authorization on top of it, access to these resources requires and access token.

A

Great. step on's api server now has oauth2 authorization on top of it.

A

Now,, there might be lots of client applications out there that want to connect with step on's api server through oauth.

A

And for each of them, we need to add them as a consumer to kong, gateway.

A

We do this by sending out a new admin. Api request.

A

It's a post request which will be going to localhost 8001/consumer.

A

Consumer is just going to be a user of this plugin and in our case, it's going to be shoe flyshoe.

A

So we're going to add a new consumer.

A

post request to /consumers and the user name for this consumer,, we'll just set as shoe fly. Shoe.

A

So they've registered themselves with step on as wanting to connect through oauth.

A

Once we've created a new consumer,, we need to set up oauth2 credentials so that that consumer can make requests of the authorization server.

A

So we send another request to the admin rest api.

A

This one will add oauth credentials for the shoe fly, ahoe consumer.

A

This is a post request.

A

And we're going to be sending it to localhost 8001/consumers/the username for our consumer,.

A

Which is shoe, fly shoe / oauth2.

A

We're going to get a name for this consumer's credentials.

A

it'll be the shoe, fly, shoe customer rewards and then we'll set a redirect uri,, which will be the location that a user's browser will be redirected back to after.

A

They've authorized a client application to access the resources., we'll talk about that in a second.

A

We send this request to create these oauth2 credentials, and now what we have is a client's secret and a client id for shoe fly shoe.

A

This is what shoe fly. Shoe will need to use later when dealing with authorization, codes and access tokens.

A

Regarding the redirect uri,, let's talk a little bit about the oauth2 authorization flow.

A

Here's how it works. so clark is at the website for shoe fly shoe,, and he sees a description that says, you know,. We can connect directly to your step on account if you.

A

Let us,, then we can download your step counts..

A

Just click on this connect button to do that., click, click on the button and shoe fly shoe redirects clark's browser over to step ons website to an authorization page.

A

And that page says, clark,, do you authorize shoe fly shoe to access your step, counts?.

A

Clark clicks on the button to authorize. and this submits a form to step on's web server.

A

The web server in the back end receives the form data which has the client id which shoe flyshoe had set up, along with the scope of authorization that shoe fly. Shoe was asking.

A

For., that is, step counts., along with a redirect uri, where it's supposed to send clark after it's done.

A

And the web server sends a post request behind the scenes to get an authorization code for shoe, fly shoe.

A

It gets that authorization code and it sends clark's browser back to shoe, fly shoe to that. Redirect uri.

A

And tacked on the end of it is a query parameter which has that authorization code.

A

Now, shoe fly shoe at its oauth2 to return page on its web. Server receives the authorization code and behind the scenes it sends a request to.

A

Step on's authorization server, exchanging that authorization code for an access token and a refresh token.

A

It stores those tokens in its own database and it will use them in the future in order to request resources on behalf of clark.

A

Now,, let's go ahead and use insomnia and walk through all of these requests that are happening.

A

So clark has just submitted the form clicking on that button that says, yes,. I authorized shoefly shoe to access my resources.

A

Step on's web server in the back receives this form with the client id,, with scopes,, with the redirect uri,, and it sends a.

A

Request to its authorization server., this request goes to localhost 8000/stepon, because this is the path.

A

For step, on's service, /oauth2/authorize.

A

The body of that request will include the client id, which shoe fly. Shoe has sent on as it redirected clark over to this authorization page.

A

We'll paste that in the second., the response type,, which is code, an authorization code.

A

The scope of authorization that shoe fly shoe was asking for step. Counts.

A

A provision key which is related to the oauth2 plugin that we've configured on kong.

A

We're going to get that in one of our previous requests in just a second.

A

And then the authenticated user id that is here on the step on website.

A

What user is this. clark has already logged in probably on the step on website, and so we don't know that this entire authorization request has to do with step. On's user clark,. Let's go get that.

A

Client id from our previous request,, the one where we set up the oauth credentials for shoefly shoe.

A

We had that client id., that's the one that shoe fly shoe would already hold on to and he would have passed it along as he redirected clark over to this page.

A

But we're going to copy paste it in here.

A

Then there's the provision key,, which shoe fly shoe, doesn't know about,, but step on knew about when it set up the plug in,. We go back to our earlier request when we enabled that.

A

Plug in on the service and way down at the bottom of that request response there is that secret provision, key.

A

Now,, we know that we're talking about this plug in for this service, and that's a special key.

A

Those are the pieces of the request body that we need to request an authorization code.

A

Now,, this is happening behind the scenes on step. On's server.

A

The response from step, on's authorization server, is a redirect uri. That is the shoe fly shoe webpage.

A

That oauth return web page that we set up with an authorization code tacked to the end of it as a query. Param.

A

Now,, I should have mentioned that when we had sent this request body,, we actually should have included a redirect uri that web page there that oauth return web.

A

Page., but we neglected to do that. fortunately, by default,, since it was the only redirect uri set up for this consumer for his credentials,. It knows to send him back here.

A

Now, clark has been redirected by step on's web server to that redirect uri.

A

Sending him back to shoe fly shoe's website.

A

Shoe fly shoe's web server at this oauth return page sees the authorization code and now behind the scenes it can send a request to step on's.

A

Authorization server, exchanging that authorization code for an access, token.

A

That request is a post, request.

A

Which we will send here to localhost 8000/.

A

Stepon/Oauth2/Token. and in the request body for this request,, we set a grant type authorization code,. That is I'm about to provide you an.

A

Authorization code. we placed in that code from our previous request, we'll do that in a second.

A

And then we have to add shoe fly, shoe's,, unique client, id and client secret.

A

This way, step on, knows, I really am shoe, fly shoe,. I have this agreement with you to do oauth2 connections and this is me,. This is my secret.

A

And here's a code that I just received for clark.

A

We paste that code in.

A

We paste in the client id and the client secret, which shoe fly, shoe stores,. So it knows what those things are and it's going to paste it in here and we're going to paste it in.

A

Here,, send it with our request.

A

So what shoe fly shoe is doing here is, it is taking the authorization code, and it is saying I would like now a long term access token that.

A

I can use to access clark's resources on your api server.

A

We send the request and there is the access token and the refresh token.

A

Now, with that token, in hand, shoe fly shoe can make requests in the future on its own to access clark's resources over at step. On's api server.

A

So we'll go back to that original. Get step, count request that we had, the one that failed, because there was no access, token.

A

And what we do for this request now is we set up bearer token auth.

A

We don't need this header anymore., the header is useless,, but we set up bearer token auth.

A

And for this type of authorization,, all we do. Is we paste in that access token, that shoe fly? Shoe now has received and stored.

A

And it can use this token whenever it wants to access clark's resources on step, on's, api server.

A

Let's recap briefly: what's just happened, here.

A

now without clark's involvement, anymore shoe fly, shoe, has this access token stored and whenever it wants to, it can send a request to step on's api.

A

Server and present this token showing that it has authorized access to clark's resources.

A

Now,, if we open up our original terminal,, the one where we were spinning up our express server and we log our request, headers,, let's take a look at those headers now.

A

So here's the header of that most recent request that came in.

A

and we can see that kong, through oauth2 plug in,, has actually written additional information to the upstream headers,, which our express server can now see..

A

It sees a consumer username. and this is through the oauth token. oh,. It knows at this token came to us from shoe, fly shoe and shoe fly shoe is accessing clark's resources.

A

That's the authenticated user id., and we also know that shoe fly shoe in this token, has only the authorization to access the scope of step, counts,, nothing else.

A

So, let's make sure server that we only send step count. Data related to clark.

A

The last request that we want to demonstrate is what happens when the access token that shoefly shoe was holding on to is about to expire by default with kong,. These tokens.

A

Expire in 70 to 100 seconds or two hours.

A

But they also receive remember, a refresh token.

A

That refresh token, is what the client application shoe fly shoe can use to send a request to the authorization server saying I need a new access.

A

Token., so this request is a post request that goes to port eight thousand and it's a refreshed token request,. It's a.

A

Post request, which we send to the authorization server.

A

This post request goes to localhost eight thousand/stepon/oauth2/toke.

A

N. this looks very similar to how we exchanged an authorization code for an access token and refresh token,, but now we're exchanging a refresh token.

A

That's our grant type. and here's our token,, which we're pasting in,, we're exchanging that for a new access token and refresh again.

A

And again, to show that we're actually shoe fly shoe, we're actually authorized to connect with you through oauth., we're going to have to provide a client id and a client secret,.

A

Which we have from one of our previous requests., we will copy that data in there.

A

And now, when we send this request,, we get back a new access took in and refresh token.

A

And you should also note that the original access, token and refresh token, the ones on the left are no longer valid..

A

They should be replaced by this new one on the right.

A

And that covers our entire project walk through today, as we used kong gateway and kong's oauth2 to plugin to put oauth2 authorization on top.

A

Of an api server., thank you for joining us.