SAML Configuration

Service Provider

The reg-app needs at least one service provider configured, to function. To add such a configuration visit the "SAML properties" -> "Service provider" in the admin menue. Click "Add service provider". Specify the entity id, private key and certificate for this service provider. Click on "save". The entity id of a SAML service is typically the URL of the service, with 'sp' appended, i.e. https://<your-hostname>/sp. The private key and certificate should be created according to the rules of the federation you want to use. For testing purpose a self-signed certificate should be sufficient.

After the configuration is created, you need to edit it. In the textbox "Assertion Consumer Endpoint" you need to enter the URL "https://your-hostname/Shibboleth.sso/SAML2/POST". In the textbox "ECP Endpoint" the value has to be "https://your-hostname/Shibboleth.sso/SAML2/ECP". These values can not be choosen freely for now. This is a planned feature to gain more flexibility for the SAML Subsystem. To complete the configuration, add an entry for the hostname of the system. You can specify more than one, if virtual hosts are involved. When done, click on save, to persist the changes.

Federation

The configuration of a single IDP is not supported at the moment. You have to configure a federation, even if it consists of only one IDP. Look up the federation, you could use, on the eduGain website.

To add a federation, goto the Admin Panel, and click on "Federations". Click on "Add Federation" and specify a name of the federation and the URL, where the metadata can be downloaded. Click on save and review the entry, by clicking on the entry at the table of federations. On the view panel for the federation, you can click on "Poll now", to fetch the metadata from the specified URL.

If you want to edit the federation name, or the URL, click on "Edit" on the view panel.

Example eduGain

If you want to use Identity Providers from eduGain, you can use the URL https://mds.edugain.org/edugain-v1.xml to fetch the metadata. This is a very big file, and there are many participating IDPs. If you just want to pick specific IDPs from eduGain, you have to use the filtering mechanisms below. Attention: Due to the size of the eduGain metadatafile you have to set at least 2048Mb memory limit. In the docker version, this memory limit is set correctly in the docker-compose file from version 2.7.4 on. On other variants, you have to do this via the -Xmx2G command line option for the java process.

Filtering Entities

In the edit panel, you can specify an "entity category". With this attribute, you can filter specific IDPs from your federation metadata, based on their entity category. If you set the entity category filter to http://aai.dfn.de/category/bwidm-member for example, only IDPs with the following section in their metadata will be loaded.

<saml:Attribute Name="http://macedir.org/entity-category" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri" xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion">
  <saml:AttributeValue>http://aai.dfn.de/category/bwidm-member</saml:AttributeValue>
</saml:Attribute>

It's also possible to use a filter rule. In this rule, all Entites which are retracted from the session are visible afterwards. All others are filtered. If you want two specific entities from a federation, you could use the following rule:

package edu.kit.scc.webreg.dools.saml

import org.opensaml.saml2.metadata.EntityDescriptor;

global org.slf4j.Logger logger;

rule "remove all except"

    when
        $ed : EntityDescriptor( 
        		(entityID == "https://idp.abc.edu/idp/shibboleth") ||
        		(entityID == "https://idp.dfg.de/idp/shibboleth")         		 
        		)
    then
    	logger.info( "remove ed {}", $ed.getEntityID() );
    	retract( $ed );

end

Update Federation Data

You can update the federation data manually by clicking the "poll now" link. To update regulary you have to create a job class and a schedule. Use the following data for the job class:

• Name: choose freely
• Job class: edu.kit.scc.webreg.job.UpdateAllFederationMetadata
• Single node: Yes
• Properties: none

Don't forget to create a schedule and activate it.