# Connect to SAML Federations

Warning

This feature only works with version 2.6.0 of Lasso and above

## Presentation

SAML federations are a list of Identity Providers or Service Providers which publish their metadata in a central point. Members of the federation can then easily download and use the full metadata file to connect to any party of the federation.

Well known federations are Renater and EduGain.

Note that in previous LemonLDAP::NG versions, the way to handle federations was to import the entire federation into the LemonLDAP::NG configuration. This caused several issues:

- The configuration JSON objects grows very large, sometimes beyond storage limitations

- The memory consumption is very high

- The manager interface becomes crowded with service definitions that are very rarely use

Now LL::NG works with a separated federation metadata file, and provide the possibility to override some settings in its configuration.

## Configuration

### Declare your SAML federation files

You need to use the provided `downloadSamlMetadata` script to periodically download the federation metadata on each portal server. This script checks if the received metadata is valid, and ensures the metadata file does not contain partial content during download.

    downloadSamlMetadata -m http://path/to/main-sps-renater-metadata.xml \
      -o /etc/lemonldap-ng/metadata/main-sps-renater-metadata.xml

Then, declare your federation metadata files in

SAML2 Service » Advanced » Federation » SAML Federation Metadata files

You should list local file paths, separated by spaces. For example

    /etc/lemonldap-ng/metadata/main-all-edugain-metadata.xml /etc/lemonldap-ng/metadata/main-sps-renater-metadata.xml

In case an EntityID is defined in multiple files, the first match wins.

### Configure template IDP/SPs

SAML metadata does not contain all the information LemonLDAP::NG needs. It is recommended that you create a generic configuration for all the providers found in federation metadata.

In order to do this:

- Add a new SAML2 Service provider (or IDP)

- Leave the Metadata content empty

- Set Options » Federation » Entity Identifier to the Name= attribute of the federation. (eg: `https://federation.renater.fr/`)

All options set on this special provider will be applied to SPs (or IDPs) defined in the Renater federation

In the case of Service Providers, Federation Metadata files contain a list of attributes that the SP wishes to receive. These attributes can be flagged as optional or mandatory (`isRequired="true"`).

LemonLDAP::NG lets you decide what to do with these attributes:

- Keep: The attribute definition from federation metadata will be handled by LemonLDAP::NG

- Make optional: The attribute will be handled by LemonLDAP::NG, but made optional if it was mandatory

- Ignore: The attribute will never be sent to this SP

You can also define additional attributes to be sent in the Exported Attributes section. In case of a conflict between an attribute definition in federation metadata and an explicit definition in LemonLDAP::NG configuration, the LemonLDAP::NG configuration wins.

### Configure specific IDP/SPs

You may want to override the federation-wide defaults for some specific SP/IDPs. A common example is the Renater test SP that defines all its attributes as mandatory. Or you might want to disable AuthnRequest signature validation for some SPs

To do this:

- Add a new SAML2 Service provider (or IDP)

- Leave the Metadata content empty

- Set Options » Federation » Entity Identifier to the entityID of the provider you want to override

- Set the desired configuration options on this provider

### Configure SAML attributes

Federation metadata files contains information about attributes required or simply requested by federated service providers (SP). In order for those attributes to be successfully sent to providers, they must exist in the LemonLDAP::NG session, under the same name as the FriendlyName declared in metadata.

For example, the following attribute definition:

    <md:RequestedAttribute
        NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri"
        Name="urn:oid:0.9.2342.19200300.100.1.1"
        FriendlyName="uid" isRequired="true"/>

requires an `uid` attribute in the session. Make sure you configure your exported variables accordingly, and use macros to fill the gaps if needed.

## Subject ID

Added in version 2.17.

Some SAML SPs can now use a `subject-id` attribute instead of a NameID or `eduPersonTargetedID` (not supported in LemonLDAP::NG).

In order to provide a `subject-id` attribute, you must create a macro with

- Key: `subjectId`

- Value: `subjectid($uid, "scope.edu", "myrandomsalt1")`

The `subject-id` attribute will only be sent if the SP metadata contains the `urn:oasis:names:tc:SAML:profiles:subject-id:req` extension with a value of `any` or `subject-id`

## eduPersonTargetedID

If a SP declares that it wants an `eduPersonTargetedID` attribute, LemonLDAP::NG will automatically configure the default NameID format to persistent and will emit both a persistent NameID, and an `eduPersonTargetedID` attribute that contains this NameID.

If the SP requests a NameID format other than persitent, the `eduPersonTargetedID` attribute will not be sent. You might need to create a per-SP configuration and set the Force NameID format option to work around this.