# Node SAML

[![Build Status](https://github.com/node-saml/node-saml/actions/workflows/workflow.yml/badge.svg?branch=master)](https://github.com/node-saml/node-saml/actions/workflows/workflow.yml)
[![npm version](https://badge.fury.io/js/@node-saml%2Fnode-saml.svg)](https://badge.fury.io/js/@node-saml%2Fnode-saml)
[![code style: prettier](https://img.shields.io/badge/code_style-prettier-ff69b4.svg?style=flat-square)](https://github.com/prettier/prettier)
[![codecov](https://codecov.io/gh/node-saml/node-saml/branch/master/graph/badge.svg?token=PQWCMBWBFB)](https://codecov.io/gh/node-saml/node-saml)
[![DeepScan grade](https://deepscan.io/api/teams/17569/projects/20921/branches/586237/badge/grade.svg)](https://deepscan.io/dashboard#view=project&tid=17569&pid=20921&bid=586237)

[![NPM](https://nodei.co/npm/@node-saml/node-saml.png?downloads=true&downloadRank=true&stars=true)](https://nodei.co/npm/@node-saml/node-saml)

A [SAML 2.0](https://en.wikipedia.org/wiki/SAML_2.0) implementation for Node.js. It acts as the
service provider (SP) half of a SAML exchange: it builds the `AuthnRequest` and logout messages you
send to an identity provider (IdP), and it decides whether the responses that come back are
trustworthy.

This package is transport-agnostic and framework-agnostic — it takes strings in and hands strings
out, and you wire it into whatever HTTP layer you already have. If your application uses
[Passport](https://www.passportjs.org/), reach for
[`@node-saml/passport-saml`](https://github.com/node-saml/passport-saml) instead; it wraps this
library in a Passport strategy.

- [Sponsors](#sponsors)
- [Installation](#installation)
- [Usage](#usage)
  - [Create a `SAML` instance](#create-a-saml-instance)
  - [Start a login](#start-a-login)
  - [Validate the response](#validate-the-response)
  - [The profile](#the-profile)
  - [Single logout (SLO)](#single-logout-slo)
  - [Service provider metadata](#service-provider-metadata)
- [Config parameter details](#config-parameter-details)
- [Security and signatures](#security-and-signatures)
- [Response validation timestamps](#response-validation-timestamps)
- [InResponseTo validation](#inresponseto-validation)
- [Cache provider](#cache-provider)
- [Node support policy](#node-support-policy)
- [Contributing](#contributing)
- [Changelog](#changelog)

## Sponsors

We gratefully acknowledge support from our sponsors:

<div align="center">
  <a href="https://stytch.com">
    <picture>
      <source width="200px" media="(prefers-color-scheme: dark)" srcset="./sponsor/stytch-light.svg">
      <source width="200px" media="(prefers-color-scheme: light)" srcset="./sponsor/stytch-dark.svg">
      <img width="200px" alt="Stytch" src="./sponsor/stytch-dark.svg" />
    </picture>
  </a>
   <p align="center">
      <a href="https://stytch.com/?utm_source=oss-sponsorship&utm_medium=paid_sponsorship&utm_campaign=nodesaml">
        <b>The identity platform for humans & AI agents</b><br/>
        One integration for authentication, authorization, and security
      </a>
   </p>
</div>

- [RideAmigos](https://rideamigos.com/)

If your company benefits from node-saml being secure and up-to-date, consider asking them to sponsor the project at $25/month. See the [Github Sponsors page](https://github.com/sponsors/cjbarth) for more sponsorship levels. It's easy to do, appearing as another line-item on the Github bill they already have.

## Installation

```shell
npm install @node-saml/node-saml
```

TypeScript type definitions ship with the package; there is no separate `@types` package to install.
See the [Node support policy](#node-support-policy) for supported runtimes.

## Usage

### Create a `SAML` instance

```javascript
const fs = require("node:fs");
const { SAML } = require("@node-saml/node-saml");

const saml = new SAML({
  // Required
  callbackUrl: "https://sp.example.com/login/callback",
  issuer: "https://sp.example.com/metadata",
  idpCert: fs.readFileSync("./idp-signing-cert.pem", "utf-8"),

  // Where to send the user to authenticate
  entryPoint: "https://idp.example.com/sso",

  // Accept only responses to requests we made; see "InResponseTo".
  validateInResponseTo: "always",

  // Sign our own requests. Set the algorithms explicitly; see "Security and signatures".
  privateKey: fs.readFileSync("./sp-private-key.pem", "utf-8"),
  publicCert: fs.readFileSync("./sp-public-cert.pem", "utf-8"),
  signatureAlgorithm: "sha256",
  digestAlgorithm: "sha256",
});
```

`callbackUrl`, `issuer`, and `idpCert` are required. Omitting one throws a `TypeError` naming the
option, and so does passing a non-boolean to an option that gates behavior — for example the string
`"false"`. All of this happens in the constructor, so a misconfiguration surfaces at startup rather
than in the middle of someone's login.

In TypeScript, the constructor takes a `SamlConfig` and `saml.options` is a `SamlOptions`. Both are
exported from the package root, and so is every other type the package's API uses: `Profile`,
`CacheProvider`, `CacheItem`, `InMemoryCacheProvider` and its `CacheProviderOptions`,
`ValidateInResponseTo`, `RacComparison`, `SignatureAlgorithm`, `SamlSigningOptions`,
`SamlScopingConfig`, `SamlIDPListConfig`, `SamlIDPEntryConfig`, `IdpCertCallback`, `AuthOptions`,
`MandatorySamlOptions`, `SamlStatusError`, `GenerateServiceProviderMetadataParams`, and the XML types
that `SAML`'s protected methods use: `XMLOutput`, `XmlJsObject`, `AudienceRestrictionXML`,
`XMLObject`, and `XMLValue`.

Import from the package root only. The compiled modules under `lib/` are internal: nothing there is
part of the API unless the root exports it. The next major version closes that path, so a deep
import will fail to load with `ERR_PACKAGE_PATH_NOT_EXPORTED`. Anything the root exports moves over
unchanged:

```typescript
// deprecated: fails to load in the next major version
import { SAML } from "@node-saml/node-saml/lib/saml";
import type { Profile } from "@node-saml/node-saml/lib/types";

// use this instead
import { SAML, type Profile } from "@node-saml/node-saml";
```

The root doesn't export the XML helpers under `lib/`, such as `parseDomFromString`, `xpath`,
`signXml`, and `signSamlPost`. They wrap `@xmldom/xmldom`, `xpath`, and `xml-crypto`, so depend on
those packages directly instead.

### Start a login

All three of these require `entryPoint` to be set.

**HTTP-Redirect binding** — build a URL and redirect to it:

```javascript
const url = await saml.getAuthorizeUrlAsync(relayState, options);
res.redirect(url);
```

`relayState` is echoed back by the IdP and is omitted from the request when it is an empty string.
`options` is an `AuthOptions`, whose `additionalParams` override anything set by
`additionalParams`/`additionalAuthorizeParams` in the constructor.

The URL never carries an empty `RelayState`, because identity providers differ on whether a
signature covers one. A `RelayState` of `""` in `additionalParams` means "send none", even when
`entryPoint` has one of its own. From JavaScript, where the types do not stop it, `null` or
`undefined` there means none was given, like an empty `relayState` argument, and one in `entryPoint`
is still sent. The next major version reads an empty `relayState` argument as "send none" too, and
takes `null` or `undefined` to mean none was given.

All three of these methods also accept a deprecated `host` argument between `relayState` and
`options`. It is ignored, and it is removed in the next major version, so pass `options` directly:

```javascript
await saml.getAuthorizeUrlAsync(relayState, host, options); // deprecated
await saml.getAuthorizeUrlAsync(relayState, options); // use this
```

If you subclass `SAML` and override one of these, migrate the override at the same time: a
two-argument call reaches it directly, so an override written for the old signature receives
`options` as `host`.

**HTTP-POST binding** — return a self-submitting form:

```javascript
const html = await saml.getAuthorizeFormAsync(relayState, options);
res.send(html);
```

This returns a complete HTML document that posts to `entryPoint` on load, with a `<noscript>`
fallback button for browsers without JavaScript.

If you would rather build the form yourself, `getAuthorizeMessageAsync(relayState, options)`
returns the message as a plain object of form fields (`SAMLRequest` plus any additional parameters).

### Validate the response

The IdP posts the response back to your `callbackUrl` as a form-encoded `SAMLResponse` field, so the
route needs a body parser.

```javascript
app.post("/login/callback", express.urlencoded({ extended: false }), async (req, res, next) => {
  try {
    const { profile, loggedOut } = await saml.validatePostResponseAsync(req.body);
    // profile is the authenticated user; see "The profile" below
  } catch (err) {
    next(err);
  }
});
```

`validatePostResponseAsync` rejects with an `Error` on anything it cannot vouch for, and the message
says what failed — an invalid signature, a mismatched audience, an expired assertion, and a missing
decryption key are all distinguishable. Nothing is returned for a document that did not verify. If
something between Node-SAML and you hides that message, run with `NODE_DEBUG=node-saml` to have it
logged; see [Troubleshooting](#troubleshooting).

Two cases resolve without a `profile`:

- The IdP returned a `LogoutResponse` rather than an authentication response:
  `{ profile: null, loggedOut: true }`. One whose status is not `Success`, or whose `Issuer` is not
  `idpIssuer` when that is set, is rejected with an `Error`, such as `Bad status code: …`, as it is
  over the Redirect binding.
- A `passive` request could not be satisfied without user interaction (a `NoPassive` status on a
  validly signed response): `{ profile: null, loggedOut: false }`.

When the IdP reports a non-`Success` status in a `Response`, the rejection is a `SamlStatusError`
whose `xmlStatus` property carries the `Status` element as XML, so you can surface the IdP's own
reason to the user. Be aware that the signature requirement is applied first: many identity
providers do not sign their error responses, and under the default `wantAuthnResponseSigned: true`
such a response is rejected for the missing signature before its status is read.

### The profile

`profile` is a `Profile`: the fields the library understands, plus every `AttributeValue` in the
assertion keyed by its `Name`. What is populated depends on the message, so check for the fields you
rely on rather than assuming they are all present.

| Field                              | Description                                                                                                      |
| ---------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| `issuer`                           | The assertion's `Issuer`.                                                                                        |
| `nameID`, `nameIDFormat`           | The subject's name identifier and its format.                                                                    |
| `nameQualifier`, `spNameQualifier` | Name qualifiers, when the assertion carries them.                                                                |
| `sessionIndex`                     | The `AuthnStatement`'s `SessionIndex`; you need it to build a logout request.                                    |
| `inResponseTo`                     | The `InResponseTo` a signature covers: the `Response`'s if signed, else the `SubjectConfirmationData`'s.         |
| `mail`, `email`                    | Convenience aliases. `mail` falls back to `urn:oid:0.9.2342.19200300.100.1.3`, and `email` falls back to `mail`. |
| `attributes`                       | Every attribute as a `Name` → value map. Single-valued attributes are strings; repeated ones are arrays.         |
| `getAssertionXml()`                | The assertion XML **that the signature covers**. This is the trustworthy copy.                                   |
| `getAssertion()`                   | The same assertion, parsed into a JavaScript object.                                                             |
| `getSamlResponseXml()`             | **Deprecated.** The response XML as received, **not as verified**. See the warning below.                        |

Attributes are also copied onto `profile` at the top level for convenience, but an attribute never
overwrites a field the library set itself.

The profile returned for a `LogoutRequest` by `validatePostRequestAsync` and `validateRedirectAsync`
is a smaller thing: `ID` (the logout request's own ID), `issuer`, `nameID`, `nameIDFormat`, and
`sessionIndex`. It carries no attributes and none of the getters, since there is no assertion.

> **Warning:** `getSamlResponseXml()` returns the response document as it arrived. When the IdP signs
> only the assertion, nothing around it — the response's `Issuer`, `Status`, and timestamps — is
> covered by any signature, and the method does not tell you whether that was the case. Never treat
> what you read from it as authenticated.

`getSamlResponseXml()` is deprecated and is removed in the next major version; calling it logs a
warning under `NODE_DEBUG=node-saml`. Read the verified assertion instead:

```javascript
profile.getSamlResponseXml(); // deprecated
profile.getAssertionXml(); // use this, or getAssertion() for the parsed form
```

#### Attributes with no value

An attribute sent without a usable value reaches the profile in one of two ways:

```xml
<Attribute Name="roles"/>                                            <!-- left out -->
<Attribute Name="team"><AttributeValue/></Attribute>                 <!-- undefined -->
<Attribute Name="team"><AttributeValue xsi:nil="true"/></Attribute>  <!-- undefined -->
```

The first is left out, so it looks the same as an attribute the identity provider did not send. The
others are present with the value `undefined`, which `JSON.stringify` drops and code commonly treats
as absent.

The next major version keeps the first with a `null` value, and represents an empty `AttributeValue`
as the empty string and one marked `xsi:nil` as `null`, which is what they mean in
[SAML core §2.7.3.1.1](https://docs.oasis-open.org/security/saml/v2.0/saml-core-2.0-os.pdf). Run
with `NODE_DEBUG=node-saml` to be told which attributes in a response you received are affected.

Code that tests for a missing value with `== null`, and reads a value that may be empty with
`?? ""`, works with both versions:

```javascript
// an attribute with no AttributeValue, or one marked xsi:nil, is undefined now and null in the
// next major version, so this test stops matching it
if (profile.roles === undefined) {
  /* ... */
}

// this test matches it in both
if (profile.roles == null) {
  /* ... */
}

// an empty AttributeValue is undefined now and "" in the next major version; `team` is "" in both
const team = profile.team ?? "";
```

### Single logout (SLO)

Node-SAML supports SP-initiated and IdP-initiated logout, over both the `Redirect` and `POST`
bindings, including signature validation and decryption of encrypted name identifiers.

**SP-initiated.** Build a `LogoutRequest` URL for a user you previously authenticated. The `profile`
you pass needs at least `nameID`, `nameIDFormat`, and — if the IdP expects it — `sessionIndex`:

```javascript
const url = await saml.getLogoutUrlAsync(profile, relayState, options);
res.redirect(url);
```

The request goes to `logoutUrl`, which defaults to `entryPoint`.

**IdP-initiated over POST.** Validate the incoming `LogoutRequest`, then answer it:

```javascript
const { profile } = await saml.validatePostRequestAsync(req.body);
const url = await saml.getLogoutResponseUrlAsync(profile, relayState, options, true);
res.redirect(url);
```

`getLogoutResponseUrl(profile, relayState, options, success, callback)` is the callback-style
equivalent of `getLogoutResponseUrlAsync`.

`validatePostRequestAsync` also accepts a deprecated second argument, an object of injected
dependencies — `_parseDomFromString`, `_parseXml2JsFromString` and `_validateSignature`. It is
ignored: nothing passed there can substitute signature verification, which the last of those used to
do. The argument is removed in the next major version, and calling it that way logs a warning under
`NODE_DEBUG=node-saml`:

```javascript
await saml.validatePostRequestAsync(req.body, { _validateSignature }); // deprecated, and ignored
await saml.validatePostRequestAsync(req.body); // use this
```

**Over the Redirect binding.** A Redirect-binding signature covers the `SAMLRequest` or
`SAMLResponse`, the `RelayState` if there is one, and `SigAlg`, byte for byte as they arrived.
Nothing else in the query string is signed. Hand the raw query string through unchanged, without
its leading `?`:

```javascript
const originalQuery = req.url.slice(req.url.indexOf("?") + 1);
const { profile, loggedOut, relayState } = await saml.validateRedirectAsync(originalQuery);
```

Node-SAML reads the `SAMLRequest` or `SAMLResponse`, `RelayState`, `SigAlg` and `Signature` from
that string, requires the signature to verify, and returns the `RelayState` that was signed. Use
that `relayState`, and not the one in a parsed query object such as `req.query`: a query parser can
read a parameter that the signature does not cover as `RelayState`. A query string with more than
one of any of those five parameters, or with both a `SAMLRequest` and a `SAMLResponse`, is
rejected, and so is a message with no `Signature`.

`validateRedirectAsync` also accepts a deprecated first argument, the parsed query object, before
the query string. That form is removed in the next major version, and calling it logs a warning
under `NODE_DEBUG=node-saml`:

```javascript
await saml.validateRedirectAsync(req.query, originalQuery); // deprecated
await saml.validateRedirectAsync(originalQuery); // use this, and the `relayState` it returns
```

The deprecated form returns no `relayState`. A signed message is read from `originalQuery` there
too, and is treated as signed when either argument has a `Signature`, even an empty one. Because
its caller goes on reading the parsed object, it also rejects a signed query string that names one
of the five parameters in bracket notation, such as `RelayState[]` or `[RelayState]`, which the
`qs` parser reads as `RelayState`. It rejects a signed message, too, when the parsed object holds a
`RelayState` that is not the one in `originalQuery`, as it does when the parser splits or nests the
query string by other rules: one that also splits on `;` reads `x=1;RelayState=...` as a
`RelayState`.

> **Note:** the deprecated form still accepts a message with no `Signature` parameter, because the
> binding makes signing optional. Such a message is accepted with none of its contents
> authenticated — the issuer and the timestamps are read from the same unsigned bytes, so
> `idpIssuer` only checks a value the sender wrote and does not show who sent it. Run with
> `NODE_DEBUG=node-saml` to be told when this happens. Configure your IdP to sign its logout
> messages before you move to `validateRedirectAsync(originalQuery)`, which rejects unsigned ones,
> as the next major version does for every call. The POST binding is unaffected:
> `validatePostRequestAsync` always requires a valid signature.

On the POST binding the profile is built only from the bytes that signature covers. The signature
has to envelope the message the way
[SAML core §5.4](https://docs.oasis-open.org/security/saml/v2.0/saml-core-2.0-os.pdf) and the
protocol schema require — a `ds:Signature` that is a child of the `LogoutRequest` element it
references — so a request whose signature sits elsewhere in the document is rejected even though
that signature verifies.

### Service provider metadata

Most identity providers will take a metadata document instead of asking you to type the same values
into a form.

```javascript
const metadata = saml.generateServiceProviderMetadata(decryptionCert, publicCerts);
```

- `decryptionCert` — the public certificate matching `decryptionPvk`. Required if the instance was
  configured with `decryptionPvk`; pass `null` otherwise.
- `publicCerts` — the public certificate matching `privateKey`. Required if the instance was
  configured with `privateKey`. Pass an array to support certificate rotation: the first entry must
  match the current `privateKey`, and later entries publish upcoming certificates to the IdP before
  you switch over.

Both are read by the rules described under [`privateKey`](#configuration-option-privatekey), as PEM or
as Base64, and published as a single line of Base64. `decryptionCert`, and each entry of
`publicCerts`, must hold exactly one certificate; a value holding several, or holding a public key
rather than a certificate, is refused with an error naming it.

The underlying function is also exported directly, for generating metadata without constructing a
`SAML` instance:

```javascript
const { generateServiceProviderMetadata } = require("@node-saml/node-saml");

const metadata = generateServiceProviderMetadata({
  issuer: "https://sp.example.com/metadata",
  callbackUrl: "https://sp.example.com/login/callback",
});
```

It accepts `issuer` and `callbackUrl` plus the metadata-relevant options from the configuration tables below:
`logoutCallbackUrl`, `identifierFormat`, `wantAssertionsSigned`, `decryptionPvk`, `decryptionCert`,
`privateKey`, `publicCerts`, `signatureAlgorithm`, `digestAlgorithm`, `xmlSignatureTransforms`,
`signMetadata`, `metadataContactPerson`, `metadataOrganization`,
`metadataAttributeConsumingServices`, and `generateUniqueId`.

Called directly, it signs the metadata when `signMetadata` is `true` and `privateKey` is set. Choose
both algorithms when it does: `signatureAlgorithm` has no default here, so omitting it is an error,
while an omitted `digestAlgorithm` selects `sha1`, or is an error too when `signatureAlgorithm` is
`"sha256-mgf1"`. The note under [`signatureAlgorithm`](#configuration-option-signaturealgorithm)
applies to this function too, and it logs the same warnings under `NODE_DEBUG=node-saml`.

## Config parameter details

### Required

| Option        | Type                                    | Description                                                                                                                                       |
| ------------- | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `callbackUrl` | `string`                                | The SP endpoint the IdP posts the response back to; becomes the `AssertionConsumerServiceURL`.                                                    |
| `issuer`      | `string`                                | The issuer string identifying this service provider to the IdP.                                                                                   |
| `idpCert`     | `string \| string[] \| IdpCertCallback` | The IdP's signing certificate(s) or public key(s), used to validate incoming signatures. See [Security and signatures](#security-and-signatures). |

The next major version checks received responses against `callbackUrl`: an assertion has to carry a
bearer `SubjectConfirmation` whose `Recipient` is `callbackUrl`
([SAML profiles §4.1.4.3](https://docs.oasis-open.org/security/saml/v2.0/saml-profiles-2.0-os.pdf)),
and a signed `Response` has to carry a `Destination` that is `callbackUrl`
([SAML bindings §3.5.5.2](https://docs.oasis-open.org/security/saml/v2.0/saml-bindings-2.0-os.pdf)).
URLs are compared after parsing, so the case of the scheme and host and an explicit default port
don't count, but the path does, trailing slash included. Until then a response that fails either
check is accepted. Run with `NODE_DEBUG=node-saml` to be told when one arrives, and set
`callbackUrl` to the URL your IdP actually posts to.

### Core

| Option                   | Default                        | Description                                                                                                                                                                                       |
| ------------------------ | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `entryPoint`             | —                              | The IdP's SSO endpoint. Required to generate any authentication request, and required by the specification when the request is signed.                                                            |
| `audience`               | `issuer`                       | Expected `Audience` in the response. Set to `false` to skip the check — which removes a security control; see the note under [Security and signatures](#security-and-signatures).                 |
| `privateKey`             | —                              | SP private key in PEM format, used to sign outgoing messages. See [Security and signatures](#security-and-signatures).                                                                            |
| `publicCert`             | —                              | SP public signing certificate, embedded in the `AuthnRequest` so the IdP can verify it. Must match `privateKey`.                                                                                  |
| `decryptionPvk`          | —                              | Private key used to decrypt encrypted assertions and encrypted name identifiers. See [Configuration option `decryptionPvk`](#configuration-option-decryptionpvk).                                 |
| `signatureAlgorithm`     | `"sha1"`                       | `"sha1"`, `"sha256"`, `"sha256-mgf1"`, or `"sha512"`. **Set this explicitly** if you set `privateKey`; see [Configuration option `signatureAlgorithm`](#configuration-option-signaturealgorithm). |
| `digestAlgorithm`        | `"sha1"`                       | Digest algorithm for the signed data object: `"sha1"`, `"sha256"`, or `"sha512"`. Same advice as above. Required with `"sha256-mgf1"`.                                                            |
| `xmlSignatureTransforms` | enveloped-signature + exc-c14n | Signature transforms used in HTTP-POST signatures. The default is `["http://www.w3.org/2000/09/xmldsig#enveloped-signature", "http://www.w3.org/2001/10/xml-exc-c14n#"]`.                         |
| `generateUniqueId`       | built-in                       | Function returning the unique IDs used for outgoing SAML messages.                                                                                                                                |

### Response validation

| Option                     | Default | Description                                                                                                                                                                           |
| -------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `wantAssertionsSigned`     | `true`  | Require the assertion itself to be signed, and advertise `WantAssertionsSigned="true"` in the metadata.                                                                               |
| `wantAuthnResponseSigned`  | `true`  | Require the response to be signed at the top level, not only at the assertion.                                                                                                        |
| `acceptedClockSkewMs`      | `0`     | Tolerance in milliseconds when checking `NotBefore` and `NotOnOrAfter`. `-1` disables those checks entirely.                                                                          |
| `maxAssertionAgeMs`        | `0`     | Reject an assertion older than this, measured from its `IssueInstant`. `0` means no limit beyond `NotOnOrAfter`. When set and stricter than `NotOnOrAfter`, this wins.                |
| `rejectReplayedAssertions` | `false` | Reject an assertion whose ID has been received before. See [Replayed assertions](#replayed-assertions).                                                                               |
| `idpIssuer`                | —       | If set, it must match the `Issuer` of the assertion, of logout messages, and of a signed `Response` that has one. For ADFS this looks like `https://acme_tools.windows.net/deadbeef`. |

Turning both `wantAssertionsSigned` and `wantAuthnResponseSigned` off does not turn signature
checking off: either the response or the assertion still has to carry a valid signature, or the
document is rejected.

### AuthnRequest content

| Option                           | Default                                                                 | Description                                                                                                                                                                                                         |
| -------------------------------- | ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `identifierFormat`               | `urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress`                | `NameID` format to request. Set to `null` to leave the `Format` attribute off the `NameIDPolicy` and the `NameIDFormat` element out of the metadata.                                                                |
| `allowCreate`                    | `true`                                                                  | Let the IdP create a new subject identifier.                                                                                                                                                                        |
| `spNameQualifier`                | —                                                                       | Request that the subject identifier be returned or created in another SP's namespace, or in that of an affiliation of service providers.                                                                            |
| `authnContext`                   | `["urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport"]` | Requested authentication context classes. Must be an array, even for a single value.                                                                                                                                |
| `racComparison`                  | `"exact"`                                                               | How the IdP should compare the requested context: `"exact"`, `"minimum"`, `"maximum"`, or `"better"`.                                                                                                               |
| `disableRequestedAuthnContext`   | `false`                                                                 | Omit `RequestedAuthnContext` entirely.                                                                                                                                                                              |
| `forceAuthn`                     | `false`                                                                 | Ask the IdP to re-authenticate the user even if they hold a valid session.                                                                                                                                          |
| `passive`                        | `false`                                                                 | Ask the IdP not to take visible control of the user interface. See the `NoPassive` case in [Validate the response](#validate-the-response).                                                                         |
| `providerName`                   | —                                                                       | Human-readable name of the requester, for the presenter's user agent or the IdP.                                                                                                                                    |
| `attributeConsumingServiceIndex` | —                                                                       | Tells the IdP which attribute set to attach to the response ([background](http://blog.aniljohn.com/2014/01/data-minimization-front-channel-saml-attribute-requests.html)).                                          |
| `disableRequestAcsUrl`           | `false`                                                                 | Omit the optional `AssertionConsumerServiceURL` from the request.                                                                                                                                                   |
| `skipRequestCompression`         | `false`                                                                 | Send the request uncompressed instead of DEFLATE-compressed.                                                                                                                                                        |
| `authnRequestBinding`            | `"HTTP-Redirect"`                                                       | Recorded on the instance for consumers such as `passport-saml` to act on. Within this library the binding follows from the method you call — `getAuthorizeUrlAsync` for Redirect, `getAuthorizeFormAsync` for POST. |
| `additionalParams`               | `{}`                                                                    | Query parameters added to every outgoing request.                                                                                                                                                                   |
| `additionalAuthorizeParams`      | `{}`                                                                    | Query parameters added to authorize requests only.                                                                                                                                                                  |
| `scoping`                        | —                                                                       | `Scoping` element contents; see below.                                                                                                                                                                              |

`scoping` implements [SAML core §3.4.1.2, `<Scoping>`](https://docs.oasis-open.org/security/saml/v2.0/saml-core-2.0-os.pdf):

```javascript
scoping: {
  idpList: [ // optional
    {
      entries: [ // required
        {
          providerId: "yourProviderId", // required for each entry
          name: "yourName", // optional
          loc: "yourLoc", // optional
        },
      ],
      getComplete: "URI to your complete IDP list", // optional
    },
  ],
  proxyCount: 2, // optional
  requesterId: "requesterId", // optional; a string or an array of strings
}
```

### InResponseTo

| Option                        | Default         | Description                                                                                                                                       |
| ----------------------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `validateInResponseTo`        | `"never"`       | `"always"`, `"ifPresent"`, or `"never"`. **Set this explicitly**; the trade-offs are below. The `ValidateInResponseTo` enum is exported for this. |
| `requestIdExpirationPeriodMs` | `28800000` (8h) | How long a generated request ID stays valid for matching against an incoming `InResponseTo`.                                                      |
| `cacheProvider`               | in-memory       | Where request IDs are stored. See [Cache provider](#cache-provider).                                                                              |

> **Set `validateInResponseTo` explicitly.** It defaults to `"never"` today, and the next major
> version requires it; until then, leaving it unset logs a warning under `NODE_DEBUG=node-saml`.
> Which value fits depends on how logins reach you:
>
> - `"always"` accepts only a response that answers a request Node-SAML recorded, and removes that
>   request ID as it accepts the response, so a response cannot be delivered unsolicited or
>   presented again later. When the cache provider consumes IDs atomically with `consumeAsync`, as
>   the built-in one does, two copies arriving at the same moment cannot both be accepted either. It
>   rejects IdP-initiated logins, and on more than one server or process it needs a shared
>   [cache provider](#cache-provider).
> - `"ifPresent"` validates `InResponseTo` when a response carries one and accepts a response that
>   does not. IdP-initiated login keeps working, and an unsolicited response is accepted and can be
>   replayed until its timestamps expire, unless you set
>   [`rejectReplayedAssertions`](#replayed-assertions).
> - `"never"` skips the check, so any captured response can be replayed until its timestamps expire,
>   unless you set [`rejectReplayedAssertions`](#replayed-assertions).

See [InResponseTo validation](#inresponseto-validation) below for what this protects against and how the IDs are consumed.

### Logout

| Option                   | Default      | Description                                                                                       |
| ------------------------ | ------------ | ------------------------------------------------------------------------------------------------- |
| `logoutUrl`              | `entryPoint` | Address to send logout requests to.                                                               |
| `additionalLogoutParams` | `{}`         | Query parameters added to logout requests only.                                                   |
| `logoutCallbackUrl`      | —            | The `Location` for the `SingleLogoutService` elements in the generated service provider metadata. |

The next major version also compares the `Destination` of a signed `LogoutRequest` or
`LogoutResponse` with `logoutCallbackUrl`, in the same way as for `callbackUrl` above. Until then
such a message is accepted. With `logoutCallbackUrl` set, run with `NODE_DEBUG=node-saml` to be told
when a `Destination` differs from it or is missing.

### Metadata

| Option                               | Default | Description                                                                                                                                   |
| ------------------------------------ | ------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `signMetadata`                       | `false` | Sign the generated service provider metadata. Requires `privateKey`.                                                                          |
| `metadataContactPerson`              | —       | `ContactPerson` entries to include in the generated metadata. An array, since metadata may carry several.                                     |
| `metadataOrganization`               | —       | `Organization` details to include in the generated metadata.                                                                                  |
| `metadataAttributeConsumingServices` | —       | `AttributeConsumingService` entries to include in the generated metadata, each listing the attributes this service provider asks the IdP for. |

```javascript
metadataContactPerson: [
  {
    "@contactType": "support", // "technical" | "support" | "administrative" | "billing" | "other"
    GivenName: "test",
    EmailAddress: ["mailto:test@node-saml"], // an array of `mailto:` URIs
  },
],
metadataOrganization: {
  OrganizationName: [{ "@xml:lang": "en", "#text": "node-saml" }],
  OrganizationDisplayName: [{ "@xml:lang": "en", "#text": "node-saml" }],
  OrganizationURL: [{ "@xml:lang": "en", "#text": "https://github.com/node-saml/node-saml" }],
},
metadataAttributeConsumingServices: [
  {
    "@index": "0",
    "@isDefault": true,
    ServiceName: [{ "@xml:lang": "en", "#text": "My Service" }],
    ServiceDescription: [{ "@xml:lang": "en", "#text": "Needs the user's name and email" }],
    RequestedAttribute: [
      {
        "@Name": "urn:oid:2.5.4.42",
        "@NameFormat": "urn:oasis:names:tc:SAML:2.0:attrname-format:uri",
        "@FriendlyName": "givenName",
        "@isRequired": true,
      },
      {
        "@Name": "urn:oid:0.9.2342.19200300.100.1.3",
        "@NameFormat": "urn:oasis:names:tc:SAML:2.0:attrname-format:uri",
        "@FriendlyName": "mail",
        "@isRequired": false,
      },
    ],
  },
],
```

`Extensions`, on a contact or on the organization, takes namespace-qualified elements as an
xmlbuilder object, like the options under [Extensions](#extensions) below. A string there cannot
produce valid metadata. Both also take namespace-qualified attributes, each written with its
prefix next to the `@xmlns:` declaration of that prefix. The elements and the attributes come from
a namespace that SAML does not define: not the SAML 2.0 metadata, assertion or protocol namespace.
A REFEDS security contact is marked that way:

```javascript
metadataContactPerson: [
  {
    "@contactType": "other",
    "@xmlns:remd": "http://refeds.org/metadata",
    "@remd:contactType": "http://refeds.org/metadata/contactType/security",
    EmailAddress: ["mailto:security@example.com"],
  },
],
```

The `SamlOptions` types do not declare such attributes until the next major version. In TypeScript,
build the entry outside the config literal, or cast it.

Each `metadataAttributeConsumingServices` entry needs an `@index` from `"0"` to `"65535"` that no
other entry uses, at least one `ServiceName` and at least one `RequestedAttribute`, and at most one
entry may set `@isDefault` to `true`. An entry that breaks these rules, carries a key not shown
above, or holds a malformed value such as an `@xml:lang` that is not a language tag, is rejected
with a `TypeError` when the `SAML` is constructed or the metadata is generated.
Set `attributeConsumingServiceIndex` to have an `AuthnRequest` select one of them by its `@index`.

The full shapes are in the `SamlOptions` type definitions, which your editor will complete for you.
`metadataContactPerson` and `metadataOrganization` are not rejected yet: either one in any other
shape is still written into the metadata as given, which can leave the metadata invalid. Run with
`NODE_DEBUG=node-saml` to be told when that happens. The next major version rejects it.

### Extensions

`samlAuthnRequestExtensions` and `samlLogoutRequestExtensions` add an `Extensions` element to the
generated `AuthnRequest` and `LogoutRequest`. They are useful for things like the
[requested attributes protocol extension](https://docs.oasis-open.org/security/saml-protoc-req-attr-req/v1.0/saml-protoc-req-attr-req-v1.0.html),
and take an [xmlbuilder](https://www.npmjs.com/package/xmlbuilder) object of namespace-qualified
elements.

```javascript
samlAuthnRequestExtensions: {
  "req-attr:RequestedAttributes": {
    "@xmlns:req-attr": "urn:oasis:names:tc:SAML:protocol:ext:req-attr",
    "md:RequestedAttribute": {
      "@xmlns:md": "urn:oasis:names:tc:SAML:2.0:metadata",
      "@isRequired": "true",
      "@Name": "LastName",
    },
  },
  vetuma: {
    "@xmlns": "urn:vetuma:SAML:2.0:extensions",
    LG: { "#text": "sv" },
  },
},

samlLogoutRequestExtensions: {
  vetuma: {
    "@xmlns": "urn:vetuma:SAML:2.0:extensions",
    LG: { "#text": "sv" },
  },
},
```

Each element directly inside `Extensions` comes from a namespace that SAML does not define: not the
SAML 2.0 assertion, protocol or metadata namespace. That is why the requested attributes above sit
inside the extension's own `RequestedAttributes` element, and not directly in `Extensions`. Neither
option is rejected yet: one in any other shape is still written into the request as given. Run with
`NODE_DEBUG=node-saml` to be told when that happens. The next major version rejects it.

## Security and signatures

Node-SAML uses the HTTP-Redirect binding for its `AuthnRequest`s (unless you call
`getAuthorizeFormAsync` for HTTP-POST) and expects the messages back over the HTTP-POST binding.

Three properties hold throughout response validation, and they are worth knowing because they
explain rejections that might otherwise look overly strict:

- **Only signed bytes are trusted.** Verification returns the content the signature actually covers,
  and that is the content the library goes on to process. The original document is never re-read
  after verification, because an attacker controls the difference between the two — that is the
  whole of an XML signature wrapping attack.
- **Ambiguity is rejected, not resolved.** A response with more than one assertion, an assertion, a
  logout message or a signed `Response` with more than one `Issuer`, more than one signature on an
  element, an `ID` resolving to more than one element, a reference pointing anywhere other than its
  own parent, or more than two transforms is refused. The library does not pick a reading, and it
  does not pick the reading that happens to verify.
  One case is not refused yet: a signature with more than one reference is ignored, so its element
  counts as unsigned. That matters only for a `Response` under `wantAuthnResponseSigned: false`,
  which is then accepted on the strength of its separately signed assertion. The next major version
  rejects such a message; until then it logs a warning under `NODE_DEBUG=node-saml`. Configure the
  identity provider to sign with a single reference, to the element signed, as
  [SAML core §5.4.2](https://docs.oasis-open.org/security/saml/v2.0/saml-core-2.0-os.pdf) requires.
- **Validation fails closed.** Decrypted content is not trusted content: an `EncryptedAssertion` is
  decrypted and then still has to have its signature verified. Timestamps, audience, issuer, and
  `InResponseTo` are security controls rather than conveniences — an option that switches one off
  (`audience: false`, `acceptedClockSkewMs: -1`) is removing a control, so make that choice
  deliberately.

### Subclassing `SAML`

Overriding a `protected` method of `SAML` that validates an incoming message is deprecated, and the
next major version makes those methods private: an override can switch off a check that the
properties above depend on. That is every `protected` method except `signRequest` and
`generateAuthorizeRequestAsync`. Check what the public method returns instead, and relax a check
only through its option under [Response validation](#response-validation):

```javascript
// deprecated
class TenantSaml extends SAML {
  async processValidlySignedAssertionAsync(...args) {
    const result = await super.processValidlySignedAssertionAsync(...args);
    assertKnownTenant(result.profile);
    return result;
  }
}

// use this instead
const { profile } = await saml.validatePostResponseAsync(req.body);
if (profile) {
  assertKnownTenant(profile);
}
```

To choose the certificates a signature is verified with at run time, pass a function as
[`idpCert`](#configuration-option-idpcert) rather than overriding `getKeyInfosAsPem`. To check the
`Issuer` of a logout message, set [`idpIssuer`](#response-validation) rather than overriding
`verifyIssuer`: a `LogoutResponse` resolves with `profile: null`, so its result has no issuer to
check.

### Verifying a signature outside `SAML`

`lib/xml` exports `getVerifiedXml()`, which upholds the first property above, and the deprecated
`validateSignature()`, which doesn't. Like everything under `lib/`, neither is part of the API: the
next major version closes the path to both, and removes `validateSignature()`.

To validate a SAML message, use the `SAML` methods above, which apply every check in this section.
To verify other signed XML, use `xml-crypto` directly, and read the signed content from
`getSignedReferences()` rather than from the document you passed in, as its
[Verifying Xml documents](https://github.com/node-saml/xml-crypto#verifying-xml-documents) section
shows. `validateSignature()` reports only that a signature verified, which leaves you to find the
signed content somewhere else, and an attacker controls the difference between what verified and
what you then read. That is an XML signature wrapping attack. `xml-crypto` doesn't apply the
SAML-specific checks listed above, such as requiring a signature's reference to point at the
signature's own parent, so add any your documents need:

```javascript
// deprecated: `dom` is the document as received, not the part the signature covered
if (validateSignature(xml, dom.documentElement, pemFiles)) {
  readTheProfileFrom(dom);
}

// use this instead
const sig = new SignedXml({ publicCert });
sig.loadSignature(signatureElement);
if (!sig.checkSignature(xml)) {
  throw new Error("Invalid signature");
}

readTheProfileFrom(new DOMParser().parseFromString(sig.getSignedReferences()[0], "text/xml"));
```

### Configuration option `signatureAlgorithm`

Requests sent by Node-SAML can be signed using RSA with SHA-1, SHA-256, or SHA-512.

```javascript
signatureAlgorithm: "sha256"; // preferred — your IdP should support it; if not, consider upgrading the IdP
signatureAlgorithm: "sha512"; // strongest — check that your IdP supports it
signatureAlgorithm: "sha256-mgf1"; // SHA-256 with RSASSA-PSS padding — only if your IdP asks for it
signatureAlgorithm: "sha1"; // legacy; SHA-1 is no longer considered collision-resistant
```

`"sha1"`, `"sha256"` and `"sha512"` sign with PKCS #1 v1.5 padding, which is what most IdPs expect.
`"sha256-mgf1"` signs with RSASSA-PSS instead and names itself
`http://www.w3.org/2007/05/xmldsig-more#sha256-rsa-MGF1`
([RFC 9231 §2.3.10](https://www.rfc-editor.org/rfc/rfc9231#section-2.3.10)), with a salt the
length of the digest. Choose it when your IdP requires PSS signatures; an IdP that does not know the
identifier will reject the request. It applies to everything Node-SAML signs: Redirect-binding
requests and logout responses, POST-binding `AuthnRequest`s, and metadata.

What your IdP signs is a separate matter and needs no option: a message it signs with
`sha256-rsa-MGF1` is verified on both bindings.

On the Redirect binding, the next major version verifies a signature only when `SigAlg` is exactly
one of these identifiers:

- `http://www.w3.org/2000/09/xmldsig#rsa-sha1`
- `http://www.w3.org/2001/04/xmldsig-more#rsa-sha256`
- `http://www.w3.org/2001/04/xmldsig-more#rsa-sha384`
- `http://www.w3.org/2001/04/xmldsig-more#rsa-sha512`
- `http://www.w3.org/2007/05/xmldsig-more#sha256-rsa-MGF1`

Other values that verify today, such as `http://www.w3.org/2001/04/xmldsig-more#rsa-sha224` or a
bare `RSA-SHA256`, are rejected then. Run with `NODE_DEBUG=node-saml` to be told when your IdP sends
one.

`digestAlgorithm` takes `"sha1"`, `"sha256"`, or `"sha512"` and controls the digest over the signed
data object. It does not take `"sha256-mgf1"`, which names a signature padding rather than a digest;
pair that with `digestAlgorithm: "sha256"`.

> **Set both explicitly if you sign, and check the spelling.** With `privateKey` set, leaving
> `signatureAlgorithm` or `digestAlgorithm` unset selects `sha1`, which is no longer considered safe
> for signatures; the next major version requires both whenever `privateKey` is set. A value that is
> not one of those listed above — including a casing difference such as `"SHA256"` — is not an error
> today either: it falls through to SHA-1, so a typo silently downgrades the signature you asked
> for. The next major version rejects it instead. `digestAlgorithm` is typed as a plain string, so
> TypeScript does not catch a typo in it. Run with `NODE_DEBUG=node-saml` to be told when any of
> this happens, whether the options go to `SAML` or straight to `generateServiceProviderMetadata`.
>
> The exception is `signatureAlgorithm: "sha256-mgf1"`: with it, a `digestAlgorithm` that is unset
> or not one of those listed is already an error.

### Configuration option `privateKey`

To sign authentication requests, provide the private key in PEM format via `privateKey`. Node-SAML
reads it with xml-crypto's `toPem()`, and uses what that returns: canonical
[RFC 7468](https://www.rfc-editor.org/rfc/rfc7468) PEM, with `\n` line endings, lines of 64
characters, and one message after another.

What it accepts is more liberal than RFC 7468's `stricttextualmsg`:

- whitespace surrounding the value, and a leading UTF-8 byte order mark, whether the value arrives
  as a string or a `Buffer`;
- any of the three line-ending conventions;
- encoded data wrapped at any width, or not wrapped at all, with spaces or tabs anywhere in it;
- a blank line after the `-----BEGIN ...-----` boundary;
- several PEM messages concatenated in one value, optionally separated by blank lines. Signing and
  verification each take only one key from such a value, so it suits a private key stored alongside
  its certificate, but not a set of keys: to trust several IdP certificates, give `idpCert` an array.

It rejects, with an error naming the option and giving the reason:

- encoded data that is not valid Base64 as [RFC 4648](https://www.rfc-editor.org/rfc/rfc4648)
  section 4 defines it — `=` padding away from the end, or a last group that is incomplete — rather
  than decoding as much of it as it can;
- a message whose `-----BEGIN` and `-----END` labels disagree;
- a `CERTIFICATE` whose data is not exactly one X.509 certificate;
- a `PRIVATE KEY` or `RSA PRIVATE KEY` whose data Node cannot read as a private key under that
  label, such as PKCS #1 data labelled `PRIVATE KEY`;
- text before, after or between the messages, and a boundary sharing its line with other text.

xml-crypto documents the complete rules under
[What the parser accepts](https://github.com/node-saml/xml-crypto#what-the-parser-accepts). A
`Buffer` is read as the text of a PEM or Base64 file, just as a string is; DER is not accepted, so
convert it to PEM first as shown under [`idpCert`](#configuration-option-idpcert).

```javascript
privateKey: fs.readFileSync("./privateKey.pem", "latin1");
```

Accepted formats:

1. RFC 7468 PEM, with either label:

   ```text
   -----BEGIN PRIVATE KEY-----
   <private key contents here delimited at 64 characters per row>
   -----END PRIVATE KEY-----
   ```

   ```text
   -----BEGIN RSA PRIVATE KEY-----
   <private key contents here delimited at 64 characters per row>
   -----END RSA PRIVATE KEY-----
   ```

2. A single-line or multi-line private key in Base64, without the delimiter lines. See the
   [single-line private key](test/static/single_line_acme_tools_com.key) used in the tests. Base64
   carries no label, so it is read as a PKCS #8 key (`PRIVATE KEY`) or, failing that, as a PKCS #1
   RSA key (`RSA PRIVATE KEY`). Base64 that is neither, such as a certificate or a public key, is
   refused with an error naming `privateKey`.

### Configuration option `decryptionPvk`

To decrypt encrypted assertions and encrypted name identifiers, provide the SP's private key via
`decryptionPvk`. Its certificate is `decryptionCert`, which the IdP encrypts to; see
[Service provider metadata](#service-provider-metadata).

```javascript
decryptionPvk: "MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQCXJP47MTKaFpkU ... ==";
```

Accepted formats:

1. PEM, handed to Node's crypto as given. That is how `decryptionPvk` has always been read, so
   Node's rules apply rather than the ones listed under [`privateKey`](#configuration-option-privatekey).
   In particular, text before or after the message, such as the `Bag Attributes` lines that
   `openssl pkcs12` writes, is passed over rather than refused.
2. A single-line or multi-line private key in Base64, without the delimiter lines, read exactly as
   for `privateKey`: PKCS #8 or PKCS #1, whichever the data holds. Base64 that is neither is
   refused with an error naming `decryptionPvk`, before any decryption is attempted.

#### Preparing for the next major version

Version 5.2 continues to decrypt the legacy forms below, but the next major version will not.
Set `NODE_DEBUG=node-saml` to see warnings **after successful decryption** of an
`EncryptedAssertion` or `EncryptedID` that uses one of them. These warnings do not change
whether a message is accepted.

- **Content encryption:** `aes128-cbc`, `aes256-cbc`, and `tripledes-cbc` will be refused.
  Configure the identity provider to use `aes128-gcm` or `aes256-gcm` instead.
- **Key transport:** `rsa-1_5` will be refused. It already fails to decrypt on Node 18
  and Node 20; other runtimes may still accept it in 5.x. Configure the identity provider to
  wrap encryption keys using `rsa-oaep-mgf1p` with its default SHA-1 digest instead.
- **OAEP digest:** An `rsa-oaep-mgf1p` key with a `DigestMethod` of
  `http://www.w3.org/2001/04/xmlenc#sha256`, `http://www.w3.org/2001/04/xmlenc#sha512`,
  `http://www.w3.org/2000/09/xmldsig#sha256` or `http://www.w3.org/2000/09/xmldsig#sha512`
  will no longer decrypt. The next major version uses that digest for OAEP and SHA-1 for MGF1,
  as [XML Encryption 1.1 §5.5.2](https://www.w3.org/TR/xmlenc-core1/#sec-RSA-OAEP) requires,
  and a key that 5.2 decrypts with one of these was wrapped another way. Configure the identity
  provider to use **SHA-1** (the default) with `rsa-oaep-mgf1p` for now. Both versions decrypt
  that form. After the upgrade, the identity provider can switch to SHA-256 with
  `http://www.w3.org/2001/04/xmlenc#sha256`, provided it uses SHA-1 for MGF1.

If your identity provider cannot use AES-GCM or `rsa-oaep-mgf1p`, and your deployment does not
require assertion confidentiality, disable assertion encryption at the identity provider. An
unencrypted assertion is accepted even when `decryptionPvk` is configured, and node-saml still
verifies the required signatures. Signatures protect integrity, not confidentiality: the browser
and any other system that handles the response can read an unencrypted assertion's NameID and
attributes. The same holds for an encrypted logout NameID: disable NameID encryption at the
identity provider only if the NameID need not be kept confidential. Logout signature validation
still applies.

### Configuration option `idpCert`

Validating the signatures on incoming responses is the point of this library, and `idpCert` is what
it validates them against. Provide the IdP's public X.509 signing certificate(s) or public key(s). The
same normalization, tolerances and rejections described under
[`privateKey`](#configuration-option-privatekey) apply here.

```javascript
idpCert: "MIICizCCAfQCCQCY8tKaMc0BMjANBgkqh ... W==";
```

If the IdP has several valid signing certificates or public keys — during a rollover, for instance,
when responses signed with either key are valid — pass an array:

```javascript
idpCert: ["MIICizCCAfQCCQCY8tKaMc0BMjANBgkqh ... W==", "MIIEOTCCAyGgAwIBAgIJAKZgJdKdCdL6M ... g="];
```

`idpCert` can also be a function taking a node-style callback, which lets you poll the IdP for its
current keys so a rotation is picked up without a restart. The result is not cached, so the function
is called on every validation:

```javascript
idpCert: (callback) => {
  callback(null, polledCertificates);
};
```

Accepted formats:

1. RFC 7468 PEM, as a certificate or a bare public key:

   ```text
   -----BEGIN CERTIFICATE-----
   <certificate contents here delimited at 64 characters per row>
   -----END CERTIFICATE-----
   ```

   ```text
   -----BEGIN PUBLIC KEY-----
   <public key contents here delimited at 64 characters per row>
   -----END PUBLIC KEY-----
   ```

2. A single-line or multi-line **certificate** in Base64, without the delimiter lines.

#### If the certificate is in the binary DER encoding

Convert it to PEM:

```shell
openssl x509 -inform der -in my_certificate.cer -out my_certificate.pem
```

### Configuration option `publicCert`

Some identity providers require the SP's public signing certificate to be embedded in the
`AuthnRequest`, so they can verify the request, match the subject DN, and confirm the certificate was
signed. Pass it as `publicCert`; it must match `privateKey`, and it must hold at least one certificate:
a public key alone is refused, because it would leave `KeyInfo` out of the signature. The same two
formats are accepted:

```text
-----BEGIN CERTIFICATE-----
<X.509 certificate contents here delimited at 64 characters per row>
-----END CERTIFICATE-----
```

or

```javascript
publicCert: "MIICizCCAfQCCQCY8tKaMc0BMjANBgkqh ... W==";
```

## Response validation timestamps

When a response carries `NotBefore` or `NotOnOrAfter`, Node-SAML validates them against the current
time plus or minus `acceptedClockSkewMs`, which accounts for drift between your server's clock and
the IdP's. The default skew is `0`.

Both attributes are honored on the `SubjectConfirmation` element and within
`Assertion/Conditions`. `maxAssertionAgeMs` adds an independent limit measured from the assertion's
`IssueInstant`, and applies when it is stricter than `NotOnOrAfter`. An assertion whose
`SubjectConfirmation` elements are all outside their window is rejected whatever
`validateInResponseTo` is set to.

## InResponseTo validation

`InResponseTo` ties a response back to a request you actually made, which is what stops a response
captured elsewhere from being replayed at your callback. Turn it on with
`validateInResponseTo: "always"`.

Node-SAML then records the ID of every request it generates, and a response validates only if its
`InResponseTo` matches one of them. It is checked as an attribute of the top-level `Response` or
`LogoutResponse` element, and within `SubjectConfirmation`.

Only a signature makes the top-level attribute trustworthy, so when the IdP signs the assertion but
not the `Response`, `"always"` requires one of the assertion's `SubjectConfirmationData` elements,
within its validity window, to carry `InResponseTo`, and rejects the response otherwise. A
conforming IdP already puts it there
([SAML profiles §4.1.4.2](https://docs.oasis-open.org/security/saml/v2.0/saml-profiles-2.0-os.pdf)).
If yours does not, have it sign the `Response`.

Recorded IDs expire after `requestIdExpirationPeriodMs` (8 hours by default). A response arriving
with an expired — or unrecognized — `InResponseTo` is rejected. Accepting a response removes its
request ID, so presenting the same response again later fails. Two copies arriving at the same
moment can both be accepted unless the cache provider removes the ID atomically, which the built-in
one does and a custom one does if it implements `consumeAsync`, described below.

While `InResponseTo` is validated — always under `"always"`, and under `"ifPresent"` when the
`Response` or `LogoutResponse` element carries one — a request ID is removed when a verified
signature covers an `InResponseTo` naming it, on that element or on a `SubjectConfirmationData` in
the assertion, whether the response is then accepted or rejected. The exception is a copy rejected
as a [replayed assertion](#replayed-assertions), which leaves the ID to the first copy, since that
copy may still be validating. Nothing else removes one. Anyone
who learns a pending request ID can put it in a response, so an unsigned `InResponseTo` is still
checked against the recorded IDs but cannot by itself retire one, and the IdP's genuine response
validates after it. That covers a rejected response in which nothing signed names the request, an
unsigned `Response` accepted under `"ifPresent"` on the strength of its assertion alone, and an
unsigned Redirect-binding `LogoutResponse`. None of these can be presented again with more effect
than before: an unsigned `InResponseTo` can be deleted, making the response unsolicited, and an
unsigned logout message can be forged outright.

A signature shows that the IdP answered a request, not that whoever presents the response started
it. Someone with an account at your IdP who gets it to answer a request carrying another user's
pending ID receives a genuinely signed response, and presenting it retires that user's request. When
`AuthnRequest`s are unsigned, knowing the ID is enough to build such a request. Signing them (set
`privateKey`, and have the IdP require signed requests) leaves only a replay of that user's own
`AuthnRequest`, which some IdPs reject.

## Replayed assertions

`InResponseTo` validation cannot stop an unsolicited response from being presented twice: it carries
no `InResponseTo`, and an unsigned one can be deleted. Set `rejectReplayedAssertions: true` to have
Node-SAML remember the ID of each assertion it receives, in the [cache provider](#cache-provider),
and reject one whose ID it has seen
([SAML profiles §4.1.4.5](https://docs.oasis-open.org/security/saml/v2.0/saml-profiles-2.0-os.pdf)).
The second copy fails with `The assertion <ID> has already been received`. It gives IdP-initiated
login, under `"ifPresent"` or `"never"`, the replay protection that `InResponseTo` gives a login
your application started.

- **What is remembered** is the verified assertion's ID together with its `Issuer`, so identity
  providers sharing a cache do not collide. It is remembered as soon as the assertion's signature
  verifies, before the other checks, so an assertion rejected as not yet valid cannot be presented
  again once it is.
- **For how long:** until the last moment the assertion could still be accepted. That is the
  earlier of its `Conditions` `NotOnOrAfter` and the latest `NotOnOrAfter` among its
  `SubjectConfirmationData`, capped by `maxAssertionAgeMs`, plus `acceptedClockSkewMs`. An
  assertion with no `NotOnOrAfter` at all could be accepted for ever, so it is rejected; a
  conforming IdP puts one on every bearer `SubjectConfirmationData`
  ([SAML profiles §4.1.4.2](https://docs.oasis-open.org/security/saml/v2.0/saml-profiles-2.0-os.pdf)).
  For the same reason the option cannot be combined with `acceptedClockSkewMs: -1`.
- **Across servers or processes** this needs a shared cache provider, and within one process the
  same `InMemoryCacheProvider` for every `SAML` instance, as described below. Either way, the
  provider has to implement `saveIfAbsentAsync`.

It is off by default in this version, because it rejects responses that were accepted before and
writes to the cache provider on every login. Leaving it unset logs a warning under
`NODE_DEBUG=node-saml`. The next major version rejects replayed assertions.

## Cache provider

With `InResponseTo` validation on, the generated request IDs have to be stored somewhere, and with
`rejectReplayedAssertions` on, so do the IDs of the assertions received. That is the
`cacheProvider`'s job.

The default is an `InMemoryCacheProvider`, which keeps request IDs in one process's memory. It is
not sufficient across multiple servers or processes: the instance that generated the request ID may
not be the one that handles the response, and validation then fails for legitimate logins. For
those deployments, back the cache with something shared — Redis, a database, your session store —
by implementing:

```typescript
interface CacheProvider {
  /** Store an item in the cache, using the specified key and value. */
  saveAsync(key: string, value: string): Promise<CacheItem | null>;
  /** Returns the value of the specified key in the cache. */
  getAsync(key: string): Promise<string | null>;
  /** Removes an item from the cache if the key exists. */
  removeAsync(key: string | null): Promise<string | null>;
  /** Optional. Removes the key and returns its value, or null if it was absent, atomically. */
  consumeAsync?(key: string): Promise<string | null>;
  /** Needed by rejectReplayedAssertions. Saves the key until expiresAtMs, if absent, atomically. */
  saveIfAbsentAsync?(key: string, value: string, expiresAtMs: number): Promise<boolean>;
}
```

Implement `consumeAsync` with your store's single-step remove-and-return, such as Redis `GETDEL` or
SQL `DELETE … RETURNING`. Node-SAML consumes request IDs with it, so of two copies of one response
validated at the same moment, only one is accepted. Without it, Node-SAML reads the ID and removes
it in separate calls, both copies can be accepted, and a warning is logged under
`NODE_DEBUG=node-saml` whenever `InResponseTo` is validated. The next major version requires it. The
built-in provider implements it.

Implement `saveIfAbsentAsync` with your store's single-step insert-if-absent with an expiry, such as
Redis `SET key value NX PXAT expiresAtMs` or SQL `INSERT … ON CONFLICT DO NOTHING`. It resolves
`true` if it saved the key and `false` if the key was already there. Node-SAML records assertion IDs
with it when `rejectReplayedAssertions` is set, so of two copies of one assertion validated at the
same moment, only one is accepted. That option requires it: the constructor throws a `TypeError`
when the option is on and the provider has no `saveIfAbsentAsync`. The built-in provider implements
it.

Give each identity provider its own cache. In a shared store, that means a provider for each
identity provider that prefixes every key with its name. Request IDs are looked up by ID alone, so
when several identity providers share one cache, a response signed by one of them can answer, and
retire, a request sent to another.

Within one process `InMemoryCacheProvider` is enough, but each `SAML` instance given no
`cacheProvider` creates its own, which lasts only as long as that instance. Code that constructs a
`SAML` for each request, as passport-saml's `MultiSamlStrategy` does, would record a login's request
ID in one cache and look for it in another, rejecting the response with `InResponseTo is not valid`.
Create one `InMemoryCacheProvider` for each identity provider, once, and pass it every time:

```javascript
const { InMemoryCacheProvider, SAML } = require("@node-saml/node-saml");

// Once, at startup, for each identity provider:
const cacheProvider = new InMemoryCacheProvider();

// On each request to that identity provider:
const saml = new SAML({ ...idpOptions, cacheProvider });
```

It keeps a request ID for `keyExpirationPeriodMs`, 8 hours by default. If you change
`requestIdExpirationPeriodMs`, pass the same value as
`new InMemoryCacheProvider({ keyExpirationPeriodMs })`. The `SAML` constructor does that for the
provider it creates, but a cache you supply expires IDs on its own schedule.

`CacheProvider`, `CacheItem`, `InMemoryCacheProvider`, and its constructor's `CacheProviderOptions` are
all exported from the package root.

## Troubleshooting

Node-SAML writes debug output through Node's
[`util.debuglog`](https://nodejs.org/api/util.html#utildebuglogsection-callback), and is silent
until you turn it on. Set `NODE_DEBUG=node-saml` in the environment the process starts with:

```shell
NODE_DEBUG=node-saml node server.js
```

Node reads `NODE_DEBUG` once, at startup, so assigning `process.env.NODE_DEBUG` inside your
application has no effect. If you already set other sections, add `node-saml` to the
comma-separated list. Each line goes to stderr, prefixed with `NODE-SAML` and the process ID.

The output covers two things:

- **Why a response was rejected.** When `validatePostResponseAsync` rejects, it logs the error too.
  That helps when the code between Node-SAML and you, such as a Passport `failureRedirect`, reports
  only that the login failed.
- **What the next major version changes.** Configuration or input that works today, but that the
  next major version rejects or handles differently, logs a warning when it is used. Examples are a
  security-relevant option left at its default, a deprecated argument or accessor, an unsigned logout
  message on the Redirect binding, and an attribute with no usable value. Each warning says what to
  change, and the sections above describe each one next to the option it concerns.

Version 5.1.0 and earlier used the `debug` package, turned on with `DEBUG=node-saml`. That variable
no longer does anything; use `NODE_DEBUG=node-saml` instead.

## Node support policy

We only support [Long-Term Support](https://github.com/nodejs/Release) versions of Node.

We specifically limit our support to LTS versions of Node, not because this package won't work on other versions, but because we have a limited amount of time, and supporting LTS offers the greatest return on that investment.

It's possible this package will work correctly on newer versions of Node. It may even be possible to use this package on older versions of Node, though that's more unlikely as we'll make every effort to take advantage of features available in the oldest LTS version we support.

The `engines` field in [`package.json`](package.json) is the authoritative statement of what we support. As each Node LTS version reaches its end-of-life we will remove that version from it. Removing a Node version is considered a breaking change and will entail the publishing of a new major version of this package. We will not accept any requests to support an end-of-life version of Node. Any merge requests or issues supporting an end-of-life version of Node will be closed.

We will accept code that allows this package to run on newer, non-LTS, versions of Node.

## Contributing

Issues and pull requests are welcome. A change that touches how a document is accepted, rejected, or
trusted needs a test that fails without it; [`AGENTS.md`](AGENTS.md) documents the standards this
repository holds itself to, and the [pull request template](.github/pull_request_template.md) lists
what a review looks for. For questions rather than bugs, start in
[Discussions](https://github.com/node-saml/node-saml/discussions).

When a change follows the SAML specification, link the relevant part. Start from the
[OASIS SAML 2.0 standards](https://www.oasis-open.org/standards#samlv2.0).

## Changelog

See [CHANGELOG.md](https://github.com/node-saml/node-saml/blob/master/CHANGELOG.md).
