compwright
passport-saml-metadata
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-metadataUsage 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:
clientAxios instanceurl(required) Metadata XML file URLtimeoutTime to wait before falling back to thebackupStore, in ms (default =2000)backupStoreAny persistent cache adapter object withget(key)andset(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 toHTTP-POST, will attempt to load identityProviderUrl/logoutUrl via HTTP-POST binding in metadata, otherwise defaults toHTTP-RedirectthrowExceptions: if set totrue, will throw upon exception
Parses metadata XML and extracts the following properties:
identifierFormat(e.g.urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress)identityProviderUrl(e.g. https://adfs.server.url/adfs/ls/)logoutUrl(e.g. https://adfs.server.url/adfs/ls/)signingCertencryptionCertclaimSchema- an object hash of claim identifiers that may be provided in the SAML assertion
Methods:
query(query)- queries themetadataXmlusing 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.
Config:
issuer(required) The unique application identifier, used to name the relying party trust; may be a URN or URLcallbackUrl(required) The absolute URL to redirect back to with the SAML assertion after logging in, usually https://hostname[:port]/login/callbacklogoutCallbackUrlThe 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.