@fusion.io/authenticate

Better Authentication for better Geeks.

In short, this is an authentication framework for Node.JS

Much like PassportJS. 😛

GETTING STARTED

For quick and dirty and lazy work with this package. Please check our supported Gateways

To get start, please follow these steps:

1. Installation.
2. Determine the authentication Protocol(s).
3. Making Identity Provider(s).
4. Register your gateway with Protocol and Identity Provider.
5. Guard your resources.

For further topics, please checkout:

• Some best practices about authentications.
• Document about making a Protocol.
• Our core concepts when building this package.

Installation

To install this package, please run:

npm install --save @fusion.io/authenticate

Determine the authentication Protocol(s)

Hey! hey! What is protocol?

If you're asking, a Protocol is just a service that can read the user's authentication information (Credential) from your app. Just it!

There are variety protocols out there and it is hard to choose! But not so many that are widely accepted and adopted.

So we are here to help you go shopping!

• If you just want to authenticate your user by email/username/phone number/whatever... and password. You should use the Local protocol.

• If you also want to let the user can authenticate and login to your application via social networks. Like Facebook, Google, Linkedin, ... Most of them are supporting OAuth2 protocol. So it will be your choice.

• If you also provide API endpoints and you want to protect that resources, we suggest that you should use token. So let's add Token into your shopping cart!

This step is just it. No code! Just cheap talk! :D

Making Identity Provider(s).

Hey! hey! What is Identity Provider?

Again, if you're asking, an Identity Provider is just a service that translates the credential of the above step into user's Identity (or user id or something that you can use to distinguish one user to others).

Let's check your shopping cart.

If you are using Local protocol. Your Identity Provider should look like:

class MyLocalUserProvider {

    async provide({username, password}) {
        // Here you can find your user
        // Do some password verification.

        // and the last thing is:

        return user.id; // Or .email .phonenumber .whatever...
    }
}

If you are using OAuth2 protocol, your Identity Provider should look like:

class MyOAuth2kUserProvider {

    async provide({access_token}) {
        // Here you can use the access_token to ask
        // the related social network for the user's
        // profile and of course, user id.

        // and ...
        return user.id;
    }
}

If you are using Token protocol, your Identity Provider should look like:

class MyApiUserProvider {

    async provide({token}) {
        // Here you can use the token to find your user.

        // and again:

        return user.id;
    }
}

In general, your Identity provider is nothing special but a class with an async provide(credential) method.

Where credential is the information that you'll get from the protocol.

Register your gateway with Protocol and Identity Provider

Now let's mixed up your Identity Provider and protocol.

const { authenticator, HeadlessLocal } = require('@fusion.io/authenticate');

// or ES6:

import { authenticator, HeadlessLocal } from "@fusion.io/authenticate";

authenticator.gate('local', new HeadlessLocal(), MyLocalUserProvider());

In the example code above, we've registered a gateway called local with HeadlessLocal protocol and your MyLocalUserProvider identity provider.

We supports 3 basic protocols for you:

HeadlessLocal, HttpOAuth2 and HttpTokenBearer . You can replace the above HeadlessLocal to any one of them.

For more usage of Protocol, please check out the Protocols documentation.

You can have as many gates as you want. Just use the authenticator.gate(gateName, protocol, identityProvider); to register a new gate.

Guard your resources

Now, your gate is ready, let's authenticate your resource with your gate.

const { UnAuthenticated, Aborted } = require('@fusion.io/authenticate');

// or ES6

import { UnAuthenticated, Aborted } from "@fusion.io/authenticate";

...

// Some where inside your code.

try {
    let userIdentity = await authenticator.authenticate('local', {username: 'rikky', password: 'Won\'t tell ya!'} );

    // Here is a safezone. User already authenticated
    // You can perform any thing on your resource here!

} catch (error) {
    if (error instanceof UnAuthenticated) {
        // Here is not a safe zone. User is unauthenticated.
    }

    if (error instanceof Aborted) {
        // Here is weird zone. The Protocol decided to abort
        // authentication step.
    }

    // Here is crazy zone. Some thing went wrong! you better throw the
    // error out for debugging.
    throw error;
}

Good news for Koa, Express, Socket.IO users!

We love middleware style! If you are using above frameworks, you'll have a very nice place to authenticate your resources. The mighty middleware:

// For example, here we'll wrap the `.authenticate()` method inside a Koa middleware.

const localAuthentication = async (context, next) => {
    try {
        let userIdentity = await authenticator.authenticate('local', context.request.body);

        context.identity = userIdentity;
        await next();

    } catch (error) {
        if (error instanceof Aborted) {
            return;
        }
        throw error;
    }
}


// So now, we can do something like:


app.use(localAuthentication);

And for your laziness, we also wrapped it. So beside HeadlessLocal, HttpOAuth2 and HttpTokenBearer we have ExpressLocal, KoaLocal, SocketIOLocal, KoaOAuth2, ExpressOAuth2, KoaToken, ExpressToken, SocketIOToken, KoaSession, ExpressSession.

These are framework specific protocols. It have ability to mount to your framework as a middleware and authenticate its endpoints.

You can replace the above code by simple authenticator.authenticate() method:

// For koa:
//
// app or router
app.use(authenticator.authenticate('local'));
// Then you can get the identity by accessing `context.identity`.

// For express:
//
// app or router
app.use(authenticator.authenticate('local'));
// Then you can get the identity by accessing `request.identity`.

// For Socket.IO:
//
// socket or namespace
socket.use(authenticator.authenticate('local'));
// Then you can get the identity by accessing `socket.identity`.

Good news for users don't find a suitable protocol.

So if you don't think these above protocols are suitable, and you decided to write one for you. That's great! Now you are becoming seriously! Please check the CUSTOM PROTOCOL part.

Tips:

• Gateway is a unit of work that combines a protocol and an identity provider together. It's the building block of authentication process. Authenticator is just a service that managing gates. Just it!

• Relationship between Protocol and IdentityProvider is many-to-many. Gateway is a pivot representing that relationship.

• You can have many Protocols that sharing the same Identity Provider if they providing the same Credential.

  For example: your application may support token authentication via web APIs. And you also want to support token authentication via WebSocket. But no matter what the transport layer is, they still returning a token as a Credential, using the same Identity Provider in this case will enable your ability to authenticate the same user over multiple transport layers.

• In reverse, you can also have many Identity Providers that sharing the same Protocol when we have more than one Type Of User, but sharing the same way of authentication (same way of providing Credential).

  For example: your application may want to authenticate users and organizations account. In both cases, they will provide email and password as Credential. Using the same Protocol will help your code DRY by not providing 2 Protocols that are identical to each other.

BEST PRACTICES

Please checkout some best practices about authentication.

FOR YOUR LAZINESS:

We ship some common social authentication services: Facebook, Google, Instagram, Slack, GitHub out of the box. So you may wants to check out how to have the Login via XXX button.

CUSTOM PROTOCOL

Please checkout the document about making a Protocol.

CONCEPTS AND DEFINITIONS

Please check out our concepts when building this package.