This is our SSO server and identity provider for webmaker.org and all our additional Webmaker websites; sign in once, sign in everywhere!
Getting the Server Up and Running Locally
Once you have those you can get things up and running by:
- Install npm modules -
- Install and start up a local MySQL instance, or ignore this step if you choose to use sqlite.
- Create and configure a
.envfile - copy the
env.samplefile we've provided.
- Run the app.js file from the root of the server with
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
grunt --travis test
If you wish to use the webmaker user bar in your webmaker.org app, you will need to implement the following steps.
1. Add the webmaker-loginapi module
Your app will need to be able to speak to persona (for server-side validation and logout). You will need the
webmaker-loginapi https://github.com/mozilla/node-webmaker-loginapi module installed to accomplish this.
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
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")( expressInstance, optionsObject );.
2. Set up your environment variables
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:
and your app's
LOGIN variable can be set to the following:
3. Include this app's CSS file in your master template
For staging/dev work, you can use
http://login.mofostaging.net instead of the
4. Add the following snippet to your HTML page, below but before any other content in the required HTML for the Webmaker navigation bar
<!-- the webmaker bar -->HiMy makes
5. Link to our external JS file
For the best performance put this at the bottom of your HTML file, just before the closing
For staging tests, this can also just be
6. If you need your own login / logout event handling
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:
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.
7. Include our sso-ux script
This include must be included after the Persona
include.js, or —if custom event handlers are used— after the custom event handling script block.
8 Set up the persona handler
The persona block that you will need to add to your app.js consists of the following code:
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.
9 put the session email into your master template, when known
Add the following snippet to you HTML
<head> section, and render it based on the person-created
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.
10 Include the
webmaker-loginapi node module in your app
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