@zaptic-external/saml
v3.0.0
Published
Minimal saml service provider with support for sp-initiated redirect login only
Downloads
130
Readme
Simple, secure SAML service provider
This library provides with a simple and secure SAML service provider.
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.loginRedirectUrl
The url that we should send auth requests using the HTTP-Redirect binding to
idp.loginPostUrl
The url that we should send auth requests using the HTTP-POST binding 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',
loginRedirectUrl: 'http://localhost:7000/idp/requestLogin',
loginPostUrl: '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'
}