Lib-oauth-tooling NPM

lib-oauth-tooling

A simple typescript based library for supporting OAuth2 flows. Currently the following flows are supported:

Authorization Code Flow
Resource Owner Password Credentials Grant
Refresh token Grant
Express middlewares to simplify authentication/authorization
TokenCache service to manage access tokens in your application

See STUPS documentation and OAuth2 documentation for more information.

Migrating to 2.x.x

If you depend on the realm property you now have to pass the value via the queryParams parameters in OAuthConfig:

// will NOT work anymore:
getAccessToken({
  // all the other config
  // ...
  realm: EMPLOYEES_REALM,
})
.then(token: Token => {
  // ...
});

// instead use this:
getAccessToken({
  // all the other config
  // ...
  queryParams: { realm: '/employees' }
})
.then(token: Token => {
  // ...
});

See the changelog for more information.

Usage

Note: node >= 6.0.0 required to consume this library.

Run npm install lib-oauth-tooling.

Import a member of this lib like so (of course ES5 syntax is working as well...):

import {
    TokenCache,
    handleOAuthRequestMiddleware,
    requireScopesMiddleware,
    ...
} from 'lib-oauth-tooling';

TokenCache(tokenConfig: { key: string: string[] }, oauthConfig: OAuthConfig)

Class to request and cache tokens on client-side.

const tokenCache = new TokenCache({
  'service-foo': ['foo.read', 'foo.write'],
  'service-bar': ['bar.read']
}, oAuthConfig);

tokenCache.get('service-foo')
.then((token: Token) => {
  console.log(token.access_token);
});

oauthConfig:

credentialsDir string
grantType string (AUTHORIZATION_CODE_GRANT | PASSWORD_CREDENTIALS_GRANT)
accessTokenEndpoint string
tokenInfoEndpoint string - mandatory for TokenCache
scopes string[] optional
queryParams {} optional
redirect_uri string optional (required with AUTHORIZATION_CODE_GRANT)
code string optional (required with AUTHORIZATION_CODE_GRANT)

handleOAuthRequestMiddleware(options: MiddlewareOptions)

Express middleware to extract and validate an access token. It attaches the scopes matched by the token to the request (request.scopes) for further usage. If the token is not valid the request is rejected (with 401 Unauthorized).

app.use(handleOAuthRequestMiddleware({
    publicEndpoints: ['/heartbeat', '/status'],
    tokenInfoEndpoint: 'auth.example.com/tokeninfo'
});

options:

publicEndpoints string[]
tokenInfoEndpoint string

requireScopesMiddleware(scopes: string[])

Specifies the scopes needed to access an endpoint. Assumes that there is an request.scopes property (as attached by handleOAuthRequestMiddleware) to match the required scopes against. If the the requested scopes are not matched request is rejected (with 403 Forbidden).

app.get('/secured/route', requireScopesMiddleware(['scopeA', 'scopeB']), (request, response) => {
    // do your work...
})

getTokenInfo(tokenInfoEndpoint: string, accessToken: string): Promise

Makes a request to the tokenInfoEndpoint to validate the given accessToken.

getTokenInfo(tokenInfoEndpoint, accessToken)
.then((token: Token) => {
  console.log(token.access_token);
})
.catch((err) => {
  console.log(err);
});

Type Token is defined like:

interface Token {
  access_token: string;
  expires_in?: number;
  scope?: string[];
  token_type?: string;
  local_expiry?: number;
  [key: string]: {};
}

getAccessToken(options: OAuthConfig): Promise

Helper function to get an access token for the specified scopes.

getAccessToken(options)
.then((token: Token) => {
  console.log(token.access_token);
})
.catch((err) => {
  console.log(err);
});

options:

credentialsDir string
grantType string (AUTHORIZATION_CODE_GRANT | PASSWORD_CREDENTIALS_GRANT | REFRESH_TOKEN_GRANT)
accessTokenEndpoint string
scopes string optional
queryParams {} optional
redirect_uri string optional (required with AUTHORIZATION_CODE_GRANT)
code string optional (required with AUTHORIZATION_CODE_GRANT)
refreshToken string optional (required with REFRESH_TOKEN_GRANT)

AUTHORIZATION_CODE_GRANT

String constant specifying the Authorization Code Grant type.

PASSWORD_CREDENTIALS_GRANT

String constant specifying the Resource Owner Password Credentials Grant type.

REFRESH_TOKEN_GRANT

String constant specifying the Refresh Token Grant type.

Mock tooling

If you want to test oAuth locally without being able to actually call real endpoints this library provides some tooling.

mockTokenInfoEndpoint(options: MockOptions)

Mocks a tokeninfo endpoint.

mockTokeninfoEndpoint({
  url: 'http://some.oauth.endpoint/tokeninfo',
  tokens: [{
    access_token: 'someToken123',
    scope: ['uid', 'something.read', 'something.write']
  }],
  times: 1
});

options:

url string (url of the tokeninfo endpoint)
tokens any optional (list of valid tokens)
times number optional (for how many times/calls the endpoint is mocked, default is Number.MAX_SAFE_INTEGER)

mockAccessTokenEndpoint(options: MockOptions)

Mocks a access_token endpoint.

mockAccessTokenEndpoint({
  url: 'http://some.oauth.endpoint/access_token',
  times: 1
});

options:

url string (url of the access_token endpoint)
times number optional (for how many times/calls the endpoint is mocked, default is Number.MAX_SAFE_INTEGER)

cleanMock()

Cleans all nock mocks (not only from this lib, really ALL) and given tokens. Helpful when having multiple tests in a test suite, you can call cleanMock() in the afterEach() callback for example.

cleanMock();

Development

clone this repo
npm install
to build: tsc
to lint: npm run tslint

Testing

npm test - runs all tests
npm run unit-test - runs unit tests
npm run integration-test - runs integration tests

Changelog

`2.0.0` - BREAKING

The (zalando-specific) realm property was removed from OAuthConfig. Also, the corresponding constants (SERVICES_REALM and EMPLYEES_REALM) were removed. Instead, you can add the realm (and arbitrary other query parameters) via the queryParams property in OAuthConfig.