@zaptic-external/saml

Simple, secure SAML service provider

This library provides with a simple and secure SAML service provider.
At the moment it supports only service provider initiated login (using redirect binding) but more will come.

Options

The options object has 4 top level components: sp, idp, preferences and getUUID

The sp property

It should contain all configuration tied to the service provider. These options will be used to generate the service provider metadata file and populate the login requests.

sp.id
A globally unique identifier that identifies your service provider. This corresponds to the entityId saml field. It is often a URL as they make it easy to namespace things so long as you own the domain. If your id might contain numbers the saml spec says that the id should start with an "_".

sp.assertionUrl
URL that will receive a POST request containing an assertion - usually login response - from the identity provider.

sp.singleLogoutUrl
URL that will receive single log out requests from the identity provider. At this time this library does not provide with a way to parse logout requests but it's an open issue.

sp.signature
The signature object see relevant section.

sp.encryption - optional
This is also a signature object but the certificates provided in this one are for encrypting the login responses.
When nothing is provided it defaults to the signing certificates under the sp.signature object.

The idp property

It should be either an object or string. If it's a string, it should be a string containing the identity provider's metadata xml. It is recommended that you use the metadata file as it's easier to maintain than the manually assigned properties.

idp.id
A globally unique identifier that identifies the identity provider. This corresponds to the entityId saml field. Same restrictions as for the sp id apply.

idp.loginUrl
The url that we should send auth requests to

idp.signature
This is the object that contains the certificates and signature algorithm that we should accept for signing the identity provider's assertions

idp.signature.algorithm
Currently, supported are sha256 and sha512 this is the algorithm with which the identity provider will sign the assertions

idp.signature.allowedCertificates
These are the public certificates that correspond to the private key the identity provider is using to sign the assertions. It must have at least one entry as we don't support unsigned requests at the moment.

The signature object

It should contain everything needed to sign our request to the identity provider. Because we are trying to be secure by default, this is not optional.

signature.algorithm
The signing algorithm to use. Only sha256 and sha512 are supported at the moment.

signature.certificate
The pem encoded public key used to sign your requests.

signature.key
The pem encoded public key used to sign your requests.

The preferences object

preferences.signLoginRequests default true
Set to true to sign login requests (aka authnRequests). When set to false the login requests will not be signed

preferences.signLoginRequests default false
When set to true, it ensures that the identity provider sends notBefore and notOnOrAfter and that the assertion is received in the interval.
When set to false it will not error if the identity provider does not send them but will still check that the assertion is in the interval if the dates are provided.

preferences.nameIdFormat default 'urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress'
The name id policy you want to use. For now only this one is supported so I would recommend not changing this

preferences.addNameIdPolicy default false
Set to true to not send the nameIdFormat along with login requests. This voids the previous parameter when set to true.

preferences.forceAuthenticationByDefault default false
Request the identity provider to prompt the user with a challenge (e.g user name + password) even if they have a valid session when set to true.

preferences.attributeMapping default '{}'
Mapping for the attributes given by the identity provider in the Attribute field. I would not worry about that too much unless you need extra claims from the identity provider. Example:

{
    'http://schemas.microsoft.com/identity/claims/objectidentifier': 'id',
    'http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name': 'email'
}

Full example:

const options = {
    sp: {
        id: 'http://service-provider.zaptic',
        assertionUrl: 'http://localhost:7000/sp/login',
        singleLogoutUrl: 'http://localhost:7000/sp/logout',
        signature: [
            {
                algorithm: <'sha256'>'sha256',
                certificate: testCert,
                key: testKey
            }
        ]
    },
    idp: {
        id: 'test-idp',
        loginUrl: 'http://localhost:7000/idp/requestLogin',
        signature: {
            algorithm: <'sha256'>'sha256',
            allowedCertificates: []
        }
    },
    preferences: {
        forceAuthenticationByDefault: true,
        signLoginRequests: false,
        strictTimeCheck: true,
        addNameIdPolicy: true,
        attributeMapping: {
            'http://schemas.microsoft.com/identity/claims/objectidentifier': 'id',
            'http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name': 'email'
        }
    },
    getUUID: () => 'test-uuid'
}