@makemydeal/dr-auth-utilities

This is a package to help with managing authorization and authentication within DR applications. This will assist with JWT Token Verification, Scopes Verification, Policy Document creation for API Gateway, etc.

VerifyTokenManager

In order to use VerifyTokenManager, you need to instantiate a copy of the class.

const vtm = new VerifyTokenManager();

This was done as a class so it can "manage it's own state." In an effort to speed up JWT Token Verifications along with Signing Verification, we only want to request the PEM once. This operation is async, so we would not want each request to slow down the application.

verify

This will verify an encoded token by checking against the SigningKey and other optional settings. It will also check if the token is Expired against the current date.

Options

| Parameter | Required | Description | --- | --- | --- | jwksUri | Yes | Location of the JWKS URI in order to acquire the SigningKey | encodedToken | Yes | The token to decode | options | No | Options that can be set when verifying the token. See IVerifyOptions

IVerifyOptions

| Options | Description | --- | --- | audience | To verify the audience against a known audience or audiences, pass the value here | issuer | To verify the issuer against a known issuer or issuers, pass the value here | algorithms | The algorithms used to encode the token. RS256 for example. You shouldn't need this option | ignoreExpiration | Pass TRUE to not validate the token against expiration | clockTolerance | If you wish to provide a "buffer", pass it here. For instance, if you want the token to be determined to be expired if we are within 30 seconds of expiration, pass 30 here.

verifyFromEvent

This function will perform the same operation as the verify function. However, instead of passing in the encodedToken, you will pass in the ITokenAuthorization object that comes from API Gateway. The function will then get the encodedToken and pass it to verify for the results.

decode

If you wish to decode a token, and check it against the criteria in IVerifyOptions, but you do not wish to verify against the SigningKey, then use this function

Options

| Parameter | Required | Description | --- | --- | --- | encodedToken | Yes | The token to decode | options | No | Options that can be set when verifying the token. See IVerifyOptions

OAuthTokenManager

This manager will request OAuth tokens and cache them for later used. It will check their expiration date with a 15m buffer and if they are expired, will also request a new token.

get

This method takes in the following parameters:

• clientId
• clientSecret
• scope - the scopes requested
• tokenEndpoint - the tokenEndpoint to use

With these parameters, it will check its cache, and if there is valid token, it will return this immediately. If it does not exist, or that token is no longer valid, it will make a request to tokenEndpoint using the clientId, clientSecret and scope as parameters to get a new token, cache it, and return it back.

considerations

The goal of this class is to allow you to instantiate it in the global space of a lambda, while calling get in the handler function. This handler function will most likely receive its configuration from the ConfigurationManager. This is why it does not take these parameters in during instantiation of the class.

const tokenManager = new TokenManager();

const handler = async (event, context) => {
    const token = await tokenManager.get({ clientId: 'clientId', clientSecret: 'secret', scope: 'scope', tokenEndpoint: 'https://tokenendpoint.com' });
    console.log(`the token was: ${token}`);
}

apiGateway

This object contains helpers to work with API Gateway method ARNs

parseMethodArn

This method will take a methodArn and parse it into it's parts.

createMethodArn

This method will take the parts of a methodArn and construct the arn. This is helpful for creating methodArns with wildcards

scopes

This object has tools for checking scopes against a known list

every

This method will tell you if every scope in the known list is in the token

some

This method will tell you if at least one scope in the known list is in the token

policyDocument

This object contains tools to create a PolicyDocument for API Gateway Authorizers

create

Given a set of resources, this will create the policy document. If the resources list is empty, or undefined, it will return a policy to deny access

createReadWrite

Given the token, the methodArn from the authorizer and a set of options, this will create the policy document. The options define the readScopes (scopes for read access), writeScopes (scopes for write access), readVerbs (verbs for read, defaults to GET) and writeVerbs (verbs for write, default to ['POST', 'PUT', 'PATCH])