samlify

The sp.parseLoginResponse method resolves to a parseResult object containing the raw SAML content and an extract object. The extract object contains processed fields where inner attribute keys are camelCased (e.g., NotBefore becomes notBefore).

Key fields in extract include:

• response: Metadata about the response (id, issueInstant, destination, inResponseTo).
• issuer: The IdP issuer URL.
• nameID: The unique identifier for the user.
• audience: The intended audience for the assertion.
• conditions: Time-based constraints (notBefore, notOnOrAfter).
• sessionIndex: Session details (authnInstant, sessionNotOnOrAfter, sessionIndex).
• attributes: A map of user attributes (e.g., email, firstName).

{
  samlContent: "<samlp:Response ...",
  extract: {
    response: {
      id: "_8e8dc5f69a98cc4c1ff3427e5ce34606fd672f91e6",
      issueInstant: "2015-10-26T11:41:43.500Z",
      destination: "https://sp.example.org/sso/acs",
      inResponseTo: "_4fee3b046395c4e751011e97f8900b5273d56685"
    },
    issuer: "https://idp.example.org/sso/metadata",
    nameID: "user@esaml2.com",
    audience: "https://sp.example.org/sso/metadata",
    conditions: {
      notBefore: "2015-10-26T11:41:43.500Z",
      notOnOrAfter: "2015-10-26T11:46:43.500Z"
    },
    sessionIndex: {
      authnInstant: "2015-10-26T11:41:43.500Z",
      sessionNotOnOrAfter: "2015-10-26T19:41:43.500Z",
      sessionIndex: "_be9967abd904ddcae3c0eb4189adbe3f71e327cf93"
    },
    attributes: {
      email: "user@esaml2.com",
      lastName: "Samuel",
      firstName: "E"
    }
  }
}

When different Identity Providers require different Service Provider configurations (for example, if one IdP requires signed requests while another does not), you should maintain one ServiceProvider instance per IdP. At runtime, you must select both the correct sourceSP and the correct targetIdP based on the incoming request parameters.

// Define the default SP.
const defaultSP = saml.ServiceProvider({
  metadata: fs.readFileSync('./metadata_sp.xml')
});

// Define an SP specifically configured for OneLogin.
const oneloginSP = saml.ServiceProvider({
  metadata: fs.readFileSync('./metadata_sp_for_oneLogin.xml')
});

// Define the default IdP.
const defaultIdP = saml.IdentityProvider({
  metadata: fs.readFileSync('./metadata_idp_default.xml')
});

// Define the OneLogin IdP.
const oneloginIdP = saml.IdentityProvider({
  metadata: fs.readFileSync('./metadata_idp_onelogin.xml')
});

// SP-initiated SSO route, parameterised by IdP name.
router.get('/spinitsso-post/:idp', (req, res) => {
  let targetIdP;
  let sourceSP;
  switch (req.params.idp || '') {
    case 'onelogin':
      targetIdP = oneloginIdP;
      sourceSP = oneloginSP;
      break;
    default:
      targetIdP = defaultIdP;
      sourceSP = defaultSP;
      break;
  }
  return sourceSP.createLoginRequest(targetIdP, 'post', (req, res) => res.render('actions', req));
});

The HTTP-POST binding delivers the SAML request via an auto-submitting HTML form. This is useful when the request size exceeds URL length limits.

To implement this, use sp.createLoginRequest(idp, 'post'). This returns an object containing the necessary data (like entityEndpoint, type, context, and relayState) to be rendered into an HTML form. The form should use method="post" and then automatically submit via JavaScript.

// Server-side: render the form object returned by createLoginRequest
router.get('/spinitsso-redirect', (req, res) => {
  res.render('actions', sp.createLoginRequest(idp, 'post'));
});

// Client-side template (e.g., Handlebars):
<form id="saml-form" method="post" action="{{entityEndpoint}}" autocomplete="off">
    <input type="hidden" name="{{type}}" value="{{context}}" />
    {{#if relayState}}
        <input type="hidden" name="RelayState" value="{{relayState}}" />
    {{/if}}
</form>
<script type="text/javascript">
    (function () {
        document.forms[0].submit();
    })();
</script>

You can construct an IdentityProvider instance by providing an existing SAML metadata document. This document serves as the contract between the Service Provider (SP) and the IdP for SSO/SLO. When using metadata, you can also provide private keys for signing and encryption.

Required parameter:

• metadata: string — The IdP-issued metadata XML string.

Common optional parameters:

• privateKey: string — The private key used for signing.
• privateKeyPass: string — The passphrase for the private key.
• encPrivateKey: string — The private key used for encryption.
• encPrivateKeyPass: string — The passphrase for the encryption private key.
• isAssertionEncrypted: boolean — Whether the IdP encrypts the assertion in the response (Note: This option is deprecated and will be removed; samlify will detect encryption automatically).

const idp = new IdentityProvider({
  // Required.
  metadata: readFileSync('./test/misc/idpmeta.xml'),
  // Optional.
  privateKey: readFileSync('./test/key/idp/privkey.pem'),
  privateKeyPass: 'q9ALNhGT5EhfcRmp8Pg7e9zTQeP2x1bW',
  encPrivateKey: readFileSync('./test/key/idp/encryptKey.pem'),
  encPrivateKeyPass: 'g7hGcRmp8PxT5QeP2q9Ehf1bWe9zTALN',
  isAssertionEncrypted: true,
});

If you do not have a metadata document, you can construct a ServiceProvider entirely from a configuration object. This allows you to manually define the SP's identity and capabilities.

Required parameter:

• entityID: string — Entity identifier used to identify the SP and match values in SAML requests/responses.

Common optional parameters:

• authnRequestsSigned: boolean — Whether the SP signs its AuthnRequest. Defaults to false.
• wantAssertionsSigned: boolean — Whether the SP requires signed assertions. Defaults to false.
• wantMessageSigned: boolean — Whether the SP requires signed SAML messages. Defaults to false.
• signingCert: string — Certificate used for signing.
• encryptCert: string — Certificate used for encryption.
• elementsOrder: string[] — DOM element ordering for generated metadata. Defaults to ['KeyDescriptor', 'NameIDFormat', 'SingleLogoutService', 'AssertionConsumerService'].
• nameIDFormat: NameIDFormat[] — Supported NameID formats. The first entry is used in outbound requests.
• singleLogoutService: Service[] — Single Logout endpoints.
• assertionConsumerService: Service[] — Endpoints where the IdP posts SAML responses.
• signatureConfig: SignatureConfig — Signature placement and layout options.

const sp = new ServiceProvider({
  // Required.
  entityID: 'http://hello-saml-sp.com/metadata',
  // Optional parameters listed below.
});

To handle a SAML response from an Identity Provider (IdP), you must implement an Assertion Consumer Service (ACS) endpoint. This endpoint receives the SAML response (typically via HTTP-POST) and uses sp.parseLoginResponse to parse the XML and extract authentication data.

Implementation Steps

1. Define an ACS Endpoint: Create a route (e.g., in Express) that matches the Location declared in your Service Provider (SP) metadata.
2. Call parseLoginResponse: Pass the IdP instance, the binding type ('post'), and the request object.
3. Handle the Result: On success, use the parseResult.extract object to access user attributes and session info. On failure, catch the error (e.g., if the SAML status code indicates failure).

Note: If WantAssertionsSigned is set in your SP metadata, parseLoginResponse will automatically verify the XML signature and the Issuer name.

router.post('/acs', (req, res) => {
  sp.parseLoginResponse(idp, 'post', req)
    .then(parseResult => {
      // Use parseResult.extract to run your business logic.
    })
    .catch(console.error);
});