Technical Archive

SAML 101 - An intro to SAML for sysadmin

This document intends to be a quick primer on SAML for those who want to get on with the rest of their todo list. SAML seems big and scary, because it has a lot of decisions and moving parts. But the reality is that many of these decisions have already been made for you, and you don’t need to know about the moving parts to make it work for you. Thus this primer attempts to distill out the most important bits in a way that’s easy to skim.

Generating eduPersonAffiliation from your internal directory

This page is intended to give you some ideas about how to generate an eduPersonAffiliation attribute that is useful to SAFIRE by reusing existing information you may already have in your internal directory services. What’s shown below are SimpleSAMLphp config snippets, but the ideas translate to pretty much all identity provider software. If you’re not using SimpleSAMLphp, hopefully the comments help you understand what is going on. All the authproc filters shown here are documented in SimpleSAMLphp’s docs.

Configuring SimpleSAMLphp for SAFIRE

SimpleSAMLphp has good documentation, and so this is not a complete/worked example of how to configure it. Instead this provides the SAFIRE-specific snippets you may need when working through that documentation. Configuring metarefresh to fetch SAFIRE metadata You should use the metarefresh and cron modules to manage SAFIRE’s metadata automatically. SimpleSAMLphp provides documentation on automated metadata management which explains the basics of how you set this up. This document assumes you have a working cron module and have enabled metarefresh.

Generating eduPersonEntitlement

The eduPersonEntitlement attribute is used to indicate a user’s entitlement to access a specific service or resource. For example, its most widely used value, urn:mace:dir:entitlement:common-lib-terms, is used to indicate eligibility to access licensed content from information publishers. Relationship to eduPersonScopedAffiliation Library information providers often support both eduPersonEntitlement and eduPersonScopedAffiliation as a means of limiting access to licensed resources. It is likely that there is significant overlap between values used for eduPersonAffiliation (and thus eduPersonScopedAffiliation).

Support for eduPersonEntitlement added

In our ongoing work to integrate library journal and platform providers, it has become apparent that we need to support the eduPersonEntitlement attribute. Support for this attribute has therefore been added to the Federation hub, as well as the test identity and service providers. To ease transition and to lower barriers to entry, the Federation hub may automatically generate a value for eduPersonEntitlement from eduPersonAffilation if none is supplied by the identity provider.

Integrating library information providers via SAFIRE

There is considerable interest in leveraging SAFIRE and eduGAIN to integrate with the various library information providers, such as academic content, journal, and database publishers. Information providers variously term this “Shibboleth”, “SAML” or “Institutional” logins, and in most cases are already integrated with other federations around the world. The following documents the integration status of various providers in SAFIRE. .library-status-green { background-color:#0f3; } .library-status-yellow { background-color:#ffde00; } .library-status-red { background-color:#ff5b33; } .

Testing your IdP or SP

Testing an Identity Provider The most obvious way to test an Identity Provider is to make use of SAFIRE’s Test Service Provider ( This SP is always aware of SAFIRE’s full attribute set and emulates a locally connected SP. By logging in, Identity Provider administrators are able to test their integration with SAFIRE as well as their own attribute release. (Likewise, end users can use it to see what attributes their home institution releases about them.

Monitoring of Identity Providers

As a courtesy, we monitor the reachability of the various South African identity providers and make that information available at The monitoring system initiates a single sign-on request, and reports the outcome as follow: Green means that we completed all the tests and found something that looked like a login page. Yellow means that we got as far as what we think should be a login page, but didn’t find a username field on it. The institution’s own monitoring or I.T. help desk may be able to provide more information. Red means that we weren’t able to contact the identity provider for some reason. This could be because there’s a network problem or that the there’s some problem with the identity provider (service not running, certificates expired, metadata expired, etc). The monitoring output shows the hosts we passed through on the way to what we believe is the login page. It may also give details of any problem(s) that were encountered.

Generating certificates for SAFIRE

Types of certificates SAML installations typically use at least two different certificates: one of the public facing portions of a website, and one to establish a private trust relationship between providers. Whilst it is possible to use the same certificate for these two roles, this is not best practice nor is it recommended. The technical requirements for identity- and service-providers definitively specify the requirements and recommendations for these two types of certificates.

Configuring G Suite (Google Apps) as an IdP for SAFIRE

G Suite for Education (formally Google Apps) includes a limited SAML identity provider. Because SAFIRE is a hub-and-spoke federation, this can be configured to work as an identity provider within SAFIRE — the federation will do the work of integrating service providers, avoiding the need to add each one individually. Note that we use G Suite’s Primary Email for eduPersonPrincipalName (and Name ID) because it corresponds to the username people log in with.

South African Identity Federation