/auth-toolbox

The developer toolbox for HTTP Client Authentication.

Primary LanguageTypeScriptMIT LicenseMIT

Auth Toolbox

NPM Package npm type definitions Build Status Coverage Status devDependencies Status semantic-release GitHub stars

The developer toolbox for HTTP Client Authentication.

Auth Toolbox is a set of JavaScript modules that can be used to add HTTP Client Authentication to your web application.

It's designed to support any HTTP Client, and any Authorization Server supporting OpenID Connect / OAuth 2.0 Resource Owner Password Credentials Grant. Any custom similar workflows with username/password credentials authentication providing an Access Token may be supported (like PHP Symfony's lexik/LexikJWTAuthenticationBundle + gesdinet/jwt-refresh-token-bundle).

Disclaimer

This kind of authentication method is commonly discouraged for web applications, but it may be acceptable for simple applications where Authentication Server and Resource Owner is implemented in the same service, or if the Authentication Server is dedicated to the application.

You should read this excellent post by Scott Brady about why you should not use Password Grant authentication. As a more secure alternative, you could use oidc-client, but if you really need to avoid any redirect to the Authorization Server, you should stick with Auth Toolbox.

Install

npm install auth-toolbox

Examples

OpenID Connect Password Grant / OAuth 2.0 Password Grant

  • Resource Owner Password Credentials Grant (grant_type=password)
  • Client authentication with id/secret (Basic Auth)
  • OpenID Auto configuration throw OpenID Discovery
  • Axios adapter
import Auth, { UsernamePasswordCredentials } from 'auth-toolbox/dist/lib/auth-toolbox'
import OpenidConnectAdapter, { openidConnectDiscovery } from 'auth-toolbox/dist/lib/server-adapter/openid-connect-adapter'
import JwtTokenDecoder from 'auth-toolbox/dist/lib/token-decoder/jwt-token-decoder'
import AxiosAdapter from 'auth-toolbox/dist/lib/client-adapter/axios-adapter'

import axios, { AxiosResponse } from 'axios'

// Keycloak is a great opensource Authentication Server
const openIdIssuerUrl = 'https://keycloak.pragmasphere.com/realms/planireza'
const openIdClientId = 'clientId'
const openIdClientSecret = 'ThisIsSecret!'

const client = axios.create()

const axiosAdapter = new AxiosAdapter(
  client,
  { auth: { username: openIdClientId, password: openIdClientSecret } }
)

const auth = new Auth<UsernamePasswordCredentials, AxiosResponse>(
  openidConnectDiscovery(axiosAdapter, openIdIssuerUrl),
  new OpenidConnectAdapter(),
  axiosAdapter,
  { accessTokenDecoder: new JwtTokenDecoder() }
)

auth.login('myUsername', 'myPassword').then(() => {
  // Read the payload from decoded access token
  const payload = auth.decodeAccessToken()
  console.log(payload) // Decoded user payload
  
  // This resource requires user to be authenticated.
  // Axios interceptors have been automatically registered to handle all the authentication stuff.
  return client.get('/restricted')
}).then((r: AxiosResponse) => {
  // We are in !
  console.log(r.data)
})

Docs

API Documentation is available

Supported HTTP Clients

Auth Toolbox supports the following HTTP Clients:

  • axios
  • request (Todo)
  • JQuery (Todo)
  • Angular (Todo)
  • XMLHttpRequest (Todo)

Any other client may be implemented.

Supported HTTP Servers protocols

Auth Toolbox supports the following protocols out of the box:

  • OpenID Connect Resource Owner Password Credentials Grant (Access Token + Optional Refresh token)
  • OpenID Discovery (.well-known/openid-configuration endpoint)

Any custom implementation matching more or less OAuth 2.0 Password Grant flow may be implemented.

Credits