Cycle

Community maintained

System Requirements

This tutorial has been tested with the following:

  • NodeJS 6.3
  • npm 3.10.3
  • @cycle/xstream-run 3.0.3
  • cyclejs-auth0 3.0.0

Before Starting

Please remember that for security purposes, you have to register the URL of your app in the Client Settings section as the callbackURL.

Right now, that callback is set to the following:

https://YOUR_APP/callback

1. Install the cyclejs-auth0 Package

To install cyclejs-auth0 from the command line, run:

npm install cyclejs-auth0

2. Instantiate the Driver and Configure Auth0Lock

In your main application file, you can now setup the auth0Driver and feed it your clientID and domain:

import {makeAuth0Driver, protect} from "cyclejs-auth0";

function main(sources) {
    //your application's code
}

const drivers = {
    auth0: makeAuth0Driver('YOUR_CLIENT_ID', 'YOUR_AUTH0_DOMAIN')
}

3. Implement the Login

Now that everything is set, you can activate authentication on some of your components. Activating authentication on a component is as simple as calling the protect function on that component. Let's assume you have a Todos component and you want to ensure the user is logged in to see it.

function main(sources) {
    const ProtectedTodos = protect(Todos); //here we wrap the Todos component in the protect function
    const protectedTodosInstance = ProtectedTodos(sources);

    return {
        DOM: protectedTodosInstance.DOM,
        HTTP: protectedTodosInstance.HTTP
        //...
    }
}

Now if the user is not logged in when the component is instantiated, the Auth0 form will show up.

4. Configuring the Login Form

You may want to configure the behavior of the Auth0 login form. To achieve that, you can use the auth0ShowParams options on the protect function:

const ProtectedComponent = protect(Component, {
    auth0ShowParams: {
        authParams: { scope: "openid nickname" },
        responseType: "token"
    }
});

It defaults to:

{
    authParams: { scope: "openid" },
    responseType: "token"
}

All the available configurable parameters are supported, see User configurable options.

After authentication, the protect function will handle the token parsing and store it to localStorage.

4. Retrieve and display the User's Information

Once a component is protected, it is given a props object that contains a tokens$ stream that can be used to either:

  • be decoded to get some basic information about your user (sub, nickname ... depending on your authParams.scope setting);
  • send a getUserInfo request to the Auth0 lock to retrieve a full profile.
function Component(sources) {
    const tokens$ = sources.props.tokens$; //the token$ added by the protect function

    const userProfile$ = sources
        .auth0
        .select("getUserInfo") //read to response of the lock to the getProfile method call

    return {
        auth0: tokens$
            .filter(tokens => !!tokens) //filter empty tokens
            //send the getUserInfo action to the auth0 driver
            .map(tokens => ({ action: "getUserInfo", params: tokens.accessToken })),

        DOM: userProfile$ //displays the user profile once fetched
            .map(user => p([
                "Welcome",
                span(".nickname", user.nickname)
            ]))
    };
}
<p>Welcome <span class="nickname"></span></p>

To discover all the available properties of a user's profile, see Auth0 Normalized User Profile. Note that the properties available depend on the social provider used.

5. Implement the Logout

To log out, you simply need to send the logout action to the Auth0 driver.

function main(sources) {
    const logoutAction$ = sources
        .DOM
        .select(".logout")
        .events("click")

    return {
        auth0: logoutAction$.mapTo({ action: "logout" })
    }
}

Persisting Application State

Lock uses redirect mode by default, meaning that a full page refresh will occur when users go through the authentication process in your application. This can be undesirable for single page apps, especially if the application contains state that should be displayed to the user again after they authenticate. For example, it may be the case that your users can initiate authentication from an arbitrary route within your single page app and you may want to return them to that location (along with any relevant state) after authentication is complete.

The recommended solution for this is to persist any necessary application state in local storage or a cookie before the user logs in or signs up. With this data, you can provide some custom post-authentication logic in the listener for the authenticated event to allow the user to pick up from where they left off.

In cases where storing application state is not possible, Lock's popup mode can be used. Please note that popup mode is not recommended. Known bugs in certain browsers prevent popup mode from functioning as expected under some circumstances.

Use Auth0 for FREECreate free Account