@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

| Property | Type | Details |
| :------- | :----: | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| tenant | string | The LabShare Auth Tenant the Resource Server (API) is registered to. Example: ncats. |
| authUrl | string | The full URL to the LabShare Auth API the Resource Server (API) is registered to. Example: https://a.labshare.org |
| audience | string | The audience of the Resource Server. This is a unique identifier for the API registered on the LabShare Auth Service. It does not need match an actual API deployment host. This is required to check if a Client (application) is allowed to access the API. Example: https://my.api.com/v2. Optional. |
| issuer | string | The issuer of the Bearer Token. Use this to validate the source of the Bearer Token. Optional. Example: https://a.labshare.org/_api/ls |

Bindings (optional)

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

| Binding | Details |
| :---------------------------------------------------- | :-----------------------------------------------------------------------------------------------------------------------------------------------------------------: |
| AuthenticationBindings.SECRET_PROVIDER | Obtains the secret used to validate the JWT signature. Not required when using tokens signed by LabShare Auth. |
| AuthenticationBindings.IS_REVOKED_CALLBACK_PROVIDER | Used to check if the token has been revoked. For example, a request to the introspection_endpoint can check if the JWT is still valid. |
| AuthenticationBindings.AUDIENCE_PROVIDER | Provides the value for the audience the JWT will be validated against instead of using the audience configuration assigned to AuthenticationBindings.AUTH_CONFIG. |

$3

``ts
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);
}
};
}
}
`

$3

`ts
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 => {
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);
}
};
}
}
`

$3

`ts
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

`ts
import { LbServicesAuthComponent } from "@labshare/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

$3

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

`ts
import {
AuthenticationBindings,
AuthenticateFn
} from "@labshare/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;
}
}
`

$3

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

`ts
import {
AuthenticationBindings,
AuthenticateFn
} from "@labshare/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

$3

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

Options

| Property | Type | Details |
| :------------------ | :-----: | :--------------------------------------------------------------------------------------------------------- |
| scopes | array | A list of one zero or more arbitrary Resource Scope definitions. Example: ['read:users', 'update:users'] |
| credentialsRequired | boolean | Set to false to support anonymous/public requests on an endpoint. Defaults to true. |

$3

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

`ts
import { authenticate } from "@labshare/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 {
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 {
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 {
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 {
return ${tenantId} users';
}
}

app.controller(MyController);
```

Contributors

See all contributors.

License

MIT