pae-microservices-runtime-sdk

Provides utilities to create PAE microservices related to the PAE architecture such as Authentication, Authorization, Impersonation, etc.

Middlewares

It provides a set of middlewares to intercept microservices routes

auth()

This middleware checks that the user is authenticated. If not then it returns 403 Forbidden. If the user is authenticated (has a session) then it modifies req.user to set the current user's session

ExpressJS

Sample usage with ExpressJS

const { middlewares } = require('@bluealba/pae-microservices-runtime-sdk')

// WARNING: you must have cookieParser middleware in place !
app.use(cookieParser())

// Here we set the middleware for a specific route
app.get('/', middlewares.auth(), (req, res) => {
  res.json({
    message: "hello",
    user: req.user, // and after that we can access req.user
  })
})

Notice that you must have cookieParser in place for this to work. Otherwise the middleware will always reject with 403.

NestJS

Sample usage with NestJS

import { MiddlewareConsumer, Module, NestModule } from '@nestjs/common';
import cookieParser from 'cookie-parser';
import microservices from '@bluealba/pae-microservices-runtime-sdk';

import { AppController } from './app.controller';
import { AppService } from './app.service';

@Module({
  imports: [],
  controllers: [AppController],
  providers: [AppService]
})
export class AppModule implements NestModule {
  configure (consumer: MiddlewareConsumer) {
    // Again here we need cookieParser first
    consumer
        .apply(cookieParser())
        .forRoutes('/time');
    // then setup the PAE auth middleware
    consumer
        .apply(microservices.middlewares.auth())
        .forRoutes('/time');
  }
}

In this case we are protecting the /time endpoint of the module.

If you want to set the middleware globally for all routes of a module you can do

const app = await NestFactory.create(AppModule);
app.use(cookieParser);
app.use(microservices.middlewares.auth());

See NestJS Global Middlewares

User Object Shape

The injected req.user object has the following type, which is a core type of PAE shared by

• pae-authentication-service: which is the one that creates the object and stores the session
• this library: which consumes the session
• pae-orchestrator-service: which does a similar job as this middleware but to inject the same object into every microfrontend application

export type Session = {
  id: string;
  
  /**
   * The unique user name
   */
  username: string;
  
  /**
   * A human-friendly name
   */
  displayName: string;

  /**
   * The original User object as returned by the Identity Provider.
   */
  orig: unknown;

  /**
   * The code name of the authentication Identity Provider. For example: okta, github, cognito, etc.
   */
  authProviderName: string;

  /**
   * The list of allowed operations in terms of PAE Authorization.
   */
  operations: string[];
  
  /**
   * It the user is being impersonated by another user then it contains information about the real impersonating User.
   */
  impersonatedBy?: {
    username: string;
    displayName: string;
  }

  /**
   * Internal Identity Provider session tokens.
   * This doesn't apply to Basic Authentication but for all other OAuth methods.
   */
  tokens?: {
    access_token: string;
    id_token: string;

    token_type?: string;
    expires_in?: number;
    scope?: string;
    refresh_token?: string;
  },
};

Here is a sample req.user object

{
  "authProviderName": "okta",
  "displayName": "Javier Fernandes",
  "username": "[email protected]",
  "operations": [
    "operation-1", "operation-2", "operation-3", "operation-4"
  ],
  "orig": {
    "sub": "99dasff0pOzmPQg1234",
    "name": "Javier Fernandes",
    "locale": "AR",
    "nickname": "Javier",
    "preferred_username": "[email protected]",
    "given_name": "Javier",
    "family_name": "Fernandes",
    "zoneinfo": "America/Argentina/Buenos_Aires",
    "updated_at": 1711637822
  },
  "tokens": {
    "token_type": "Bearer",
    "expires_in": 3600,
    "scope": "offline_access profile openid",
    "access_token": "SOME_TOKEN",
    "id_token": "SOME_TOKEN",
    "refresh_token": "SOME_TOKEN"
  },
  "iat": 1717441563,
  "exp": 1717527963
}