passport-saml-metadata
v4.0.0
Published
SAML2 metadata loader
Downloads
55,597
Maintainers
Readme
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-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 instanceurl
(required) Metadata XML file URLtimeout
Time to wait before falling back to thebackupStore
, in ms (default =2000
)backupStore
Any 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-Redirect
throwExceptions
: 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/)signingCert
encryptionCert
claimSchema
- an object hash of claim identifiers that may be provided in the SAML assertion
Methods:
query(query)
- queries themetadataXml
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.
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/callbacklogoutCallbackUrl
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.