NodeJS / Passport

Requirements 

The cookbook uses the Passport library with the passport-saml plugin running with the Express web application framework.

Runtime Example 

Included in the repository is a dockerized application for hands-on learners. It starts an Identity Provider and one Service Provider per example.

Clone the Repository 

git clone https://gitlab.code.rit.edu/systems-public/saml-cookbook.git

Start Containers 

The examples requires docker and docker-compose to run. You can download these by following instructions from the official Docker website.

After dependencies have been installed, navigate to the ./saml-cookbook/docker folder in a terminal and run the following command.

# Get a coffee, this is going to take a while
docker-compose build && docker-compose up

You can now view the example at https://saml-cookbook.localtest.me/. If you’re having issues verify that the command completed without errors and that localhost:443 is forwarding traffic to your docker containers.

All the code can be found at ./saml-cookbook/docker/<example>/.

Integration and Pre-Requisites 

Install passport, passport-saml, and some compatible session package. This library uses express-session.

Extract IdP Settings 

Find the IdP metadata. RIT’s IdP metadata can be found here.

You’ll need the entity id, the signing certificate, and the single sign-on service url. All the examples in this cookbook default to using RIT’s SAML IdP metadata.

Configuration 

Note

If you’re confused about any of the terms, refer to the glossary.

Selecting an Entity Id 

An entity id must be a URI you own. An example of a good entity id is $serviceUrl + /saml2, or the URL of your metadata.

Do not use bare words like widgets or URIs owned by other entities like google.com/widgets.

Create a Keypair 

You will need a public and private keypair to encrypt and sign communication between the IdP and your service. You must generate a separate keypair every time you create a new entity id. Included is a one-line example to show how we could easily create a keypair for our service.

openssl req -new -newkey rsa:2048 -days 3650 -nodes -x509 \
    -keyout "service.key" -out "service.crt" -subj "/CN=widgets.rit.edu"

Create Your Settings 

Refer to the official documentation for an expanded list of options. The passport-saml library passes options directly to node-saml.

Save this alongside your application or integrate it with an existing settings file. These settings configure how you send requests to the IdP and how you parse responses.

Modify the settings in the SP Section and IdP Section to get started.

Variable Settings

/** SP Section **/
// base url of your site
const BASE_URL = 'https://widgets.rit.edu/';
// your generated entity id
const SP_ENTITY_ID = 'https://widgets.rit.edu/saml2';
// your generated keypair information
// base64 encoded private key (PEM) for the SP
const SP_PVK = fs.readFileSync('/abs/path/to/service.key', { encoding: 'utf8' });
// base64 encoded certificate (PEM) for the SP
const SP_CERT = fs.readFileSync('/abs/path/to/service.crt', { encoding: 'utf8' });
/** End SP Section **/

/** IdP Section **/
// single-sign-on url for your IdP, defaults to Redirect binding
const IDP_SSO_URL = 'https://shibboleth.main.ad.rit.edu/idp/profile/SAML2/Redirect/SSO';
// base64 encoded certificate (PEM)
const IDP_CERT = fs.readFileSync('/abs/path/to/idp.crt', { encoding: 'utf8' });
/** End IdP Section **/

Common Settings

const defaultSamlStrategy = new SamlStrategy(
    {
        name: 'saml',
        callbackUrl: BASE_URL + 'saml2/acs',
        entryPoint: IDP_SSO_URL,
        issuer: SP_ENTITY_ID,
        idpCert: IDP_CERT,
        decryptionPvk: SP_PVK,
        decryptionCert: SP_CERT,

        signMetadata: true,
        wantAssertionsSigned: true,
        wantAuthnResponseSigned: true,
        disableRequestedAuthnContext: true
    },
    /* acs callback */
    (profile, done) => {
        // Called after successful authentication, parse
        // the attributes in profile.attributes and create
        // or update a local user. Then return that user.
        return done(null, profile.attributes)
    }
    /* end acs callback */
)

module.exports = {
    defaultSamlStrategy,
    IDP_CERT,
    SP_PVK,
    SP_CERT
};

Integrating SAML 

Once your settings are taken care of you can begin integration. To integrate with a production IdP, you will need to exchange metadata and define the attributes you need for your service.

An example list of attributes you may need is:

User name (uid)
First name (givenName)
Last name (sn)
email (mail)

Generating Metadata 

The IdP will require a copy of the metadata produced at this endpoint to register your service.

siteRoot.get(
    "/saml2/metadata",
    (req, res) => {
        res.set('Content-Type', 'text/xml');
        res.send(defaultSamlStrategy.generateServiceProviderMetadata(SP_CERT, SP_CERT))
    }
)

Creating the AuthnRequest 

The passport.authenticate(STRATEGY_NAME) function handles redirecting the user to the IdP with the correct parameters.

// Passes the SAML login function handler to passport. 
// Passport will then redirect the client to the IdP
siteRoot.get('/login', passport.authenticate('saml'))

Parsing the Response from the IdP 

The ACS endpoint extracts and operates on a payload set by the IdP. Passport creates a handler for you to do most of this.

// Passes the ACS function to passport. 
// Passport will then extract the attributes from the IdP
// assertion and store the user in the session.
siteRoot.post(
    "/saml2/acs",
    bodyParser.urlencoded({ extended: false }),
    passport.authenticate("saml", {
        failureRedirect: SITE_ROOT,
        failureFlash: true,
    }),
    function (req, res) {
        res.redirect(SITE_ROOT);
    },
)

Extracting Attributes 

After successfully parsing the IdP payload, the ACS can then extract attributes. These are returned as an object and may be mapped to an alias such as mail, uid, givenName or may use an oid such as 0.9.2342.19200300.100.1.1.

With Passport, the attributes are extracted in the strategy initializer. You can choose to create a local user here and use that user record on subsequent page loads.

(profile, done) => {
    // Called after successful authentication, parse
    // the attributes in profile.attributes and create
    // or update a local user. Then return that user.
    return done(null, profile.attributes)
}

The user payload is then passed to the passport.serializeUser method. This saves attributes to the user’s session. For the example we save all the SAML attributes. In a more robust environment you could extract a user profile id, serialize that, and then lookup the user from the database.

// Necessary to tell passport how to serialize the user
// In a production environment we may just serialize the
// user.id and then read from the database when deserializing
passport.serializeUser(function (user, done) {
    done(null, user);
});

// Same as the above, we could just have an id and need to hydrate
// that into a full user object. In this example we just store the
// full attribute array in the session and retrieve it every time.
passport.deserializeUser(function (user, done) {
    done(null, user);
});