Skip to content
master
Switch branches/tags
Go to file
Code
This branch is 65 commits ahead of danroot:master.

Latest commit

 

Git stats

Files

Permalink
Failed to load latest commit information.
Type
Name
Latest commit message
Commit time
 
 
src
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

README.md

passport-saml-metadata

Build Status Dependency Status Download Status

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:

  • client Axios instance
  • 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())

Additional configuration options supported: https://github.com/axios/axios#request-config

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

toPassportConfig(reader, options = { multipleCerts: false })

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

Config:

  • multipleCerts (boolean): causes the full array of signing certificates to be passed to the passport config instead of assuming the last certificate is the most recent one. Note: this option is not compatible with passport-wsfed-saml2.

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.

About

SAML 2.0 Metadata utilities for PassportJS

Topics

Resources

Sponsor this project