Wider support for JWT authentication

[MarinPostma]

We would like to support JWT for authentication. Currently, it is supported for the experimental typescript policies, but we want it to be supported more generally. Most of the code for verifying tokens is there already, we need to figure out how the API would work.

In Typescript policies, the token is validated, and the claims are passed to the policy code. This means that we don't really care what's inside the token. With the current policies, we can't do that, so we need to figure out what we expect the token to contain.

As a first iteration, we could improve the authentication story by requesting a standard compliant JWT, and use the sub claim in place of the user id.

@CodingDoug, you can add your thoughts to this issue :)

[CodingDoug]

One thing we need to decide is if we do user record management or not. Our current NextAuth system attempts to do so, but It will be much easier for us not to. I suggest that we simply accept and decode JWTs from any source (where decoding tools or configuration are provided), but leave their interpretation up to the developer.

We can provide plugins for popular auth providers that perform validation using the provider’s own libraries if available. For example:

• Google
• Facebook
• Okta
• Firebase (federated across many providers)

Developers can provide their own JWT plugins using an API that we document. The API should allow for the plugin to run arbitrary code to decode the JWT, since providers often rotate signing keys and provide SDKs to handle that automatically.

It’s entirely possible that a developer will want to accept JWT from any number of providers. In that case, we should provide a name for each provider that we support (or they support themselves), and pass that along with the decoded JWT to routes or policies that use them. With that, the developer can write code to implement things like “Users authenticated with the Firebase plugin that have custom claim ‘foo’ may invoke this route” or “Users authenticated using the Google plugin whose ‘sub’ (uid) claim is present in an entity query may invoke this route”. It also allows developers to “link” the same end user with multiple auth providers by associating a pair of provider ID / claim within a per-user entity. For example, a UserAuth entity might have the following structure:

class UserAuth extends ChiselEntity {
    // identifies a unique end user to the application
    uid: string
    // provider ID they auth’d with (e.g. “google”, “facebook”)
    provider: string  
    // value of the claim that identifies them to the provider
    providerUid: string
}

With this, code can be written to query UserAuth using information from a decoded JWT to find out which logical end user is making the request.

Availability in ChiselRequest

The following Auth type could be provided in ChiselRequest and policies:

interface Auth {
    // provider ID, e.g. “google”
    provider: string

    // decoded JWT
    jwt: Jwt
}

interface Jwt {
    header: JsonObject
    payload: JsonObject
}

type JsonValue =
    | string
    | number
    | boolean
    | JsonObject
    | JsonArray;

interface JsonObject {
    [key: string]: JsonValue;
}

interface JsonArray extends Array<JsonValue> { }

Here’s how the JWT might surface in a route handler:

async (req: ChiselRequest) => {
    // defined only if a JWT was decoded from Authorization
    const auth: Auth? = req.auth

    if (auth === undefined) {
        // Auth required, return 403
    }

    const provider = auth.provider  
    const jwt = auth.jwt

    // sub uniquely identifies the user to the provider
    const providerUid = jwt.header.sub

    // look up app user record using provider and sub
    const user = await AuthUser.findOne({ provider, providerUid })

    // decide if the user should be allowed to do whatever
}