1 Define the API endpoints
1 Define the API endpoints
This implementation uses the Express web application framework to build a Node.js API.Launch your API server using
Create a package.json File
Create a folder for your API, navigate into it, and runnpm init. This sets up your package.json file.Leave the default settings or change them as you see fit.Our sample’s package.json looks like the following:Install the Dependencies
Next, set the dependencies with the following modules:- express: This module adds the Express web application framework.
- cors: This module adds support for enabling CORS, which is required since the API is called from a Single-Page Application that runs on a different domain inside a web browser.
- jwks-rsa: This library retrieves RSA signing keys from a JWKS (JSON Web Key Set) endpoint. Using
expressJwtSecret, we can generate a secret provider that provides the right signing key toexpress-jwtbased on thekidin the JWT header. To learn more, refer to the node-jwks-rsa GitHub repository. - express-jwt: This module authenticates HTTP requests using JWT tokens in your Node.js applications. It provides several functions that make working with JWTs easier. For more information, refer to the express-jwt GitHub repository.
- body-parser: This is a Node.js body parsing middleware. It extracts the entire body portion of an incoming request stream and exposes it on
req.bodyas something easier with which to interface.
Implement the Endpoints
Navigate to your API directory and create aserver.js file. Your code needs to:- Get the dependencies.
- Implement the endpoint(s).
- Launch the API server.
node server and make an HTTP POST request to localhost:8080/timesheets. You should see a JSON response with the message This is the POST /timesheets endpoint.So now we have our endpoint but anyone can call it. Continue to the next step to see how we can fix this.2 Secure the API endpoints
2 Secure the API endpoints
In order to validate our token, use the If we launch our server now and do an HTTP POST to
jwt function, provided by the express-jwt middleware, and the jwks-rsa to retrieve our secret. The libraries do the following:express-jwtdecodes the token and pass the request, the header, and the payload tojwksRsa.expressJwtSecret.jwks-rsadownloads all signing keys from the JWKS endpoint and see if a one of the signing keys matches thekidin the header of the JWT. If none of the signing keys match the incomingkid, an error will be thrown. If we have a match, pass the right signing key toexpress-jwt.express-jwtcontinues its own logic to validate the signature of the token, the expiration,audienceand theissuer.
- Create the middleware function to validate the access token.
- Enable the use of the middleware in our routes.
localhost:8080/timesheets we should get the error message Missing or invalid token (which is accurate since we didn’t send an access token in our request).In order to test the working scenario as well we need to:- Get an access token. For details on how to do so refer to: Get an Access Token.
- Invoke the API while adding an
Authorizationheader to our request with the valueBearer ACCESS_TOKEN(whereACCESS_TOKENis the value of the token we retrieved in the first step).
3 Check the app permissions
3 Check the app permissions
In this step, we add the ability to check if the application has permissions (or scopes) and use our endpoint in order to create a timesheet. In particular, we want to ensure that the token has the correct scope, which is Now add a call to If we invoke our API with a token that does not include this scope, then we should get the error message Forbidden with the HTTP status code
batch:upload.In order to do this, we make use of the express-jwt-authz Node.js package, so add that to your project:jwtAuthz(...) to your middleware to ensure that the JWT contain a particular scope in order to execute a particular endpoint.We add an additional dependency. The express-jwt-authz library, which is used in conjunction with express-jwt, validates the JWT and ensures it bears the correct permissions to call the desired endpoint. For more information, refer to the express-jwt-authz GitHub repository.This is our sample implementation (some code is omitted for brevity):403. You can test this by removing this scope from your API.4 Determine User Identity
4 Determine User Identity
The
express-jwt middleware that is used to validate the JWT also sets req.user with the information contained in the JWT. If you want to use the sub claim to identify the user uniquely, you can use req.user.sub. For the timesheets application, we want to use the email address of the user as a unique identifier.Create an Action
First, create a new Action that will add the email address of the user to the access token.- Navigate to Auth0 Dashboard > Actions > Library, and select Build Custom.
-
Enter a descriptive Name for your Action (for example,
Add email to access token), select the Login / Post Login trigger, and select Create. -
Locate the Actions Code Editor, copy the following JavaScript code into it, and select Save Draft to save your changes:
The
namespaceis used to ensure the claim has a unique name that does not clash with standard OIDC claims or internal services. To learn more about restrictions and guidelines with namespaced and non-namespaced claims, read Create Custom Claims. - From the Actions Code Editor sidebar, select Test (play icon), then select Run to test your code.
- When you’re ready for the Action to go live, select Deploy.
Add your Action to the Login Flow
Next, add the Action you created to the Login Flow. To learn how to attach Actions to Flows, read the “Attach the Action to a flow” section in Write Your First Action.Retrieve the unique identifier
Finally, from inside your API, retrieve the value of the claim fromreq.auth. Use that value as the unique user identifier to associate with timesheet entries.