Developing a Secure API with NestJS

[ramiro]

Learn how to use NestJS, a Node.js framework powered by TypeScript, to build a secure API.

Read on

Brought to you by @dan-auth0

[dan-auth0]

I’m loving TypeScript. NestJS made it much easier to integrate it within the context of NodeJS. Let me know what you think about this tutorial, please Loved it? Hated it?

[mob]

@dan-auth0 This seems like a great tutorial! I’ve been meaning to try NestJS for quite some time now, and this article looks like a very good entry point.

There’s one thing I don’t understand though, and that is need to create the @Permissions decorator.
In the final example, you use it like this:

@UseGuards(AuthGuard('jwt'), PermissionsGuard)
@Post()
@Permissions('create:items')
create(@Body('item') item: Item) {
  this.itemsService.create(item);
}

But I really don’t see the added value of the @Permissions (other than the fact that I like decorators ) . Is there any particular reason why you didn’t pass the permissions to PermissionsGuard through an argument like it’s done for the AuthGuard?

@UseGuards(AuthGuard('jwt'), PermissionsGuard('create:items'))
@Post()
create(@Body('item') item: Item) {
  this.itemsService.create(item);
}

That would avoid the creation of a new decorator. Did I miss something?

But I really like the syntax simplicity of the @Permission decorator
Wouldn’t it be possible instead to declare the PermissionGuard to be used globally for all methods (since it doesn’t prevent access to method without attached permissions anyway)?
This way, we wouldn’t have to add the guard to methods that do have the @Permission decorator, like this:

@UseGuards(AuthGuard('jwt'))
@Post()
@Permissions('create:items')
create(@Body('item') item: Item) {
  this.itemsService.create(item);
}

Anyway, kudos again for this tutorial. I’ll surely do more than just read it sometime

[dan-auth0]

Thank you for reading and for your feedback

To address your question:

Is there any particular reason why you didn’t pass the permissions to PermissionsGuard through an argument like it’s done for the AuthGuard ?

It’s for educational purposes as to how to create a custom decorator. Both methods would work well. I do prefer the @Permissions() decorator as it reads so cleanly but also could be used by something different than the guard, perhaps

[zacksinclair]

Great tutorial. I had already implemented the same integration (Auth0 via NestJS) - but a bit differently. Wanted to point out something and ask a couple questions:

This may be an inconsistency in code vs description:

The PermissionGuard has:

    const hasPermission = () =>
      userPermissions.some(permission => routePermissions.includes(permission));

Then the copy states:
“The route handler has permissions set and each one of them is present in the permissions claim of the access token.”

userPermissions.some will only require that one of the permissions is met, as opposed to “each one of them”. The code should probably be userPermissions.every or the copy should be “one of N permissions met”. (To this end - I am curious which approach is “better” - every or some - or perhaps supporting both via separate decorators is a good thing)

Questions:

1. In my implementation, I call the Auth0 API to get the user’s current permissions, then cache the results of that API call for N (10 minutes) - as opposed to storing permissions in accessToken and just reading it. Should I swap to storing/reading in accessToken? If you use accessToken, how do you handle permission changes when tokens are out in the wild?

2. In the docs here it is stated that access tokens should never be used for authentication. The tutorial states:
   “Then, the access token can be sent as a bearer token in an authorization header to prove authentication to the server on requests made to protected endpoints.”
   This seems in contradiction to the docs I linked stating access token should not be used for AuthN. Could you help clarify?

3. Related to #2 - is it best a best practice to authenticate with idToken and then authorize with accessToken? IE check authentication via idToken in middleware, then confirm permissions by checking accessToken in a guard? That was my understanding; seems like the tutorial only does AuthZ, but not AuthN.

4. “Refresh the WAB Dashboard to rotate the access token” - where is the access token rotation implemented?

5. Is there a repo somewhere showing the full implementation?

Thanks in advance.

[dan-auth0]

Howdy! Welcome to the Auth0 community and thank you for reading this blog post I apologize for the delay in response. I was on vacation. I’ll be working a response for you within the next days

[puffancs]

Hello.

I have implemented almost the same solution and would be happy to help with the next chapters and review.

To be hones an article like this would have been a tremendous help for me a couple of month ago, so thank you very much for writing it. It will be really helpful for the community!

The client side code would be interesting to go through. How you implemented token refresh, audience handling etc.

Ideas for the article mixed with a couple of questions:

• I have not used passport but express-jwt and a middleware. I believe passport is an overshoot for this task and makes life a bit more complex then it should be. If a middleware is used with a custom jwt validation (which is done in the startegy anyway) to store the jwt on the req object and a single AuthGuard is created then it would remove a bit of magic from the flow and 1 guard would be enough instead of 2
• Using guards would be problematic with graphql in my opinion, because every ResolvePropery should be protected anywhere it is used. Because of this I have put the authorization logic in the service layer.
• On the client side it’s “tricky” to know how to force auth0 to use jwt access_token-s (audience has to be specified)
• It would be greate to know what is the best practice if I have multiple api-s? How do I handle it on the UI? (The ui should request the access token? Or the back-end?)
• The jwt parse is a bit simplisitic. The revoked token handling is not implemented I believe
• express-jwt is used in all the old docs and in the example code but it’s not really maintained
• the client callback has a bit of black magic to it (dashboard.whatabyte.now.sh) Instead of putting up a now.sh app I would have shown how to set up url-s in the host so anybody could follow and reproduce the example.
• there is a way to load .env files when starting the app so it would not be necessart to put the import and .config() everywhere I want to use them. node --inspect -r dotenv/config -r ts-node/register -r tsconfig-paths/register src/main.ts If this is used in package.json then it’s all done automatically.
• I personally prefer nodemon but it’s a personal preference
• I would not use roles on ui because permissions should define what can be shown.
• on the UI (angular) I had to implement routeguards, link visibility and directive for restriction. It was a bit tricky, would be happy to share how I did it.

The article is well written easy to follow and understand and it’s greate to have one. Thank you. Please take my ideas as a personal opinion for improvement.

Would be really happy to get involved in next steps for this topic.

[konrad.sopala]

Hey there @puffancs!

Have you considered joining our Auth0 Guest Authors program?

Auth0's Apollo Program

Sounds like a perfect fit!

[dan-auth0]

Feedback like this helps us all grow and become better. Thank you for taking the time to read the post and to leave this detailed comment.

I’ve been working over the past weeks to improve the language of the tutorial and do some additional research. It started as a foundation of what identity in NestJS would be like.

Let me address your points one by one, please:

The client side code would be interesting to go through. How you implemented token refresh, audience handling etc.

Absolutely. This is on the pipeline It would be a tutorial of using React with TypeScript.

I have not used passport but express-jwt and a middleware. I believe passport is an overshoot for this task and makes life a bit more complex then it should be. If a middleware is used with a custom jwt validation (which is done in the startegy anyway) to store the jwt on the req object and a single AuthGuard is created then it would remove a bit of magic from the flow and 1 guard would be enough instead of 2

I debated over this one haha! I went with Passport because NestJS provides that NestJS module out of the box and it seemed like a good idea to show how to integrate it. Definitely for the use case here, Passport is “over-engineering” as there are no sessions, etc.

I will be adding the option on a different chapter to use a simple middleware function instead. What do you think about it?

https://gist.github.com/dan-auth0/ce63f6dd2cb0ae6c14f0eef6b92171b9

Using guards would be problematic with graphql in my opinion, because every ResolvePropery should be protected anywhere it is used. Because of this I have put the authorization logic in the service layer.

GraphQL was not on my radar, but as Konrad commented, if you like to write content and this is something you’d like to contribute to our blog, by all means, I’d invite you to apply to the Guest Author program

However, making the code more adaptive to different architectures is a solid goal to have. How did you go about putting the authorization logic in the service layer?

On the client side it’s “tricky” to know how to force auth0 to use jwt access_token-s (audience has to be specified)

Is this feedback about our documentation not being clear on this or the process not being intuitive?

It would be greate to know what is the best practice if I have multiple api-s? How do I handle it on the UI? (The ui should request the access token? Or the back-end?)

This would be a great topic for a general post without being connected to a particular backend technology, for sure.

The jwt parse is a bit simplisitic. The revoked token handling is not implemented I believe

Right at this time there is no refresh token. I am considered adding that as an extra chapter as long as guidance on how to implement short-lived tokens. Something similar to what @zacksinclair has done.

express-jwt is used in all the old docs and in the example code but it’s not really maintained

You are correct. Apologies for that. I have been conducting internal research and discussion to address this.

the client callback has a bit of black magic to it (dashboard.whatabyte.now.sh) Instead of putting up a now.sh app I would have shown how to set up url-s in the host so anybody could follow and reproduce the example.

The goal of the demo client was to quickly set up a working client without much set up other than creating an Auth0 application. Something like this would be possible down the road. I wanted to also try a "Deploy with… " button or something of that nature. What do you think of the length of the tutorial? haha I didn’t want to make things too long

there is a way to load .env files when starting the app …

Great tip! Thank you!

I personally prefer nodemon but it’s a personal preference

I like it too!

I would not use roles on ui because permissions should define what can be shown.

Another debate that happened I’m taking this part in consideration as well.

on the UI (angular) I had to implement routeguards, link visibility and directive for restriction. It was a bit tricky, would be happy to share how I did it.

It would be interesting to see what you’ve done in Angular for sure. I think NestJS may be more popular with Angular developers because of the feature parity and similar architecture constructs. Thank you!

[konrad.sopala]

Huge kudos for this great write-up Dan!

[tammai]

Hi Dan,
Thanks for your great article. It’s really help me much when learning Nest and Auth0.
I found a tiny typo issue at section Getting User Roles when you explaining how to add roles to the access token:

const accessTokenClaims = context.idToken; // It should be context.accessToken

I’m waiting your next chapters that guide us implement a client application that handle token, refresh token, validate the user roles/permissions if you will.

[dan-auth0]

@tammai Thank you for reading and for your feedback. Yes! I have that typo fixed in the update that I’ll be publishing this week Sorry about that!

[dan-auth0]

Everyone. The updates for these chapters are going to be reviewed this week and we’ll be pushing them as soon as possible. Thank you for your patience We’ve been working hard on taking everyone’s feedback and improving the tutorial.

[konrad.sopala]

Thanks a lot for all the hard work on this Dan!

[zacksinclair]

Hey Dan - checking to see if you could review my previous questions? Thanks in advance!

[dan-auth0]

They have been in my tasks queue for the past weeks. Sorry for the delayed, which was mainly caused by the holiday season and

A few of them will be addressed in the update:

#2 There was a mistake in the language used and I went deep into getting this clarified. We’ll also need to update some documentation.

#3 You are right. The tutorial focus is only on authorization, as such the artifact to use for that process is the access token. The waters became murky because we are introducing authentication indirectly through the demo client as to get a real, production access token. So we do “Add authentication” to the tutorial flow but we don’t implement it. Passport was definitely not needed for this API but I wanted to use it since there is a NestJS module for it. I will be adding an alternative track where you can enforce authorization using a middleware function instead. The ID Token is designed to be consumed by the client application only for tasks like populating user profile data on the UI.

#5 The repo will be shared

Pending for further research and a POC:

#1 I consulted with our Solution Engineers about the use case where permissions may change between calls and how to deal with them. I am working on a POC on the different approaches which they suggested and get them reviewed. We want to be sure we provide you solid guidance on this with security in mind. I can tell you that your approach is not too far apart from one of the proposed strategies. This one will take a bit more time.

#4 Also awaiting review of this answer to relay it to you

You also were right about the PermissionGuard bug! I tested it myself The wires crossed lol It was meant to be:

    const hasPermission = () =>
      routePermissions.every(routePermission =>
        userPermissions.includes(routePermission),
      );

Thank you for bringing it up. That is also part of the update. We want to ensure that all the permissions required by the endpoint as present in the permissions claim of the access_token.

[dan-auth0]

Zach, here’s a preview of what the authz middleware would be like. I’d love your feedback:

https://gist.github.com/dan-auth0/ce63f6dd2cb0ae6c14f0eef6b92171b9

[zacksinclair]

Your JWT middleware is basically identical to mine - I also implemented this w/o passport.

I’m still mildly unclear on the official position on id_token and access_token with regard to authentication. “The ID Token is designed to be consumed by the client application only for tasks like populating user profile data on the UI” - this implies the token must be stored insecurely (ie be accessible to client side javascript) - and is therefore not useable for authenticating a request to the server. If that is the case, access_token would need to be used for authentication, but we’re back to this issue where access_token is supposed to be strictly for authorization.

My implementation is as such:

• id_token, access_token, and refresh token are stored in HTTPS, http-only cookies (and thus unaccessible to client side JS)
• id_token is used to authenticate user in middleware and attach JWT + user object to request for subsequent use in queries etc
• I currently do not use access_token to check permissions and instead call the Auth0 API as described in previous comment. I could switch to access_token, but it brings up in token revocation issue, which has its own inefficiencies and downsides. I know its inefficient to call Auth0 API for every request; I simply cache the response for ~10 minutes, so its not such an issue. Basically, I authenticate user with id_token, then get their permissions from the API.
• To display user data in the UI - I have a graphql get user query that decodes the id_token sent in the cookie and returns the relevant info for display in UI (since the cookie is http only, i need the server to do this). This allows best of both worlds; id_token is securely stored (thus useable for authentication) and still effectively used to display user info in UI.
• I also have a series of decorators that allow authentication and authorization checks for both any given controller and/or any given graphql query/mutation, such that I can require login and/or specific permissions for absolutely anything returned to a client, either via standard REST or Gql

[zacksinclair]

One point about your jwt middleware: you’re calling it AuthZ, but all its doing is validating a JWT - which is AuthN. I keep getting back to this distinction with regard to id_token and access_token and their respective uses for authN vs authZ.

[dan-auth0]

Zach, to better assist you, could you please clarify what you mean by “authenticating a request to the server”?