Implementing Key Authentication in Express Gateway
So, you’ve probably used it before: key authentication. The basic idea is simple, to authenticate your app or client with a given service you send a key to identify (and authorize) yourself. Also, this is not intended for individual users necessarily, but rather for systems talking to each other. (Just to be clear, for users authenticating themselves you might want to look into OAuth2, something Express Gateway also offers.)
In this article I’ll be showing you how to get up and running with key authentication quickly and easily with Express Gateway (EG). We’ll talk about setting up and configuring your gateway, creating credentials, and sending authenticated requests. This is a brief introduction, so be sure to read the documentation and test things before you deploy your API gateway!
Creating and Configuring the Gateway
Your first step might be to generate a new Express Gateway instance. (Feel free to skip this step if you’ve already done this.) You’ll want to first install the
package and then generate a new gateway:
~$ npm i -g express-gateway
~$ eg gateway create
? What's the name of your Express Gateway? widget-factory
? Where would you like to install your Express Gateway? widget-factory
? What type of Express Gateway do you want to create? Getting Started with Express Gateway
To start widget-factory, run the following commands:
cd widget-factory &amp;&amp; npm start
Great! Before we start up our gateway for the first time, let’s go ahead and configure it.
Express Gateway has two primary configuration files (plus model configuration) in the
directory of your new project: the
file and the
file. The system config file is where you will set up things like database access (for the gateway, not your individual microservices) and certain security settings for things like OAuth2. We won’t be working in that file today (which also means our users and credentials will not be saved for this example).
The gateway configuration file is where you configure HTTP, endpoints, policies (like key authentication), and pipelines (which are just a series of policies applied to some endpoints). The default generated config file creates one API endpoint for the gateway at
and proxies those requests to <https://httpbin.org/ip> – you’ll want to change that later, but we’ll leave it for now. What we need to do is add a policy to the “api-basic” pipeline (the only one in there).
Find your “pipelines” block in the
file and make it look like this:
- name: api-basic
- key-auth: ## This line is new!!
Notice that we added our “key-auth” policy before the “proxy” policy. The policies in each pipeline are ordered, so be sure to put them in the order you want them to execute. In our case, we should not proxy the API request if the authentication fails.
Believe it or not, that’s the only change you need to make to our demo gateway to enable key authentication! You can test this out by starting up the gateway and making a simple
(or any other endpoint really):
~/widget-factory$ npm start
You can test the HTTP request using cURL, or a tool like Postman (which I highly recommend for API development). Here is the response you might get using cURL:
~$ curl -D - "http://localhost:8080/ip"
HTTP/1.1 401 Unauthorized
Content-Type: text/html; charset=utf-8
Date: Sun, 16 Jul 2017 19:37:52 GMT
Notice that our response code was
because we did not send an API key. We’ll talk more about these status codes later, but for now let’s make an API key.
Generating Key Credentials
Our first step to create an API key is to create a “user” in the system. Open up another terminal window and navigate to your gateway project directory. Now we can use the same
command we used to generate the gateway to create credentials:
~/widget-factory$ eg users create
? Enter username [required]: jordan
? Enter firstname [required]: Jordan
? Enter lastname [required]: Kasper
? Enter email: [email protected]
? Enter redirectUri:
✔ Created jordan
I’ve left the
blank here because we are not using it in key authentication, but you might need for other schemes. Now that we have a user, can either create an “app” for that user and then “credentials”, or we can just create the “credentials” for the user themselves. I’ll do the second option for now:
~/widget-factory$ eg credentials create -c jordan -t key-auth
"createdAt": "Sun Jul 16 2017 15:48:48 GMT-0400 (EDT)",
"updatedAt": "Sun Jul 16 2017 15:48:48 GMT-0400 (EDT)",
That’s it! Notice that the output above shows us out
. These two pieces together create our final API key for the system.
Sending Authenticated Requests
Now that we have some credentials we can send some more requests to our API (through our gateway).
~$ curl -H "Authorization: apiKey 0J6961Lhn8JgxYybTXFdRg:23BfI6QVqgdxP3ty8F4Jx3" -I "http://localhost:8080/ip"
HTTP/1.1 200 OK
date: Sun, 16 Jul 2017 19:54:49 GMT
content-type: text/html; charset=utf-8
via: 1.1 vegur
There are two points of note above: first, we got a
response! That’s great, that means our auth check passed! So how did we do that? We sent the
header with our key in it. Remember, our key is made up of two parts. So you can see above that the
header value is actually two pieces of information separated by a colon (“:”). Additionally, we prefix that value with our header scheme: “apiKey”.
Authorization: apiKey 0J6961Lhn8JgxYybTXFdRg:23BfI6QVqgdxP3ty8F4Jx3
header name : scheme keyId : keySecret
As you see above, we got a
response status code, meaning success! That status code actually came from our API service (in this case httpbin.org) not from our gateway. If you request a resource that doesn’t exist on that service you should receive a
, for example. The gateway will send back a
when the key is not authenticated – or missing entirely. But it could also send back a
if the user is authenticated, but not authorized for the given resource. This could happen if you are using “scopes”.
What’s a Scope?
We won’t get deep into scopes in this blog post, but the scopes are the main entities for specifying authorizations within Express Gateway. A scope is simply a pre-defined string added to your gateway configuration (both on an API endpoint and then again on a policy in a pipeline for that endpoint). API endpoints are secured by specifying scopes. To be authorized for an API endpoint that is secured by a scope, a consumer must have a credential containing the scope listed on the API endpoint. In other words, the scopes on the endpoint have to match the scopes on the user’s (or app’s) key credentials.
There are more options you can add to your gateway “key-auth” policy to secure it further or simply customize it. For example, by default the gateway will accept keys in both the headers and query string as well. You can easily disable this with the
- name: api-basic
- disableQueryParam: true ## Disable API keys in the query string
You can also change the header used for authentication (although this would break with current standards) or the scheme used:
- name: api-basic
- apiKeyHeader: "X-My-Auth-Header"
- apiKeyHeaderScheme: "key-pair"
If you used the configuration above you would need to modify the header you send in all authenticated API requests like so:
~$ curl -H "X-My-Auth-Header: key-pair 0J6961Lhn8JgxYybTXFdRg:23BfI6QVqgdxP3ty8F4Jx3" -I "http://localhost:8080/ip"
Managing Key Credentials
Our last topic for this post has to do with managing those keys you’ve generated. You will probably find a time when you need to deactivate a user’s access. This is easily accomplished on the command line by deactivating their credentials:
~$ eg credentials deactivate -t key-auth 0J6961Lhn8JgxYybTXFdRg
✔ Deactivated 0J6961Lhn8JgxYybTXFdRg
After performing this action, the given
will no longer be authenticated in the gateway. This is not a permanent action, and the credentials can easily be reactivated with the companion
~$ eg credentials activate -t key-auth 0J6961Lhn8JgxYybTXFdRg
✔ Activated 0J6961Lhn8JgxYybTXFdRg
One of the biggest things an API gateway can do for you is centralize the authentication for your various microservices. And Express Gateway makes this process extremely straight forward. Take a look at the documentation and give it a try!
- Sign up for our private beta – your feedback helps prioritize our roadmap with the most value realized within the shortest amount of time
- Check out our Open Source Initiative: The Express Gateway
- Learn about the inaugural feature set we’re striving for to make APIs repeatedly fast, easy and manageable as you evolve through the API lifecycle itself.
- Sign up for the latest development on APIs and microservices.