Skip to content



Repository files navigation


Build Status Download Status

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


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 = '';

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.


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.


  • 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:

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:


  • 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'


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:


  • query(query) - queries the metadataXml using XPath.

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.


  • 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.

Sponsor this project



  • JavaScript 99.0%
  • Makefile 1.0%