Skip to end of metadata
Go to start of metadata

Federated Single Sign-On

The DARIAH Authentication and Authorization Infrastructure (DARIAH AAI) is based on SAML and Shibboleth in the European higher education identity inter-federation eduGAIN. See AARC Federations 101 Training Module or the DASISH Training on AAI for a gentle introduction to the underlying concepts.

For setting up a service in the DARIAH AAI, you want to protect it with a Shibboleth Service Provider, e.g. by following this SWITCHaai Tutorial. Other SP software following the SAML v2 standard can be used as well. In order to integrate better with the DARIAH AAI, follow this presentation on DARIAH AAI. See below for Service Developer Resources.

DARIAH User Management

Researchers and students in organizations that do not operate an federated Identity Provider can request a DARIAH "homeless" account using the DARIAH SelfService. It can be accessed here: https://auth.dariah.eu/cgi-bin/selfservice/ldapportal.pl.

Useful links:

For administrators, there is a DARIAH User Administration which can be accessed here. It allows you to create and manage "homeless" and federated accounts, assign users to authorization groups, e.g. DARIAH Wiki spaces, and manage organizations in a country. See the DARIAH User Administration manual

For Service Developers

DARIAH AAI is integrated in Higher Education Federations using the SAML standard. This means any Web application should integrate with a so-called SAML Service Provider (SP). The SP will protect your application, driving the log-in process and providing your application with attributes about the user who has logged in using a SAML Identity Provider (IdP) at another organization. Be sure you understand these concepts well, perhaps using the Federations 101 article that is linked above.

In the following, we concentrate on securing your Web application using the Shibboleth SP, which is a widely used and flexible Apache- oder IIS-based module. However, there are other popular Open Source SAML SPs around, such as simpleSAMLphp, pySAML2, mod_auth_mellon, or Spring-Security-SAML, or even commercial ones.

Basics of setting up a Shibboleth Service Provider for your application

Refer to Example Shibboleth SP Configuration for some example configuration files for all use-cases described below.

 

The Shibboleth SP will do all processing of SAML requests and handling of SAML responses for you. An application only needs to decide on when login should occur, evaluate user attributes (provided as environment variables to the application) and base its access decisions upon it. For a first overview, you can follow this SWITCHaai Tutorial. It sums up to two steps:

If you are using puppet, there is a puppet module created by SUB Göttingen that has some DARIAH AAI specifics and can be found at https://github.com/DARIAH-DE/puppetmodule-dariahshibboleth.

Registering your Service with the DARIAH homeless Identity Provider only

Federating with the DARIAH homeless IdP only is one deployment option. Is is however less recommended, as DARIAH wants to make use of the full potential of eduGAIN, allowing researchers to log in using their home organization account.

Here is what needs to be done if you choose homeless-only:

  • Save DARIAH IdP metadata (Test: https://ldap-dariah-clone.esc.rzg.mpg.de/idp/shibboleth and Production: https://idp.de.dariah.eu/idp/shibboleth) to you local disk and load them using <MetadataProvider type="XML" file="idp-metadata.xml"/> in shibboleth2.xml
  • Send your own SP's metadata (from https://your.sp.edu/Shibboleth.sso/Metadata) to register@dariah.eu with a request for entering them locally at the test and/or production IdP
  • Set the SP to direct login using <SSO entityID="https://ldap-dariah-clone.esc.rzg.mpg.de/idp/shibboleth"> (Test) or https://idp.de.dariah.eu/idp/shibboleth (Production) in shibboleth2.xml
  • decide whether you need REMOTE_USER="uid" or REMOTE_USER="eppn" for your application
  • enable the attributes you need in attribute-map.xml, among them you specifically might want to consider
    • <Attribute name="urn:oid:0.9.2342.19200300.100.1.1" id="uid"/>

Using this approach, you have to manually take care of when IdP or SP metadata change (the first two items). You'll better go with the next section.

Register your Service for federated Users (National Higher Education Federation / eduGAIN)

The preferred way of operating your SP is in your national research federation. The federation allows you to upload and manage your SP's metadata. All IdPs and SPs will refresh their metadata regularly such that updates are smooth. Most important, however, is the ability to join the research inter-federation eduGAIN. Thus you can register your SP, say, in the Finnish HAKA federation, and be interoperable with the DARIAH IdP, which happens to be registered in the German DFN-AAI.

Here is what needs to be done:

Some organizations are hesistant in making their IdPs release personal data. In order to be sure you receive the required user attributes from the IdPs you connect to, there are two initiatives your organization / SP should implement:

CoCo

The GÉANT Data Protection Code of Conduct for SPs is a self commitment of an organization running an SP. Your SP expresses compliance in its metadata. The documentation is at https://wiki.edugain.org/Data_Protection_Code_of_Conduct_Cookbook. IdPs respecting the CoCo can make a one-for-all attribute filter decision for any SP that complies with the Coco. Important about the CoCo is:

  • Specify your Privacy Policy. See https://de.dariah.eu/ServicePrivacyPolicy as an example. As you run a DARIAH service, you might consider copying it verbatim, or linking to it.
  • Specify the Attributes your SP requires. This is done in your federation's metadata management service. You should at least mark eduPersonPrincipalName (eppn) as required. Add any attribute your service uses or needs.

Research&Scholarship

The REFEDS Research & Scholarship is the other initiative. This tag is not self-asserted but granted by the federation operator. Compliance is expressed in metadata as well. Documentation is at https://refeds.org/category/research-and-scholarship. Contrary to he CoCo, R&S defines a fixed set of attributes any adhering IdP must release. The list is:

  • eduPersonPrincipalName
  • mail
  • displayName OR (givenName AND sn)

Get more out of DARIAH - the DARIAH AAI

The DARIAH AAI has been designed with several goals in mind.

  • Goal 1: users of DARIAH services (SPs) should authenticate via their home organization (campus IdP).
  • Goal 2: certain DARIAH services only allow particular user groups. This should be configurable centrally by the respective admins, for all DARIAH services.
  • Goal 3: DARIAH needs some user information
    • 3.a) she agrees to DARIAH Terms
    • 3.b) she is a researcher ( e.g. her organization or e-mail)
  • Goal 4: cope with a situation where users either
    • 4.a) have no campus IdP
    • 4.b) their campus IdP would not release Personally Identifiable Information (PII) to hitherto unknown SPs

Here's a diagram of how the architecture looks like. In essence, the DARIAH IdP turns into a SAML Attribute Authority (AA) and an SP makes an additional query to the DARIAH AA upon each login.

Follow the guide at Connect the DARIAH Attribute Authority in order to make your SP profit from these atttributes.

Attributes available in the DARIAH AAI - Full list

See the following sections for a description of the dariah-specific attributes and attributes most Campus IdPs might send.

These attributes need to be available in the attribute-map.xml configuration file of your Shibboleth SP (usually under /etc/shibboleth).

Some of these attributes are already present there and you only need to remove the comments around them.
The DARIAH-specific attributes need to be added entirly. The order is not relevant. 

Attribute nameAttribute oidExample valueDescription
eduPersonPrincipalNameurn:oid:1.3.6.1.4.1.5923.1.1.1.6john.doe@example.org 
eduPersonScopedAffiliationurn:oid:1.3.6.1.4.1.5923.1.1.1.9student@example.org 
eduPersonAffiliationurn:oid:1.3.6.1.4.1.5923.1.1.1.1student 
eduPersonEntitlementurn:oid:1.3.6.1.4.1.5923.1.1.1.7  
cnurn:oid:2.5.4.3John Doe 
givenNameurn:oid:2.5.4.42John 
snurn:oid:2.5.4.4Doe 
displayNameurn:oid:2.16.840.1.113730.3.1.241John Doe 
preferredLanguageurn:oid:2.16.840.1.113730.3.1.39DE 
ourn:oid:2.5.4.10Example Universityorganisation
mailurn:oid:0.9.2342.19200300.100.1.3john.doe@example.org 
schacCountryOfCitizenshipurn:oid:1.3.6.1.4.1.25178.1.2.5DE 
isMemberOfurn:oid:1.3.6.1.4.1.5923.1.5.1.1textgrid-users
  • Contains all DARIAH-specific groups the user is a member of
  • Can be used for authorisation by your application
  • Can be multivalued with individual groups semicola-separated
dariahRoleurn:oid:1.3.6.1.4.1.10126.1.52.5.2cn=National Representative,c=DE
  • Contains the context of all roles the user has within DARIAH
  • Can be multivalued with individual roles semicola-separated
dariahTermsOfUseurn:oid:1.3.6.1.4.1.10126.1.52.4.15Terms_of_Use_v5.pdf
  • Contains all Terms of Use (ToU) documents the user has accepted
  • Can be used by your application to make sure, that required ToU has been accepted
  • Can be multivalued with individual groups semicola-separated

The following code is an excerpt of the attribute definitions done in the attribute-map.xml configuration file:

attribute-map.xml
<!-- eduPerson attributes -->
    <Attribute name="urn:oid:1.3.6.1.4.1.5923.1.1.1.6" id="eppn">
    <Attribute name="urn:oid:1.3.6.1.4.1.5923.1.1.1.9" id="affiliation">
    <Attribute name="urn:oid:1.3.6.1.4.1.5923.1.1.1.1" id="unscoped-affiliation">
    <Attribute name="urn:oid:1.3.6.1.4.1.5923.1.1.1.7" id="entitlement"/>

<!-- standard attributes -->
    <Attribute name="urn:oid:2.5.4.3" id="cn"/> <!-- common name -->
    <Attribute name="urn:oid:2.5.4.42" id="givenName"/>
    <Attribute name="urn:oid:2.5.4.4" id="sn"/> <!-- surname -->
    <Attribute name="urn:oid:2.16.840.1.113730.3.1.241" id="displayName"/>
    <Attribute name="urn:oid:2.16.840.1.113730.3.1.39" id="preferredLanguage"/>
    <Attribute name="urn:oid:2.5.4.10" id="o"/> <!-- organization -->
    <Attribute name="urn:oid:0.9.2342.19200300.100.1.3" id="mail"/>

<!-- DARIAH-specific -->
    <Attribute name="urn:oid:1.3.6.1.4.1.5923.1.5.1.1" id="isMemberOf"/>
    <Attribute name="urn:oid:1.3.6.1.4.1.10126.1.52.5.2" id="dariahRole"/>
    <Attribute name="urn:oid:1.3.6.1.4.1.10126.1.52.4.15" id="dariahTermsOfUse"/>

Receive Central Authorization Information (the DARIAH isMemberOf-attribute)

DARIAH Administrators can assign users to groups, such as "texgrid-users", or "dariah-de-contributors". Such groups can be open for anybody, or upon request - see the DARIAH SelfService Documentation. The central DARIAH directory (DARIAH LDAP server) holds these authorization group information. Your service can use this multi-valued attribute in order to implement fine-grained access restrictions. In order to make use of them, first see the general topic on how to Connect the DARIAH Attribute Authority for querying the AA, and then add to attribute-map.xml the following line near the end:

attribute-map.xml
<Attribute name="urn:oid:1.3.6.1.4.1.5923.1.5.1.1" id="isMemberOf"/>

Consequently your Shibboleth SP will provide all values it receives as an Apache environment variable with the name isMemberOf. Please refer to the according documentation on how to use this in your application. It is also possible to use this information as Apache Access rules.

isMemberOf is a multi-valued attribute, meaning, that it includes all groups the user is a member of with the individual values separanted by semicola.

Example: consider a user that is member of the groups textgrid-users and dariah-de-contributors. The resulting value of isMemberOf would be "texgrid-users;dariah-de-contributors".

Process Role Information

DARIAH adminstrators can operate on a global or national level, or just for a single organization. See the DARIAH User Administration Documentation for the concept of the implementation. The central DARIAH directory (DARIAH LDAP server) holds this information as well. Your service can use this multi-valued attribute in a similar way. In order to make use of them, first see the general topic on how to Connect the DARIAH Attribute Authority for querying the AA, and then add to attribute-map.xml the following line near the end:

attribute-map.xml
<Attribute name="1.3.6.1.4.1.10126.1.52.5.2" id="dariahRole"/>

The value of the dariahRole attribute will include all roles the user is a member of in the DARIAH LDAP server, once again separated by semicola and in their context, as they do on the LDAP directory.

Example: consider a user with three different roles in the DARIAH LDAP directory:

  • cn=DCO-admin
  • cn=National Representative,c=DE
  • cn=orgadmin,o=SUB,c=DE 

The resulting value of dariahRole would be "cn=DCO-admin;cn=National Representative,c=DE;cn=orgadmin,o=SUB,c=DE".

Assure your Service receives personal Data about the user

If your application needs personal data, e.g. the e-mail address, or displayName, the DARIAH AA can provide this. With the e-mail as an example, one would

attribute-map.xml
<Attribute name="urn:oid:0.9.2342.19200300.100.1.3" id="mail"/>
...
<Attribute name="urn:oid:1.3.6.1.4.1.10126.1.52.4.15" id="dariahTermsOfUse"/>
shibboleth2.xml
<!-- shorthand from of what is below -->
<!-- make sure the sessionHook="/Shibboleth.sso/AttrChecker" is in place -->
<Handler type="AttributeChecker"                        
         Location="/AttrChecker"
         template="attrChecker.html"
         attributes="dariahTermsOfUse mail"
         flushSession="true"/>

 

Assure user has signed your Service's Custom Terms of Use

In order to check for your Service's Custom Terms, do the following:

  • First see the general topic on how to Connect the DARIAH Attribute Authority in order to include the registration flow
  • Send your Terms of Use document to register@dariah.eu, stating for which service it is used, which ToU version it is, and, if applicable, which authorization group you use
    • Your ToU document can be either a WWW link (then the URL should contain some version information)
    • Or a PDF file (then the filename should contain some version information). The Dariah AAI staff will put the file on the server auth.dariah.eu.
  • Assume you document is called "foobar-service-agreement_version1.pdf", or "https://my-project/ToU_v1.html", you can expect the dariahTermsOfUse to assume this value (it is a multivalued attribute, and another value will be the DARIAH terms, in this case "Terms_of_Use_v5.pdf"). This is how you can send check for these terms and send the user off:
attribute-map.xml
<Attribute name="urn:oid:1.3.6.1.4.1.10126.1.52.4.15" id="dariahTermsOfUse"/>
shibboleth2.xml
<!-- this is the complicated form -->
<!-- make sure the sessionHook="/Shibboleth.sso/AttrChecker" is in place -->
<Handler type="AttributeChecker" 
		 Location="/AttrChecker" 
	     template="attrChecker.html"
         flushSession="true">
    <AND>
		<Rule require="mail" />
		<Rule require="dariahTermsOfUse">Terms_of_Use_v5.pdf</Rule>
        <Rule require="dariahTermsOfUse">foobar-service-agreement_version1.pdf</Rule>
		<Rule require="dariahTermsOfUse">https://my-project/ToU_v1.html</Rule>
    </AND>
</Handler>



  • No labels