How to Implement OAuth in Express Gateway
Express Gateway gives you the ability to spin up your own oauth provider from the command line. OAuth enables your users to delegate API endpoints to various apps via scopes. In this introductory article, you’ll learn how to get up and running with OAuth in Express Gateway.
Configuring the Gateway
The first step is to create a new gateway using the Express Gateway generator.
First, install the
npm module, and then create a new gateway using
$ npm i -g express-gateway
$ eg gateway create
? What's the name of your Express Gateway? oauth
? Where would you like to install your Express Gateway? oauth
? What type of Express Gateway do you want to create? Getting Started with Express Gateway
To start oauth, run the following commands:
cd oauth &amp;&amp; npm start
Second, edit the
file and enable OAuth for the
pipeline as shown below. Once you turn on OAuth, you should see an ‘Unauthorized’ error when you visit
. You need to restart the server for config changes to take effect, so if you ran
be sure to kill the process and then re-run
- name: default
# The below enables oauth for the localhost:8080/ip endpoint
Next, you’ll need to create a new Express Gateway user. Users and applications have a one-to-many relationship, so you must create a user before you create an application. Make sure you do not restart the express gateway server after creating a user unless you have already set up a data store, because otherwise express gateway will use an in-memory data store and all your users will be deleted if the process is killed.
$ eg users create
? Enter username [required]: val
? Enter firstname [required]: Valeri
? Enter lastname [required]: Karpov
? Enter email: [email protected]
? Enter redirectUri:
✔ Created c25fe037-30bb-42f7-9f3a-0264dcd60d14
"email": "[email protected]",
"createdAt": "Wed Aug 16 2017 22:08:07 GMT-0700 (PDT)",
"updatedAt": "Wed Aug 16 2017 22:08:07 GMT-0700 (PDT)"
Next, you need to create 2 credentials for this user: an OAuth credential and a basic-auth (password) credential. Express Gateway has a one-to-many relationship between users and credentials, so a user can have multiple credentials of different types (OAuth, key-auth, basic, etc.). The below creates an OAuth credential and a basic-auth credential with password “bacon”. Note that
doesn’t show up in the output of
, that’s for security.
$ eg credentials create -c val -t oauth2
✔ Created val
"createdAt": "Wed Aug 16 2017 22:08:13 GMT-0700 (PDT)",
"updatedAt": "Wed Aug 16 2017 22:08:13 GMT-0700 (PDT)",
$ eg credentials create -c val -t basic-auth -p "password=bacon"
✔ Created val
"createdAt": "Wed Aug 16 2017 22:08:21 GMT-0700 (PDT)",
"updatedAt": "Wed Aug 16 2017 22:08:21 GMT-0700 (PDT)",
Finally, you need to create an application, or “app”. The app represents a consumer of your API. Similar to how an app might use Facebook login and request access to the user’s photos, an Express Gateway app will log in against Express Gateway and receive permission to access a certain set of API endpoints. To create an app, you need to specify an associated user, a name, and a redirect URI, which is the URL the user will be directed to after successfully logging in.
$ eg apps create -u val
? Enter name [required]: testapp
? Enter redirectUri: http://google.com
✔ Created 84828eee-2832-4ecd-8155-008fbea0f485
"createdAt": "Wed Aug 16 2017 22:08:38 GMT-0700 (PDT)",
"updatedAt": "Wed Aug 16 2017 22:08:38 GMT-0700 (PDT)"
Walking Through the Oauth Flow
Now that you’ve set up the necessary objects, let’s walk through the actual oauth flow using Chrome and cURL. You’ll notice that if you visit
in Chrome you’ll get an ‘Unauthorized’ error message as shown below.
file protects the
endpoint behind oauth middleware, so you need to get an access token by walking through the Express Gateway oauth flow. To start, you need to visit the
endpoint and specify the following parameters in the URL query string:
: String containing either ‘bearer’ or ‘token’. For this example you’ll use ‘token’.
: String containing the id of your app from the output ofeg apps create -u val
. In this case, ‘84828eee-2832-4ecd-8155-008fbea0f485’, but it will be different for you.
: String that must match theredirectUri
you specified when running theeg apps create -u val
Here’s how the full URL looks:
When you visit this URL, you should get redirected to a login screen. You can configure the UI, but for this article you’ll just use Express Gateway’s minimal built-in login screen.
Enter in the username and password you entered when you ran
. If you’re following this article exactly, the username will be “val” and the password will be “bacon”. You will then get redirected to a page that asks you to authorize your app ‘testapp’ to access your account. In more advanced applications, this is also where Express Gateway will ask for other permissions (scopes).
Hit the ‘Allow’ button to continue the flow and you’ll get an ‘Unauthorized’ error.
Don’t panic, you didn’t do anything wrong, this is actually the right behavior.
OAuth is all about granting API access to client apps, and does so by putting the
in the URL. This is the access token you use in the
header in your HTTP requests to authenticate to the oauth policy. Your app will have to do that on its own, but, in the interest of keeping this example lean, you’ll just use curl.
from the URL bar. The
is URI-encoded, so first decode it using Node.js’s shell.
to make an HTTP request with the token in the
header as shown below:
$ curl -H "Authorization: Bearer 599f481560a74545a0f9d54a2e3f7dde|b1f7252fe6f24a0d98d98cc87693579c" http://localhost:8080/ip
Congratulations, you’ve successfully generated an access token through Express Gateway’s oauth flow and used it to make an authenticated request!
This article is just a “Hello, World” level example for OAuth with Express Gateway. In this example you used Express Gateway as both the auth server (the server requesting auth) and the resource server (the server granting access to the API).
However, Express Gateway can also serve as an auth server for an external API, so you can add OAuth permissions on top of any API. I’d recommend you try actually building a client-side app that uses Express Gateway OAuth for login, and read up on scopes so you can control which portions of your API your app has access to.
- 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.