search

Clever / saml2

Node module to abstract away the complexities of the SAML protocol behind an easy to use interface.
Apache License 2.0
352 stars 163 forks source link

readme

Maintenance Notice

This library is currently in maintenance mode. Until further notice, the primary directive is to handle bug reports and security issues with this library.

Any library alternatives and suggestions can be filed under an issue.

SAML2-js

CircleCI

saml2-js is a node module that abstracts away the complexities of the SAML protocol behind an easy to use interface. It achieves this this by helping you implement a service provider for the SAML protocol. It currently does not implement the features to act as an identity provider.

Usage

Install with npm.

  npm install saml2-js --save

Include the SAML library.

  var saml2 = require('saml2-js');

Documentation

This library exports two constructors.

Note: Some options can be set on the SP, IdP, and/or on a per-method basis. For the options that are set in multiple places, they are overridden in the following order: per-method basis overrides IdP which overrides SP.

ServiceProvider(options)

Represents a service provider that relies on a trusted IdentityProvider for authentication and authorization in the SAML flow.

Options

An object that can contain the below options. All options are strings, unless specified otherwise. See note for more information on options.

Returns the following functions

Example


  var sp_options = {
    entity_id: "https://sp.example.com/metadata.xml",
    private_key: fs.readFileSync("key-file.pem").toString(),
    certificate: fs.readFileSync("cert-file.crt").toString(),
    assert_endpoint: "https://sp.example.com/assert",
    force_authn: true,
    auth_context: { comparison: "exact", class_refs: ["urn:oasis:names:tc:SAML:1.0:am:password"] },
    nameid_format: "urn:oasis:names:tc:SAML:2.0:nameid-format:transient",
    sign_get_request: false,
    allow_unencrypted_assertion: true
  }

  // Call service provider constructor with options
  var sp = new saml2.ServiceProvider(sp_options);

  // Example use of service provider.
  // Call metadata to get XML metatadata used in configuration.
  var metadata = sp.create_metadata();

Service provider function definitions

create_login_request_url(IdP, options, cb)

Get a URL to initiate a login.

Takes the following arguments:

redirect_assert(IdP, options, cb)

Gets a SAML response object if the login attempt is valid, used for redirect binding.

Takes the following arguments:

Example of the SAML assert response returned:

  { response_header:
     { id: '_abc-1',
       destination: 'https://sp.example.com/assert',
       in_response_to: '_abc-2' },
    type: 'authn_response',
    user:
     { name_id: 'nameid',
       session_index: '_abc-3',
       attributes:
        { 'http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname': [ 'Test' ] } } }

post_assert(IdP, options, cb)

Gets a SAML response object if the login attempt is valid, used for post binding.

Takes the following arguments:

create_logout_request_url(IdP, options, cb)

Creates a SAML Request URL to initiate a user logout.

Takes the following arguments:

create_logout_response_url(IdP, options, cb)

Creates a SAML Response URL to confirm a successful IdP initiated logout.

Takes the following arguments:

create_metadata()

Returns the XML metadata used during the initial SAML configuration.

IdentityProvider(options)

Represents an online service that authenticates users in the SAML flow.

Returns no functions, exists solely to be passed to an SP function.

Options

An object that can contain the below options. All options are strings, unless specified otherwise. See note for more information on options.

Example


  // Initialize options object
  var idp_options = {
    sso_login_url: "https://idp.example.com/login",
    sso_logout_url: "https://idp.example.com/logout",
    certificates: [fs.readFileSync("cert-file1.crt").toString(), fs.readFileSync("cert-file2.crt").toString()],
    force_authn: true,
    sign_get_request: false,
    allow_unencrypted_assertion: false
  };

  // Call identity provider constructor with options
  var idp = new saml2.IdentityProvider(idp_options);

  // Example usage of identity provider.
  // Pass identity provider into a service provider function with options and a callback.
  sp.post_assert(idp, {}, callback);

Example: Express implementation

Library users will need to implement a set of URL endpoints, here is an example of express endpoints.

var saml2 = require('saml2-js');
var fs = require('fs');
var express = require('express');
var app = express();
// If you're using express <4.0:
// var bodyParser = require('body-parser');
// app.use(bodyParser.urlencoded({
//   extended: true
// }));
app.use(express.urlencoded());

// Create service provider
var sp_options = {
  entity_id: "https://sp.example.com/metadata.xml",
  private_key: fs.readFileSync("key-file.pem").toString(),
  certificate: fs.readFileSync("cert-file.crt").toString(),
  assert_endpoint: "https://sp.example.com/assert"
};
var sp = new saml2.ServiceProvider(sp_options);

// Create identity provider
var idp_options = {
  sso_login_url: "https://idp.example.com/login",
  sso_logout_url: "https://idp.example.com/logout",
  certificates: [fs.readFileSync("cert-file1.crt").toString(), fs.readFileSync("cert-file2.crt").toString()]
};
var idp = new saml2.IdentityProvider(idp_options);

// ------ Define express endpoints ------

// Endpoint to retrieve metadata
app.get("/metadata.xml", function(req, res) {
  res.type('application/xml');
  res.send(sp.create_metadata());
});

// Starting point for login
app.get("/login", function(req, res) {
  sp.create_login_request_url(idp, {}, function(err, login_url, request_id) {
    if (err != null)
      return res.send(500);
    res.redirect(login_url);
  });
});

// Variables used in login/logout process
var name_id, session_index;

// Assert endpoint for when login completes
app.post("/assert", function(req, res) {
  var options = {request_body: req.body};
  sp.post_assert(idp, options, function(err, saml_response) {
    if (err != null)
      return res.send(500);

    // Save name_id and session_index for logout
    // Note:  In practice these should be saved in the user session, not globally.
    name_id = saml_response.user.name_id;
    session_index = saml_response.user.session_index;

    res.send("Hello #{name_id}! session_index: #{session_index}.");
  });
});

// Starting point for logout
app.get("/logout", function(req, res) {
  var options = {
    name_id: name_id,
    session_index: session_index
  };

  sp.create_logout_request_url(idp, options, function(err, logout_url) {
    if (err != null)
      return res.send(500);
    res.redirect(logout_url);
  });
});

app.listen(3000);