This is our SSO server and identity provider for webmaker.org and all our additional Webmaker websites; sign in once, sign in everywhere!

The app is written using nodejs, requires npm for package management and (to make running multiple servers at once easier) ruby (we run the app locally using foreman).

Once you have those you can get things up and running by:

1. Install npm modules - npm install
2. Install and start up a local MongoDB instance
3. Create and configure a .env file - copy the .env.sample file we've provided.
4. Install foreman (if you don't have it) - gem install foreman
5. Run foreman - foreman start -f Procfile.dev

Head to either http://localhost:3001 or http://localhost:3002 (or both) and sign in.

On first-time login, the page will slide down a dialog that lets you pick a username to use. Fill in something interesting, accept the terms, and continue. On subsequent logins, you will not be faced with this dialog.

We use Grunt to lint our CSS and JS and these tests are run on each pull request sent into the mozilla repo using travis-ci.

If you want to check your code passes before sending in a pull request (and ensure no breaking builds) then:

• ensure that grunt is installed globally on your system - npm install -g grunt
• run grunt --travis test

Bugs can be found in Bugzilla - this is what bugs we have now, if you notice anything else please file a new bug for us.

If you wish to use the webmaker user bar in your webmaker.org app, you will need to implement the following steps.

Your app will need to be able to speak to persona (for server-side validation and logout), as well as the webmaker login API. You will need the express-persona, https://github.com/jbuck/express-persona, and webmaker-loginapi, https://github.com/mozilla/node-webmaker-loginapi, modules installed.

Also note that the login API requires that the username:password combination that you use to create your loginapi instance with needs to be known by the login server you are accessing. As such, you will have to make sure that it is one of the possible username:password combinations specified in the login server's environment variable ALLOWED_USERS.

Also, it is recommended to not hardcode the loginapi's endpoint with user credentials in your app, but to use an environment variable that you refer to in the code: var loginapi = require("webmaker-loginapi")({make this an env. var});.

Ensure that you're using the correct values in your local .env file, make sure that the URL of your app is included in the ALLOWED_DOMAINS for this app. (For production and staging, these values have already been fixed to the webmaker.org production and staging domains).

For example, if we're integrating SSO into two apps running at http://localhost:8888 and http://localhost:7777, with the Login server running at http://localhost:3000, you would need to include the following in the .env of login.webmaker.org:

ALLOWED_DOMAINS="http://localhost:3000 http://localhost:8888 http://localhost:7777"

For testing purposes, your app's Persona AUDIENCE variable can be set to the following:

AUDIENCE="http://webmaker.mofostaging.net"

and your app's LOGIN variable can be set to the following:

LOGIN="http://login.mofostaging.net"

<link rel="stylesheet" href="<%= login %>/css/nav.css" />

For staging/dev work, you can use http://login.mofostaging.net instead of the login variable.

<div id="webmaker-nav">
  <!-- the webmaker bar -->
  <nav class="webmaker-nav-container">
    <a id="logo" href="https://webmaker.org"><img src="<%= login %>/img/webmaker-logo.png" alt="Mozilla Webmaker" /></a>
    <ul class="webmaker-nav user-info">
      <li class="user">
        Hi <span id="identity" class="user-name-container"></span>
      </li>
      <li class="makes"><button>My makes</button></li>
      <li>
        <button id="webmaker-login">Sign in to save <span>Sign up</span></button>
        <button id="webmaker-logout">Sign out</button>
      </li>
    </ul>
  </nav>
  <div class="my-projects-container">
    <iframe src="<%= audience %>/myprojects?app=<%= appname %>&email=<%= email %>"></iframe>
  </div>
</div>

For the best performance put this at the bottom of your HTML file, just before the closing </body>

<script src="http://webmaker.mofostaging.net/sso/include.js"></script>

You can specify custom event handlers to be triggered after the user bar logs someone in or out (in order to effect UI changes for your app, for instance). This requires setting up a navigator.idSSO.app object in the following manner:

<script>
  navigator.idSSO.app = {
    onlogin: function(loggedInUser, displayName) {
      // your code here
    },
    onlogout: function() {
      // your code here
    }
  };
</script>

Note that you do not need to provide both event handlers; if you only need one, the other can be left out without leading to any errors.

This include must be included after the Persona include.js, or —if custom event handlers are used— after the custom event handling script block.

<script src="http://login.mofostaging.net/js/sso-ux.js"></script>

The persona block that you will need to add to your app.js consists of the following code:

persona(app, {
  audience: env.get( "AUDIENCE" )
});

Make sure you also follow the instructions on setting up express-persona mentiond in step 1.

This will let you use req.session.email in the rest of your code.

Add the following snippet to you HTML <head> section, and render it based on the person-created req.session.email value:

  <meta name="persona-email" content="{value from req.session.email}">

If req.session.email is known during page serving, the user may already be logged in and this value should be the user's Persona email address. If it is not set, this value should be an empty string.

Add webmaker-loginapi to your package.json, and follow its instructions in the README at https://github.com/mozilla/node-webmaker-loginapi. The module will give your app a new route, /user/:userid, which can be used to get a user's Webmaker username.

Calling the route with a Persona email as userid will either set a session value req.session.username to the user's Webmaker username, if they have one, or will not add the username property on req.session, signalling that the user is either unknown entirely, or does not have a username associated with his or her Persona login. For more detailed information, see the node-webmaker-loginapi repository.

To enable New Relic, set the NEW_RELIC_ENABLED environment variable and add a config file, or set the relevant environment variables.

For more information on configuring New Relic, see: https://github.com/newrelic/node-newrelic/#configuring-the-agent