oauth-client-nestjs

This package includes client oauth authentication module based upon NestJS framework.
This package includes vcita authentication, and can also interact with additional providers.

Content

Using this package you will be able to:

1. Authenticate incoming requests

   • Internal services: with the internal token generated by the IdP (Identity Provider)
   • External services (apps):
     1. Using the Oauth grant flow (authorizing the service to make changes for logged-in user)
     2. Using cookies for stateful keeping the user information

        :warning:   Usage of cookies will be deprecated.

2. Object allowing to make requests to vCita's services (AKA consuming Platform API's) safely through the API-GW

   1. Internal services
   2. External services

3. Utilities for rapid testing and developing

   1. Authentication mocking on testing environments
   2. Simplified authentication mechanism for development environments

Glossary

• Oauth grant flow:
  A series of steps defined by the Oauth 2.0 protocol allowing a user to give an external application access to a resource he owns in a different application.
  
• Platform API(s):
  APIs exposed by the API-GW and are consumed by both vCita's hosted apps/services and 3rd party apps/services.
  
• Internal Service:
  A service which is part of the vCita's eco-system and exposes Platform APIs via the API-GW.
  
• Application:
  A service which not part of the vCita eco-system.
  • It may be hosted by vCita or by a 3rd party host.
  • It may be created by vCita or by a 3rd party developer.
  • It may have frontend which could hosted in vCita's SaaS website.
  • It may consume Platform APIs.
  • Users must authorize apps to preform actions on their behalf using the Oauth-grant-flow.

Installation

1. Install this package using npm in your NestJS app.

   npm install @vcita/oauth-client-nestjs

2. You must have these env variables available on your application (accessible through process.env.<env-var>):
   You may do so by adding them to your .env.

   :bulb:   When opening a project from template, you will only need to add values or make sure they are filled correctly

   :lock_with_ink_pen:   When deploying your project, some values will be overridden with deployment secrets (this is good)

| Env var | Explanation | Development Value | Deployment Overridden | |--------------------|------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------|---------------------| | OAUTH_CLIENT_ID | String representing oauth application uid | Obtained when registering app | Yes | | OAUTH_CLIENT_SECRET | String representing oauth application secret | Obtained when registering app | Yes | | OAUTH_SERVER | URL of frontend oauth-grant-flow start (frontage). | http://localhost:7200/app/oauth/authorize | Yes | | OAUTH_REDIRECT_URI | URL of redirection in a oauth-grant-flow | Location of your service in development. Example: http://localhost:47745 | Yes | | API_GW_SERVER | URL of vCita's API-GW | Will be explained in section | Yes | | AUTHORIZATION_SERVER | URL of vCita's Authorization Server | http://localhost:7100 | Yes | | CUSTOM_ENTITIES | Array of location(s) of additional entities | ["/home/node_modules/@vcita/oauth-client-nestjs/dist/oauth/**/*.entity.js","./node_modules/@vcita/oauth-client-nestjs/dist/oauth/**/*.entity.js"] | No |

Migration

After the package installation, you must generate and run a new migration for oauth module - migration docs

Usage

To use the package content we must first import the OauthModule into our root module (AppModule for most cases).
This is a dynamic module, use it you should call register method and supply object complying with ApplicationConfig interface.

OauthModule.register({ mainRoute: '' })

mainRoute - the default route to redirect to after OAuth completed.

:warning:   Note!
The interface will be changed on version 2.0.0

Consuming Platform APIs

Internal Services

As an Internal Service you have 2 options to consume a Platform API:

1. Make a request on behalf of the service itself.
   Example: The service needs to update some other service with it's current state.
   
2. Make a request on behalf of some user (staff, client etc...).
   Example: The service needs to change the calendar of the user, yet Calendars are the responsibility of a different service.

To consume Platform APIs you must use the InternalProxyService object - a provider exported by the OauthModule.
To use the provider you must declare it as a dependency of the consuming class so NestJS would inject it at initialization.

@Processor('channels')
export class ChannelsProcessor extends BaseProcessor { // consuming class
   constructor(
           private readonly internalProxy: InternalProxyService, // NestJS will inject the `InternalProxyService` fatory object 
   ) {
     super();
   }
}

:bulb:   Now ChannelProcessor object is automatically injected with InternalProxyService intance when NestJS framework initializes.

This object exposes methods for making an HTTP requests: getRequest, postRequst, putRequest, deleteRequest for proper usage.
Those methods can be used for both Platform API consuming by simply giving the last argument actingAs.
Examples:

// Request example fitting option 1 
import { ActorType } from "@vcita/oauth-client-nestjs";

this.internalProxy.getRequest<ResponseDataType>(
  'platform/v1/test', 
  6, 
  { query_param: 'some value' }
)


/* Reuest example fitting option 2
 * Note this invocation contains another argument to the same method!
 * This argument is the `actingAs` argument
 */
this.internalProxy.getRequest<ResponseDataType>(
  'platform/v1/test', 
  6, 
  { query_param: 'some value' }, 
  actor.getActingAs(ActorType.STAFF)
)

:bulb:   Each HTTP request method have a different interface, but they all allow the actingAs optional argument. Also notice that without the optional argument given, the default behaviour is of option 1!

Applications

:warning:   Note!
This section is not final and might be subject to various changes in the next version.

As an application you must use the OAuthHttpAppService.
To obtain this object you must declare it's factory object OauthHttpService as a dependency of the consumer.
OauthHttpService is a provider exported by the OauthModule.
Example:

@Injectable()
export class ConnectorService { // Consumer class
  private vcitaOauthHttpService: OAuthHttpAppService;

  constructor(
    httpClient: OauthHttpService, // NestJS will inject the `OAuthHttpAppService` fatory object
  ) {
    this.vcitaOauthHttpService = httpClient.getInstance('vcita'); // Getting the proper instance to consume vCita's Platform APIs
  }

  async doWork(staffUid: string, path: string) {
    const platformApiAns = await this.vcitaOauthHttpService.getRequest(
      staffUid,
      path,
    );

    return 'Answer from Platform Api is: ' + platformApiAns.toString();
  }
}

Internal Services Consuming External APIs

There are cases where an internal service will need to call some external api.
We provide a way for the external api to authenticate that some arbitrary incoming API request was made by vCita's eco-system (one of vCita's internal services to be exact).
Example use case:

1. vCita needs to inform external application A about some operation that happened (a webhook)
2. A receives an API request.
   How will A know that the incoming request was made by vCita?

Some external application/service might not care, but those who do care we offer a mechanism for authenticating.

TBD