@turnly/auth v0.2.38

Auth

If you're wondering how we handle authentication and authorization, you've come to the right place.

We use the JWKS (JSON Web Key Set) standard to verify the JWT (JSON Web Token) signature. This means you can bring your own OIDC (OpenID Connect) provider and authenticate the users without the need to write a wrapper around it.

How it works?

1. The user obtain a JWT through the OIDC provider login flow. When the user is authenticated, the OIDC provider returns a signed JWT.
2. Now, the user can use the JWT to access the Tenancy API.
3. The Tenancy API will verify the JWT signature using the OIDC provider public keys.
4. If the signature is valid, the Tenancy API will return the user claims.
5. The user claims are used to authorize the user to access the Tenancy API.
6. The user can now access the Tenancy API.
7. Done! 🎉

RS256 Signing Algorithm

We use RS256 because it is the recommended algorithm when signing your JWTs. It's more secure, and you can rotate keys quickly if they're compromised without re-deploying your application with a new secret, as you would have to do with HS256.

JSON Web Key Set

When you create JSON Web Tokens, they are signed using public/private key pair. Signing the token allows its recipient to validate that the content of the token wasn't changed and verify the original issuer of the token created signature.

The OIDC server provides the keys publicly in a URL in the form of a JSON Web Key Set (JWKS). During verification, the public keys are obtained. Here is an example of JWKS:

{
  "keys": [
    {
      "kid": "dkvkkV9wgDWsA7g8bPwwckirxcoDDigCOHOXqoFck2Q",
      "kty": "RSA",
      "alg": "RS256",
      "use": "sig",
      "n": "joVj5rZQ89N8rJUCsqVca9DDcOgmXMVuuMJlnZh_hZtHGKvAE1Q...x200",
      "e": "AQAB"
    }
  ]
}

Usage

import { OIDC } from '@turnly/auth'

const oidc = new OIDC({
  /**
   * The issuer is used to validate the issuer of the JWTs.
   * You can also provide the `AUTH_ISSUER` environment variable.
   */
  issuer: 'https://turnly.us.auth0.com',

  /**
   * JWKs (JSON Web Key Set)
   */
  jwks: {
    /**
     * The uri is used to retrieve the signing keys from the JWKS endpoint.
     * You can also provide the `AUTH_JWKS_URI` environment variable.
     */
    jwksUri: 'https://turnly.us.auth0.com/.well-known/jwks.json',

    /**
     * The cache option is used to cache the signing keys.
     */
    cache: true,

    /**
     * The cacheMaxAge option is used to set the maximum age of the cache. (in milliseconds)
     * Default: 7_200_000 (2 hours)
     */
    cacheMaxAge: 300_000,
  },

  /**
   * Token type
   *
   * @description This is optional verification for validating the expected token type.
   */
  tokenType: {
    /**
     * The expected value of the token type.
     * @example Standard values are `Bearer` | `ID` | `Refresh`
     */
    type: 'Bearer',

    /**
     * The property to lookup the token type.
     */
    claim: 'token_type',
  },
})

const claims = await oidc.verify('__TOKEN___')

Tenancy - Authorization policies

If you're wondering how we handle access control, you've come to the right place.

We use a set of programming rules that determine who is authorized to access a particular resource or perform a particular action.

This package is used by the main API to authorize access to resources and actions. It is also used by the main API to determine which resources and actions are available to a user.

This may sound complicated, but it's not. The policies are just functions that receive a context and return a boolean value. The context contains the user claims and the resource.

How it works?

1. Select the policy that you want to use.
2. The policy will receive a context.
3. The policy will return a boolean value.
4. Done! 🎉

Example

import { Context, Policies } from '@turnly/auth'

const context: Context = {
  user: {
    memberships: [
      {
        organizationId: 'organization-id',
        roles: ['roles:admin'],
      },
    ],
  },
  organizationId: 'organization-id',
  roles: ['roles:admin'],
}

if (Policies.Roles.isAllowed(context)) {
  // Do something
}

If you are using another programming language, you should not worry about using these policies, event if you are using it.

These policies although available as a package, are intended for internal use of the main API.

The tenancy API takes care of using these policies and gets the user's claims from the access token.