Service Provider Integration Guide

There are two steps to becomming a Service Provider member of Edugate, the first step is the completion of the Edugate Agreement (see http://www.edugate.ie/membership). The second step is the technical implementation, service providers must support SAML2 access to their service. This may already be supported by the service providers web-server or web-application, where it is not the following options can be considered.

 

Option 1. SAML Protected Proxy

Use of a web-server proxy service such as EZproxy or mod_proxy may be sufficient where the web-server proxy supports a SAML plug-in, in this scenario the proxy service is protected by a SAML plug-in (Shibboleth or otherwise), when the user has authenticated via the SAML plug-in the proxy service delivers the requested content. Note however, that in most cases the proxy service may not be able to transfer any SAML user data to the back-end resource and thus features such as personalisation, or role based authorisation within the application would not normally be possible.

Option 2. Application integration with SAML

Many of the applications used in the academic sector already support SAML either natively or using a web-server plug-in. The Shibboleth web-site maintains a list of known web applications that can be integrated with Shibboleth, SimpleSAML also maintains a similar list (see SimpleSAMLphp). Where the web application does not already support SAML or the proxy option is not suitable, adding support for SAML through application code can be achieved by either;

  • Invoking an API that implements the SAML protocol

  • Processing web-server variables set by a SAML plug-in

  • Implementing the SAML protocol directly in your code (not recommended).

1(a) SAML API libraries.

  • Using SAML libraries may be the only option in some scenarios, particularly if a SAML plug-in is not available or is not feasible with your web-server setup. There are a number of libraries available for each development platform.
  • There are a mumber of hosted SAML providers that will handle SAML on your behalf and provide a simplified API that you can invoke.
    • SSOCircle
    • OneLogin
    • PingOne
    • Okta

1(b) SAML Webserver Plugin

  • Relying upon web server variables is an option if there is a SAML plug-in (Shibboleth or otherwise) for your web-server. In this scenario the SAML plug-in acts passively by invoking SAML authentication when a specific URL is clicked and setting server variables (or headers) that are populated as a result of the authentication phase. Theses variables can then be extracted by standard application code for custom authorisation and personalisation purposes. Some applications may support the standard header variable REMOTE_USER, if your SAML Plugin can set this header it may be possible to integrate SAML into your application without any further application code. There are a number of web-server plugins that can enable SAML access to the web-server, these are divided here into open source or commercial implementations.
  • Open Source

    • Shibboleth ('Service Provider' for Apache/IIS/Java)**

    • Forgerock OpenAM*

    • JBoss Picketlink

    • SimpleSAMLphp**

    • Gluu Server (Community Edition)

  • Commercial

    • Microsoft Active Directory Federation Services**

    • Ping Federate

    • Gluu Server (Basc, Enterprise edition)

    • Tivoli Federated Identity Manager**

    • Novell Access Manager 

    • RSA Federated Identity Manager

    • Eduserv OpenAthens SP*

* These products are known to be interoperable with Edugate.

**HEAnet have direct experience integrating these products and they can be made to be compatible with Edugate

1(c) Implementing SAML natively in your code

  • If your web application cannot be integrated using third party code, applications/plugins or proxies then implementing SAML natively in your own code will be your only option, as with any protocol specification some parts of the protocol remain unspecified. However, the saml2int.org sub-specification will significantly reduce the development effort by elliminating protocol features that Edugate does not use and by clarifying many of the areas where the protocol specification is unclear.

1(d). OpenID or OAuth bridge

  • SimpleSAMLphp, and possibly other products as outlined above, can be configured as a gateway or bridge between a SAML identity provider and an OpenID/OAuth Relying Party. This may be useful if your application already supports OpenID or OAut

Option 3. SAML Delegation

Instead of supportng SAML directly, SAML support can be delegated to a third party that is an existing member of Edugate (or affiliated via eduGAIN). The third party may provide a simple HTML widget or simple proprietary HTTP based API, this approach is most widely used to offer a student discount. Third parties offering this service as of August 2016 are;

  • Campus.ie
  • SheerID.com
  • Myunidays.com
  • StudentBeans.com

If your service should be offered only within the Republic of Ireland, the third party will need to be advised of this.

Usage Models

There are two common approaches to using Edugate, the first uses Edugate for one-time verification, this is often used by providers of student-discount. The second approach is more suited where the user will login to the service frequently or where the provider wishes to avoid issuing credentials to end-users.

Model A: One-time verification

Service providers may use the federation for one-time verification which allows service providers to verify the identity and/or affiliations of a user so that the provider can provision a local user account for the users of the service. This allows the service provider to retain control over the user accounts it issues and may lessen the burden of integrating federated access into the service. The same scenario can be used at a later date to reconnect users with forgotten accounts or to provide a self-service password reset feature. Service Providers should bear in mind that a second credential may lead to high attrition rates due to the inconvenience of having to login using a set of credentials that has to be remembered. Service Providers that intend on using Edugate for one-time verification may find that the pseudononymous attribute 'eduPersonTargetedID' and role attribute 'eduPersonScopedAffiliation' particularly useful. A student’s affiliation may change during the academic term and should be revalidated at least once a year.

Model B: Single-Sign-On model

Using Edugate for Single-Sign-On can remove the need for service providers to maintain user credentials whilst providing a very convenient feature to users. Service providers may be able to avoid account management entirely for federated users if they find that Edugate and its members provide sufficient data so as to enable personalisation, authorization and persistence. Service Providers may still have to permit access to users who are not from an Edugate participating institution, a SAML bridge can be used to allow users login to the service using a social identity (e.g. Facebook, Twitter, Google, Yahoo! or LinkedIn). An example of this bridge can be seen at the LIR website (select 'Login' and then select the Social Login option. A bridge will present your application with a standard user object, regardless of whether the user his/her institution identity service or a social identity.

WAYF/Discovery Service Considerations.

When adding SAML support for services that will be accessed by more than one home organisation/institution a choice will need to be made on whether to use the Edugate central WAYF/Discovery Service or to develop similar functionality within the application code. Service Providers are advised to follow the best practice guidance at discovery.refeds.org. The Edugate centralised WAYF should be used as a last resort as it introduces an external dependency and can confuse users when logging in (as the look and feel of the WAYF website will be different from your website). Another important feature that your code should support is the automatic processing of frequent changes of digitally signed, remotely hosted metadata as the identity providers details that your application may be required to support may change frequently (e.g new webserver, new certificates etc).

Developer Resources.

A test identity provider service is provided, this can be used to test the login process to your service provider during development. The test identity provider log file can be viewed online, it shows the SAML authentiation reqeusts that were received from your SP, and the SAML responses that were returned. To register for an account on the test identity provider visit https://guestidp.edugate.ie/.  

The Edugate Technical Specification is in appendix A of the Edugate Membership Rules