DEV Community: Marcus

Spotify OAuth2 Authentication in a NestJS Application

Marcus — Sun, 20 Mar 2022 15:46:25 +0000

Integrate an OAuth2 authorization code flow strategy for the Spotify Web API in a NodeJS with TypeScript and NestJS back end application

When building an API, one of the most important parts of the application is the security and authentication of its users. Most frameworks provide some guidelines on how to implement different authentication strategies. NestJS, for instance, presents, in its official documentation, the JWT strategy.

However, one widely spread authentication strategy is the OAuth2 approach, usually used with 3rd party services such as Facebook, Google and Spotify accounts which provides a way to use an existing account in these services to authenticate the user and even interact with these services on behalf of the authenticated user.

As there is no official documentation for integrating this type of authentication with NestJS and development articles usually focus on Google and Facebook integration, this article presents an alternative to integrate the Spotify Authorization Code Flow with NestJS using the Passport authentication middleware along with the passport-spotify strategy.

Requirements

This article focuses on the process of using the OAuth2 strategy for Spotify integrated with a NestJS application, therefore, the following requirements are considered to be fulfilled before the process described in this article:

A NestJS application bootsraped with its basic structure. For this part, it is sufficient to follow the quick setup guide in the NestJS documentation;
A Spotify account with access to the Spotify Developer Dashboard and an app registered with its CLIENT ID and CLIENT SECRET credentials. Following the step-by-step official documentation on how to use the Spotify API is sufficient for this article.

If you are not familiar with the OAuth2 Authorization Code Flow, please check the guide provided by the Spotify Web API documentation.

The auth folder

With a NestJS application ready, an auth resource must be created using the following command - considering that the Nest CLI is installed in the machine:

nest g mo auth
nest g s auth --no-spec
nest g co auth --no-spec

Those commands create an auth folder with basic module, service, and controller files without any .spec files. With all in place, the folder structure should look like this:

Now, the following dependencies must be installed:

npm install @nestjs/passport @nestjs/jwt passport passport-jwt passport-spotify
npm install -D @types/passport-jwt @types/passport-spotify

From now on, there are 3 functionalities that must be available in the application in terms of authentication:

Login of users using the Spotify OAuth2 authorization code flow;
Retrieving the user's info from Spotify and generate a JWT;
Using the JWT strategy so that there is no need for connecting with the Spotify OAuth2 server every time there's a need for user authentication in during a session.

The routes

For the first and second functionalities described earlier, there needs to be a controller with the routes '/login' and '/redirect':

The above code comprehends the following:

Both routes, '/login' and '/redirect' are guarded with the SpotifyOauthGuard custom guard which implements the passport-spotify strategy that will be described later;
The login method/route is the endpoint that users will access to initiate the authentication;
The spotifyAuthRedirect method ('/redirect' route) is the URL to which the Spotify OAuth2 service will be redirected once the user successfully logs in;
The spotifyAuthRedirect method: retrieves the user's information coming from Spotify located the req.user property - if there is no info, meaning the authentication wasn't performed or failed, the method redirects the request to the login route again - sets the user req property to undefined (as it is will be defined as the JWT payload further), generates a JWT with it, and returns the user's info and Spotify tokens that can be used by the application to access routes in the Spotify Web API using the user's info depending on the scopes defined.

The Spotify OAuth2 strategy

When using a built-in passport strategy, a custom guard mustbe created and also its corresponding strategy. The SpotifyOauthGuard is simply a class that extends the AuthGuard class, so, after creating a /guards folder, inside it, the SpotifyOauthGuard should look like this:

Also, the named spotify strategy must be created inside a /strategies folder:

The above code is responsible for connecting with the Spotify OAuth2 service and managing the redirection to the application. The process is:

The SpotifyOauthStrategy class extends the PassportStrategy using the strategy provided by the passport-spotify lib and name it 'spotify' so the SpotifyOauthGuard can identify it;
The constructor method calls the passport-spotify Strategy constructor method using the super method, passing the Spotify app credentials CLIENT_ID and CLIENT_SECRET(saved in .env vars as they must not be exposed publicly), better described here, a callback URL which is the same route defined in the auth.controller.ts, '/redirect', and the scopes that the app needs for interacting with the user's information;
The super method also has a callback function, that will be called as soon as the user's login process succeeds and before it is redirected to the application. This function adds to the request that will be made to the '/redirect' route the following properties: user (containing the user's profile info) and authInfo (containing the refreshToken, accessToken and expires_in info).

The redirection and JWT generation

Once the strategy is implemented, the user will be redirected to the /redirect URL, and, in auth.controller.ts (presented earlier), the spotifyAuthRedirect method will intercept the req object and extract the user and authInfo properties and pass the user to the authService. With the user's info, the login method in the AuthService class is responsible for generating the JWT. The auth.service.ts should look like:

Finally, in auth.service.ts, the '/redirect' route returns an object containing the authInfo and user properties as well as a header Authentication set to 'Bearer ' concatenated with the JWT.

The JWT strategy

This part of the authentication is basically as described in the official NestJS documentation. For this part, there needs to be defined in your .env vars a JWT_SECRET, which is a string that is used to generate and encrypt/decrypt the JWT's that the application generates and must not be exposed publicly. Similar to the Spotify strategy, it's necessary to create a JwtAuthGuard class that extends the built-in passport AuthGuard along with a corresponding, named 'jwt'. Inside the /guards folder, create the jwt-auth.guard.ts file as the following:

And the corresponding strategy, inside the /strategies folder, should look like:

The above code is executed when a route is decorated with the JwtAuthGuard. The super method extracts the JWT provided by the request to a guarded route, decrypts it with the JWT_SECRET provided and inserts a user property into the req object containing the info that was previously inserted into the payload of the JWT.

It's important to highlight that the inserted user property is not the same that the spotify-strategy inserts to the req object, and this is the reason why in the spotifyAuthRedirect method, the req.user property is set to undefined before the sign in with the jwt strategy.

Now any authenticate route can be decorated with the JwtAuthGuard as the following:

The AuthModule and AppModule Configs

With everything in place, it's time to configure the instantiation of all the modules. The AuthModule class should look like this:

The auth.module.ts file defines all the providers of the auth resource and registers the JWT_SECRET during the instantiation of the JwtModule as well as the expiration time for it, here defined as 3600s (1 hour).

Also, the AppModule should look like:

The app.module.ts instantiates all the modules of the application including the ConfigModule, which is necessary for using all the env vars described in the process.

The final state of the folders and files of the application should look like this:

Conclusion

The OAuth2 is an interesting way of integrating an application with external apps such as widespread social media services, taking advantage of an easy way to log users as well as providing functionalities to the users related to these apps.

Even though NestJS does not provide an official way of making this kind of integration, there are many open source projects that aims to make it easier this authentication method such as the ones described and used in this article.

Credits

Cover image by Alexander Shatov on Unsplash

Integrate Node.js Client for Google Maps Services With a NestJS Application

Marcus — Sat, 19 Mar 2022 00:15:28 +0000

Wrapping the NodeJS client for Google Maps Services in a NestJS app

A common doubt that comes to mind when building a NestJS application is the proper way to implement some functionality respecting the framework architecture to take full advantage of the scalability it provides.

This article's main goal is to propose a way of wrapping the NodeJS client for Google Maps Services in a NestJS module and use dependency injection to make it easy to reuse across the application. Although this article uses specifically the @googlemaps/google-maps-service-js npm package, it may be used as inspiration for other client based external services.

NestJS framework

NestJS is a framework for creating scalable and loosely coupled server-side NodeJS applications. One of its main characteristics is the implemented architecture and directory structure, which reinforces the modularized nature of the application. On top of that, NestJS fully supports TypeScript and also works with Express and Fastify under the hood, which makes it an up-to-date and viable alternative framework for building a reliable web server with well-known tooling.

The framework architecture

As stated in the NestJS documentation, its architecture is heavily inspired by Angular's architecture. The folder structure is basically organized in modules that represent some entity that binds a specific context of the application. Each module is commonly composed by the files app.module.ts, app.controller.ts, and app.service.ts. The common folder structure for a module looks like this:

google-maps | - google-maps.controller.ts | - google-maps.module.ts | - google-maps.service.ts

Node.js Client for Google Maps Services

The client for google maps service is a library created to interact with the Web API provided by Google directly from a given project's programming language, in this case, TypeScript with NodeJS.

Given that the @googlemaps/google-maps-service-js npm package provides many recurrently used methods and classes, one way to use dependency injection with this service is to wrap the google maps service client inside a getter method in a module class along with the most used methods to better serve the application.

Wrapping the library in a module

The google-maps module folder is composed simply by a module.ts file and a service.ts file, which contains a client getter and other most used methods. The service would then look like this:

The above code is composed by the following functionalities, using an OOP approach:

The GoogleMapsService class extends the default Client class and calls the super() method to instantiate it in order to use all its methods and properties;
A private propertie is declared to store the access Key that is required to access the google api service;
The accessKey is retrieved from an environment variable for security reasons, using the built-in NestJS service ConfigService;
In this example, an async method called getCoordinates is defined to get latitude and longitude values from a given address using the .geocode method which communicates with its web service API relative;
Given that the application is using TypeScript, the package also provides custom types for the library so it is possible to define the type of the returned value for the method created as LatLngLiteral.

The whole structure of the service above is well described in its dedicated section in the NestJS documentation.

Since the application described in this article does not provide any external route to interact with the service presented above, there is no controller.ts file to handle external requests.

As for the module file, it is responsible for binding all files related to a given context and also to be injected in other modules. More on this section can be found in the NestJS documentation. The google-maps.module.ts looks something like the following:

The above code defines the service created as a provider and exports it so that it can be reused in other modules.

Dependency injection

Lastly, it is required that the google-maps module created is declared inside the module that uses the google-maps service and then uses dependency injection on the class that uses the google-maps service methods. Other modules would look like this:

And then, for the DI at service level:

The above code uses the NestJS dependency injection format to use the google-maps service created and also the google-maps types to define the returned value of the getAddressCoords method.

Conclusion

As discussed before, it is interesting to write code in a modularized way in scalable applications with multiple entity scopes.

Considering the described scenario, the application presented in this article shows a way of modularizing external services, making the code more reusable, and concentrating context-related methods and values in the same module.

Credits

Cover image by Ilya Pavlov on Unsplash