@elm-street-technology/passport-saml-metadata

1.5.3 • Public • Published

passport-saml-metadata

Build Status Greenkeeper badge

Utilities for reading configuration from SAML 2.0 Metadata XML files, such as those generated by Active Directory Federation Services (ADFS).

Installation

npm install passport-saml-metadata

Usage Example

const os = require('os');
const fileCache = require('file-system-cache').default;
const { fetch, toPassportConfig, claimsToCamelCase } = require('passport-saml-metadata');
const SamlStrategy = require('passport-wsfed-saml2').Strategy;

const backupStore = fileCache({ basePath: os.tmpdir() });
const url = 'https://adfs.company.com/federationMetadata/2007-06/FederationMetadata.xml';

fetch({ url, backupStore })
  .then((reader) => {
    const config = toPassportConfig(reader);
    config.realm = 'urn:nodejs:passport-saml-metadata-example-app';
    config.protocol = 'saml2';

    passport.use('saml', new SamlStrategy(config, function(profile, done) {
      profile = claimsToCamelCase(profile, reader.claimSchema);
      done(null, profile);
    }));

    passport.serializeUser((user, done) => {
      done(null, user);
    });

    passport.deserializeUser((user, done) => {
      done(null, user);
    });
  });

See compwright/passport-saml-example for a complete reference implementation.

API

fetch(config = {})

When called, it will attempt to load the metadata XML from the supplied URL. If it fails due to a request timeout or other error, it will attempt to load from the backupStore cache.

Config:

  • url (required) Metadata XML file URL
  • timeout Time to wait before falling back to the backupStore, in ms (default = 2000)
  • backupStore Any persistent cache adapter object with get(key) and set(key, value) methods (default = new Map())

Returns a promise which resolves, if successful, to an instance of MetadataReader.

toPassportConfig(reader)

Transforms metadata extracts for use in Passport strategy configuration. The following strategies are currently supported:

claimsToCamelCase(claims, claimSchema)

Translates the claim identifier URLs to human-friendly camelCase versions. Useful in Passport verifier functions.

claimSchema should be an object of the following format, such as from MetadataReader.claimSchema():

{
  [claimURL]: {
    name: claimUrl,
    camelCase: 'claimIdentifierInCamelCase',
    description: 'Some description'
  },
  ...
}

Example:

function verifier(profile, done) {
  profile = passportSamlMetadata.claimsToCamelCase(profile, reader.claimSchema);
  done(null, profile);
}

new MetadataReader(metadataXml, options)

Options parameter details:

  • authnRequestBinding: if set to HTTP-POST, will attempt to load identityProviderUrl/logoutUrl via HTTP-POST binding in metadata, otherwise defaults to HTTP-Redirect
  • throwExceptions: if set to true, will throw upon exception

Parses metadata XML and extracts the following properties:

metadata(app)(config = {})

Returns a function which sets up an Express application route to generate the metadata XML file for your application at /FederationMetadata/2007-06/FederationMetadata.xml. ADFS servers may import the resulting file to set up the relying party trust.

Config:

  • issuer (required) The unique application identifier, used to name the relying party trust; may be a URN or URL
  • callbackUrl (required) The absolute URL to redirect back to with the SAML assertion after logging in, usually https://hostname[:port]/login/callback
  • logoutCallbackUrl The absolute URL to redirect back to with the SAML assertion after logging out, usually https://hostname[:port]/logout

See compwright/passport-saml-example for a usage example.

Package Sidebar

Install

npm i @elm-street-technology/passport-saml-metadata

Weekly Downloads

32

Version

1.5.3

License

MIT

Unpacked Size

14.9 kB

Total Files

8

Last publish

Collaborators

  • idxbrokertm
  • john.lysen
  • darceloixest
  • tamlee_est
  • bondi
  • elmsttim
  • semcgee
  • pharv
  • nuex