NOTE: This project has been moved to the @labshare/base-api repository

See: https://github.com/LabShare/base-api/tree/master/packages/services-auth

@labshare/services-auth

Install

npm i @labshare/services-auth

Usage

Register the component and register the configuration for the action by injecting AuthenticationBindings.AUTH_CONFIG.

Configuring the component

Options

Bindings (optional)

To perform additional customization of token validation, you can bind Loopback Providers to the following keys:

Example IsRevokedCallbackProvider

import request = require('request-promise');

export class IsRevokedCallbackProvider {
  constructor() {}

  public async value() {
    return async (
      req: Request,
      payload,
      callback: (error: Error, isRevoked: boolean) => void
    ) => {
      try {
        // ... request to introspection endpoint
        // ... check if token is valid

        callback(null, isTokenRevoked);
      } catch (error) {
        callback(error, false);
      }
    };
  }
}

Example SecretProvider

import { jwk2pem } from 'pem-jwk';

export class SecretProvider {
  constructor(
    @inject('MyJwkService')
    private jwkService: JwkService
  ) {}

  public async value() {
    return async (
      req: Request,
      header,
      payload: any,
      cb: (err: any, secret?: any) => void
    ): Promise<void> => {
      if (!header) {
        log('Invalid JWT. No header found.');
        cb(null, null);
        return;
      }

      if (header.alg !== 'RS256' || !payload || !payload.sub) {
        cb(null, null);
        return;
      }

      try {
        const publicJWK = await this.jwkService.getPublicJWK('...');
        const secret = jwk2pem(publicJWK);

        cb(null, secret);
      } catch (error) {
        cb(null, null);
      }
    };
  }
}

Example AudienceProvider

export class SecretProvider {
  constructor(
    // Constructor can inject services used to figure out which audience to use
    @inject(RestBindings.Http.REQUEST)
    public request: Request
  ) {}

  public async value() {
    // Determine the audience the JWT should be validated against, perhaps based on a value in the API request
    return 'https://some.new.audience';
  }
}

Application Bootstrap Example

import { LbServicesAuthComponent } from '@labshare/lb-services-auth';
import { SecretProvider } from 'secret.provider';
import { AudienceProvider } from 'audience.provider';
import { IsRevokedCallbackProvider} from 'is-revoked-callback.provider';

app = new Application();
app.component(LbServicesAuthComponent);
app.bind(AuthenticationBindings.AUTH_CONFIG).to({
  authUrl: 'https://a.labshare.org/_api',
  tenant: 'my-tenant'
});

// Assign a custom JWT secret provider (optional)
app.bind(AuthenticationBindings.SECRET_PROVIDER).toProvider(SecretProvider);

// Assign a custom revoked JWT check (optional)
app.bind(AuthenticationBindings.IS_REVOKED_CALLBACK_PROVIDER).toProvider(IsRevokedCallbackProvider);

// Assign a custom audience provider (optional)
app.bind(AuthenticationBindings.IS_REVOKED_CALLBACK_PROVIDER).toProvider(AudienceProvider);

Actions

Authenticate

Inject the authenticate action into the application sequence to require the user to pass a valid bearer token and optionally validate the bearer token's scope and audience claims. Ensure the authenticate action runs before the controller methods are invoked (see the example).

Example

import {
  AuthenticationBindings,
  AuthenticateFn
} from "@labshare/lb-services-auth";

class MySequence implements SequenceHandler {
  constructor(
    @inject(SequenceActions.FIND_ROUTE) protected findRoute: FindRoute,
    @inject(SequenceActions.PARSE_PARAMS)
    protected parseParams: ParseParams,
    @inject(SequenceActions.INVOKE_METHOD) protected invoke: InvokeMethod,
    @inject(SequenceActions.SEND) protected send: Send,
    @inject(SequenceActions.REJECT) protected reject: Reject,

    // Inject the new authentication action
    @inject(AuthenticationBindings.AUTH_ACTION)
    protected authenticateRequest: AuthenticateFn,
  ) {}

  async handle(context: RequestContext) {
    try {
      const {request, response} = context;
      const route = this.findRoute(request);

      // Authenticate the request. We need this sequence action to run before "invoke" to ensure authentication
      // occurs first.
      await this.authenticateRequest(request as any, response as any);

      const args = await this.parseParams(request, route);
      const result = await this.invoke(route, args);
      this.send(response, result);
    } catch (error) {
      this.reject(context, error);
      return;
    }
}

User Info

Inject the user info action provider into your application sequence to assign the user's profile on request.userInfo. The profile corresponds to the response returned by LabShare Auth's OIDC user_info route.

Example

import {
  AuthenticationBindings,
  AuthenticateFn
} from "@labshare/lb-services-auth";

class MySequence implements SequenceHandler {
  constructor(
    @inject(SequenceActions.FIND_ROUTE) protected findRoute: FindRoute,
    @inject(SequenceActions.PARSE_PARAMS)
    protected parseParams: ParseParams,
    @inject(SequenceActions.INVOKE_METHOD) protected invoke: InvokeMethod,
    @inject(SequenceActions.SEND) protected send: Send,
    @inject(SequenceActions.REJECT) protected reject: Reject,

    // Inject the new authentication action
    @inject(AuthenticationBindings.USER_INFO_ACTION)
    protected setUserInfo: AuthenticateFn,
  ) {}

  async handle(context: RequestContext) {
    try {
      const {request, response} = context;
      const route = this.findRoute(request);

      // Set the userInfo on the request
      await this.setUserInfo(request as any, response as any);

      const args = await this.parseParams(request, route);
      const result = await this.invoke(route, args);
      this.send(response, result);
    } catch (error) {
      this.reject(context, error);
      return;
    }
}

Decorators

@authenticate

Use the @authenticate decorator for REST methods or controllers requiring authentication.

Options

Dynamic Scopes

Dynamic path/query parameters can be injected into scope definitions using brackets. For example: [read:users:{path.id}, update:users:{query.limit}] assigned to a route such as /users/{id} would require the request's bearer token to contain a scope matching the id parameter in the route (for example: 'read:users:5' if the request route is /users/5).

Example

import { authenticate } from "@labshare/lb-services-auth";
import { Request } from "@loopback/core";

// Attach the decorator at the controller level to require authentication on all methods
// and a scope of `my:shared:scope`
@authenticate({
  scope: 'my:shared:scope'
})
class MyController {
  constructor(
    @inject(RestBindings.Http.REQUEST) public request: Request
  ) {}

  @authenticate()
  @get('/whoAmI', {
    'x-operation-name': 'whoAmI',
    responses: {
      '200': {
        description: '',
        schema: {
          type: 'string',
        },
      },
    },
  })
  async whoAmI(): Promise<string> {
    return 'authenticated data';
  }

  // This route supports both authenticated and anonymous requests
  @authenticate({
    credentialsRequired: false
  })
  @get('/resource', {
    'x-operation-name': 'resource',
    responses: {
      '200': {
        description: '',
        schema: {
          type: 'string',
        },
      },
    },
  })
  async resource(): Promise<string> {
    if (this.request.user) {
      return 'Resource requiring authentication';
    }

    return 'Public resource';
  }

  // This route has an additional Resource Scope requirement. The user's bearer token will need to contain
  // 'read:users' in the `scope` claim. Otherwise, they will receive a 403 in the response.
  @authenticate({
    scope: ['read:users']
  })
  @get('/users', {
    'x-operation-name': 'users',
    responses: {
      '200': {
        description: '',
        schema: {
          type: 'string',
        },
      },
    }
  })
  async users(): Promise<string> {
    return 'users';
  }

  // This route has a dynamic scope parameter for validation.
  // The request will be unauthorized if the JWT does not contain the "tenantId", "someOtherParam" values in the route path and the "someParam" query parameter.
  @authenticate({
    scope: ['{path.tenantId}:read:users:{query.someParam}:{path.someOtherParam}']
  })
  @get('{tenantId}/users')
  async users(
    @param.path.string('tenantId') tenantId: string,
    @param.path.number('someOtherParam') someOtherParam: number,
    @param.query.boolean('someParam') someParam: boolean
  ): Promise<string> {
    return `${tenantId} users';
  }
}

app.controller(MyController);