SAML2-js
saml2-js
is a node module that abstracts away the complexities of the SAML protocol behind an easy to use interface.
Usage
Install with npm.
npm install saml2-js --save
Include the SAML library.
var saml2 = ;
Documentation
This library exports two constructors.
ServiceProvider
- Represents a service provider that relies on a trustedIdentityProvider
for authentication and authorization in the SAML flow.IdentityProvider
- Represents an online service that authenticates users in the SAML flow.
Options
An object that can contain the below options. All options are strings, unless specified otherwise. See note for more information on options.
entity_id
- Required - Unique identifier for the service provider, often the URL of the metadata file.private_key
- Required - (PEM format string) - Private key for the service provider.certificate
- Required - (PEM format string) - Certificate for the service provider.assert_endpoint
- Required - URL of service provider assert endpoint.force_authn
- (Boolean) - If true, forces re-authentication of users even if the user has a SSO session with the IdP. This can also be configured on the IdP or on a per-method basis.auth_context
- SpecifiesAuthnContextClassRef
. This can also be configured on a per-method basis.nameid_format
- Format for Name ID. This can also be configured on a per-method basis.sign_get_request
- (Boolean) - If true, signs the request. This can also be configured on the IdP or on a per-method basis.allow_unencrypted_assertion
- (Boolean) - If true, allows unencrypted assertions. This can also be configured on the IdP or on a per-method basis.
Returns the following functions
create_login_request_url(IdP, options, cb)
- Get a URL to initiate a login.redirect_assert(IdP, options, cb)
- Gets a SAML response object if the login attempt is valid, used for redirect binding.post_assert(IdP, options, cb)
- Gets a SAML response object if the login attempt is valid, used for post binding.create_logout_request_url(IdP, options, cb)
- Creates a SAML Request URL to initiate a user logout.create_logout_response_url(IdP, options, cb)
- Creates a SAML Response URL to confirm a successful IdP initiated logout.create_metadata()
- Returns the XML metadata used during the initial SAML configuration.
Example
var sp_options = entity_id: "https://sp.example.com/metadata.xml" private_key: fs certificate: fs assert_endpoint: "https://sp.example.com/assert" force_authn: true auth_context: comparison: "exact" class_refs: "urn:oasis:names:tc:SAML:1.0:am:password" nameid_format: "urn:oasis:names:tc:SAML:2.0:nameid-format:transient" sign_get_request: false allow_unencrypted_assertion: true // Call service provider constructor with options var sp = sp_options; // Example use of service provider. // Call metadata to get XML metatadata used in configuration. var metadata = sp;
Service provider function definitions ##### create_login_request_url(IdP, options, cb) Get a URL to initiate a login.
Takes the following arguments:
IdP
- IdPoptions
- An object that can contain the below options. All options are strings, unless specified otherwise. See note for more information on options.relay_state
- SAML relay state.auth_context
- SpecifiesAuthnContextClassRef
. This can also be configured on the SP.nameid_format
- Format for Name ID. This can also be configured on the SP.force_authn
- (Boolean) - If true, forces re-authentication of users even if the user has a SSO session with the IdP. This can also be configured on the IdP or SP.sign_get_request
- (Boolean) - If true, signs the request. This can also be configured on the IdP or SP.
cb(error, login_url, request_id)
- Callback called with the login URL and ID of the request.
Takes the following arguments:
IdP
- IdPoptions
- An object that can contain the below options. All options are strings, unless specified otherwise. See note for more information on options.cb(error, response)
- Callback called with the request response.
response_header: id: '_abc-1' destination: 'https://sp.example.com/assert' in_response_to: '_abc-2' type: 'authn_response' user: name_id: 'nameid' session_index: '_abc-3' attributes: 'http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname': 'Test'
Takes the following arguments:
IdP
- IdPoptions
- An object that can contain the below options. All options are strings, unless specified otherwise. See note for more information on options.cb(error, response)
- Callback called with the request response.
Takes the following arguments:
IdP
- IdP. Note: Can passsso_logout_url
instead of IdP.options
- An object that can contain the below options. All options are strings, unless specified otherwise. See note for more information on options.name_id
- Format for Name ID. This can also be configured on a per-method basis.session_index
- Session index to use for creating logout request.allow_unencrypted_assertion
- (Boolean) - If true, allows unencrypted assertions. This can also be configured on the IdP or SP.sign_get_request
- (Boolean) - If true, signs the request. This can also be configured on the IdP or SP.relay_state
- SAML relay state.
cb(error, request_url)
- Callback called with the logout request url.
Takes the following arguments:
##### create_metadata() Returns the XML metadata used during the initial SAML configuration. ### IdentityProvider(options) Represents an online service that authenticates users in the SAML flow.Returns no functions, exists solely to be passed to an SP function.
Options
An object that can contain the below options. All options are strings, unless specified otherwise. See note for more information on options.
sso_login_url
- Required - Login url to use during a login request.sso_logout_url
- Required - Logout url to use during a logout request.certificates
- Required - (PEM format string or array of PEM format strings) - Certificate or certificates (array of certificate) for the identity provider.force_authn
- (Boolean) - If true, forces re-authentication of users even if the user has a SSO session with the IdP. This can also be configured on the SP or on a per-method basis.sign_get_request
- (Boolean) - If true, signs the request. This can also be configured on the [SP or on a per-method basis.allow_unencrypted_assertion
- (Boolean) - If true, allows unencrypted assertions. This can also be configured on the SP or on a per-method basis.
Example
// Initialize options object var idp_options = sso_login_url: "https://idp.example.com/login" sso_logout_url: "https://idp.example.com/logout" certificates: fs fs force_authn: true sign_get_request: false allow_unencrypted_assertion: false ; // Call identity provider constructor with options var idp = idp_options; // Example usage of identity provider. // Pass identity provider into a service provider function with options and a callback. sp;
Example: Express implementation
Library users will need to implement a set of URL endpoints, here is an example of express endpoints.
var saml2 = ;var fs = ;var express = ;var app = ; // Create service providervar sp_options = entity_id: "https://sp.example.com/metadata.xml" private_key: fs certificate: fs assert_endpoint: "https://sp.example.com/assert";var sp = sp_options; // Create identity providervar idp_options = sso_login_url: "https://idp.example.com/login" sso_logout_url: "https://idp.example.com/logout" certificates: fs fs;var idp = idp_options; // ------ Define express endpoints ------ // Endpoint to retrieve metadataapp; // Starting point for loginapp; // Assert endpoint for when login completesapp; // Starting point for logoutapp; app;