SAML service configuration¶

Note

SAML service configuration is a common step to configure LL::NG as SAML SP or SAML IDP.

Presentation¶

This documentation explains how configure SAML service in LL::NG, in particular:

Install prerequisites
Import or generate security keys
Set SAML end points

Attention

Service configuration will be used to generate LL::NG SAML metadata, that will be shared with other providers. It means that if you modify some settings here, you will have to share again the metadata with other providers. In other words, take the time to configure this part before sharing metadata.

Prerequisites¶

Lasso¶

SAML2 implementation is based on Lasso. You will need a very recent version of Lasso (>= 2.6.0).

Debian/Ubuntu¶

You can use official Debian packages or those available here: http://deb.entrouvert.org/.

Tip

We recommend Lasso 2.6 for the SHA256 support, so use the stretch-testing repository of deb.entrouvert.org.

You will only need to install liblasso-perl package:

sudo apt-get install liblasso-perl

RHEL/CentOS/Fedora¶

RPMs are available in LL::NG RPM “extras” repository (see YUM repository)

Then install lasso and lasso-perl packages:

yum install lasso lasso-perl

Attention

RHEL9 and derivatives (CentOS 9, AlmaLinux 9, Rocky Linux 9) do not provide SHA-1 support for XML document signature. You will not be able to use SHA-1 signature on these distributions.

Other¶

Download the Lasso tarball and compile it on your system.

Service configuration¶

Go in Manager and click on SAML 2 Service node.

Tip

You can use #PORTAL# in values to replace the portal URL.

Entry Identifier¶

Your EntityID, often use as metadata URL, by default #PORTAL#/saml/metadata.

Note

The value will be used in metadata main markup:

<EntityDescriptor entityID="http://auth.example.com/saml/metadata">
  ...
</EntityDescriptor>

Security parameters¶

You can define keys for SAML message signature and encryption. If no encryption keys are defined, signature keys are used for signature and encryption.

To define keys, you can:

import your own private and public keys (Replace by file input)
generate new public and private keys (New certificate button)

Changed in version 2.0.10: A X.509 certificate is now generated instead of a plain public key. It has 20 years of validity, and is self signed with the 2048 bit RSA key.

Tip

You can enter a password to protect private key with a password. It will be prompted if you generate keys, else you can set it in the Private key password.

Tip

You can change default key size by inserting defaultNewKeySize = 3072 into lemonldap-ng.ini file.

Use certificate in response: Certificate will be sent inside SAML responses.
Signature method: set the signature algorithm

Changed in version 2.0.10: The signature method can now be overridden for a SP or IDP. This will only work if you are using a certificate for signature instead of a public key.

Attention

If you are running a version under 2.0.10, the choice of a signature algorithm will affect all SP and IDP.

Converting a RSA public key to a certificate¶

If your application complains about the lack of certificate in SAML Metadata, and you generated a public RSA key instead of a certificate in a previous version of LemonLDAP::NG, you can convert the public key into a certificate without changing the private key.

Save the private key in a file, and use the openssl commands to issue a self-signed certificate:

$ openssl req -new -key private.key -out cert.pem -x509 -days 3650

NameID formats¶

SAML can use different NameID formats. The NameID is the main user identifier, carried in SAML messages. You can configure here which field of LL::NG session will be associated to a NameID format.

Note

This parameter is used by SAML IDP to fill the NameID in authentication responses.

Customizable NameID formats are:

Email
X509
Windows
Kerberos

Tip

For example, if you are using AD as authentication backend, you can use sAMAccountName for the Windows NameID format.

Other NameID formats are automatically managed:

Transient: NameID is generated
Persistent: NameID is restored from previous sessions
Undefined: Default NameID format is used

Authentication contexts¶

Each LL::NG authentication module has an authentication level, which can be associated to an SAML authentication context.

Note

This parameter is used by SAML IDP to fill the authentication context in authentication responses. It will use the authentication level registered in user session to match the SAML authentication context. It is also used by SAML SP to fill the authentication level in user session, based on authentication response authentication context.

Customizable NameID formats are:

Password
Password protected transport
TLS client
Kerberos

Organization¶

Note

This concerns all parameters for the Organization metadata section:

<Organization>
  <OrganizationName xml:lang="en">Example</OrganizationName>
  <OrganizationDisplayName xml:lang="en">Example</OrganizationDisplayName>
  <OrganizationURL xml:lang="en">http://www.example.com</OrganizationURL>
</Organization>

Display Name: should be displayed on IDP, this is often your society name
Name: internal name
URL: URL of your society

Service Provider¶

Note

This concerns all parameters for the Service Provider metadata section:

<SPSSODescriptor>
  ...
</SPSSODescriptor>

General options¶

Signed Authentication Request: set to On to always sign authentication request.
Want Assertions Signed: set to On to require that received assertions are signed.

Tip

These options can then be overridden for each Identity Provider.

Single Logout¶

For each binding you can set:

Location: Access Point for SLO request.
Response Location: Access Point for SLO response.

Available bindings are:

HTTP Redirect
HTTP POST
HTTP SOAP

Assertion Consumer¶

For each binding you can set:

Default: will this binding be used by default for authentication response.
Location: Access Point for SSO request and response.

Available bindings are:

HTTP Artifact
HTTP POST

Artifact Resolution¶

The only authorized binding is SOAP. This should be set as Default.

Identity Provider¶

Note

This concerns all parameters for the Service Provider metadata section:

<IDPSSODescriptor>
  ...
</IDPSSODescriptor>

General parameters¶

Want Authentication Request Signed: By default, LemonLDAP::NG requires all SAML Requests to be signed. Set it to “Off” to let each Service Provider metadata decide if their requests should be verified by LemonLDAP::NG or not.

Tip

The per-SP “Check SSO message signature” setting allows you to disable signature verification even if this option is set to “On” globally

This option will set the WantAuthnRequestsSigned attribute to true in LemonLDAP::NG’s IDP Metadata.

Warning

This setting requires Lasso 2.6.1 to be effective. Older versions behave as if this setting was set to “Off”

Single Sign On¶

For each binding you can set:

Location: Access Point for SSO request.
Response Location: Access Point for SSO response.

Available bindings are:

HTTP Redirect
HTTP POST
HTTP Artifact

Single Logout¶

For each binding you can set:

Location: Access Point for SLO request.
Response Location: Access Point for SLO response.

Available bindings are:

HTTP Redirect
HTTP POST
HTTP SOAP

Artifact Resolution¶

The only authorized binding is SOAP. This should be set as Default.

Attribute Authority¶

Note

This concerns all parameters for the Attribute Authority metadata section

<AttributeAuthorityDescriptor>
  ...
</AttributeAuthorityDescriptor>

Attribute Service¶

This is the only service to configure, and it accept only the SOAP binding.

Response Location should be empty, as SOAP responses are directly returned (synchronous binding).

Advanced¶

These parameters are not mandatory to run SAML service, but can help to customize it:

IDP resolution cookie name: by default, it’s the LL::NG cookie name suffixed by idp, for example: lemonldapidp.
UTF8 metadata conversion: set to On to force partner’s metadata conversion.
RelayState session timeout: timeout for RelayState sessions. By default, the RelayState session is deleted when it is read. This timeout allows one to purge sessions of lost RelayState.
Use specific query_string method: the CGI query_string method may break invalid URL encoded signatures (issued for example by ADFS). This option allows one to use a specific method to extract query string, that should be compliant with non standard URL encoded parameters.
Override Entity ID when acting as IDP: By default, SAML entityID is the same for SP and IDP roles. Some federations (like Renater) can require a different entityID for IDP. In this case, you can fill here the IDP entityID, for example: https://auth.example.com/saml/metadata/idp.
Federation: see Connect to SAML Federations

SAML sessions module name and options¶

By default, the main session module is used to store SAML temporary data (like relay-states), but SAML sessions need to use a session module compatible with the sessions restrictions feature.

Tip

You can also choose a different session module to split SSO sessions and SAML sessions.

Discovery Protocol¶

Note

Discovery Protocol is also know as WAYF Service. More information can be found in the specification: sstc-saml-idp-discovery-cs-01.pdf.

When Discovery Protocol is enabled, the LL::NG IDP list is no more used. Instead user is redirected on the discovery service and is redirected back to LL::NG with the chosen IDP.

Attention

If the chosen IDP is not registered in LL::NG, user will be redirected to discovery service again.

Configuration parameters are:

Activation: Set to On to enable Discovery Protocol support.
EndPoint URL: Discovery service page
Policy: Set a value here if you don’t want to use the default policy (urn:oasis:names:tc:SAML:profiles:SSO:idp-discovery-protocol:single)
Is passive: Enable this option to avoid user interaction on discovery service page

SAML service configuration¶

Presentation¶

Prerequisites¶

Lasso¶

Debian/Ubuntu¶

RHEL/CentOS/Fedora¶

Other¶

Service configuration¶

Entry Identifier¶

Security parameters¶

Converting a RSA public key to a certificate¶

NameID formats¶

Authentication contexts¶

Organization¶

Service Provider¶

General options¶

Single Logout¶

Assertion Consumer¶

Artifact Resolution¶

Identity Provider¶

General parameters¶

Single Sign On¶

Single Logout¶

Artifact Resolution¶

Attribute Authority¶

Attribute Service¶

Advanced¶

SAML sessions module name and options¶

Common Domain Cookie¶

Discovery Protocol¶