SeamlessAccess Homepage

Getting Started >Step 3. Implement the service

How does your system support federated authentication? In all cases, your service needs to be enabled with federated authentication. If a user can already sign into your site using their institution’s sign in credentials you may be able to simply configure your service to use SeamlessAccess.

3. Implement the service

Who does this work? This work is done by someone who configures your access systems for your site and the person/team that modifies the pages where sign in happens will make this change. This may be a system administrator, a software interface designer, or it could be a software developer. In some cases this work may be done by a vendor or consultant. The SeamlessAccess team will help you to identify the right person.

Once you have selected your implementation flavor, it is time to implement it. The steps for implementation depend on your selected flavor. Details for implementing each step are also included below.

SeamlessAccess uses software called “thiss.io”, a name derived from THe Identity Selector Software.

Implementing the “Limited” Flavor

For the “Limited” flavor, you will implement:

Implementing the “Standard” Flavor

For the “Standard” flavor, you will implement:

Implementing the “Advanced” Flavor

For the “Advanced” flavor, you will implement:

The “Advanced” flavor is significantly more complicated than the other implementations, and should only be used if you are unable to achieve your discovery and/or UX experiences otherwise.

An Example Implementation

You can see an example of the “Standard” implementation at our Demo Service. This site provides an example of the standard behavior, and can provide insight for your implementation.

Implementation technical details

Understand the End-User Data Flow

Each level of integration will have the user data flow through the environment along slightly different paths. Make sure you understand exactly where the data is coming and going via each integration as you design your environment. See this explanation of the user data flow for every integration.

Discovery Service Integration

For the Limited and Standard integration flavors, you will be using the SeamlessAccess discovery service. This service is based on the eduGAIN metadata list. You can see a list of participating organizations at the eduGAIN technical website.

By far the easiest integration is to use SeamlessAccess service as a standard SAML identity provider discovery service (DS). The DS URL is https://service.seamlessaccess.org/ds. You will use this URL in your Service Providers configuration where appropriate. Here is how to do this for some common SP software stacks:

Shibboleth

In the file /etc/shibboleth/shibboleth.xml modify the SSO element to read:


<SSO discoveryProtocol="SAMLDS" discoveryURL="https://service.seamlessaccess.org/ds/">
   SAML2
</SSO>

For a complete set of options related to discovery see the shibboleth documentation.

SimpleSAMLphp

In authsources.php (relative to the SSP config directory) find your SAML authentication source (often named ‘default-sp’) and set the discoURL parameter to https://service.seamlessaccess.org/ds/:


'default-sp' => array(
    'saml:SP',
    'entityID' => NULL,
    'discoURL' => 'https://service.seamlessaccess.org/ds/',
    ....
),

For more details visit the SSP documentation.

Display of SeamlessAccess Login Button

Including the component library

You will need to reference the SeamlessAccess component library before you can use it. For the Standard implementation, you will always reference through a CDN:


<head>
<!-- Include the SeamlessAccess Sign in Button & Discovery Service -->
<script src="https://service.seamlessaccess.org/thiss.js"></script>
</head>

Rendering the button

Include a <div> container that is identified with an id tag where you want the button to appear on your HTML page:


<body>
  <!-- Location for the SeamlessAccess login button -->
  <div id='putMyLoginButtonHere'></div>
</body>

And to display the button into this container, invoke the DiscoveryComponent.render function as a handler for the onload event on the window. This action will cause the button to initialize as soon as the window has finished loading. (NOTE: while it is possible to initialize the button component earlier, the behavior can be unpredictable and is not recommended.)


<script>
window.onload = function() {
  // Render the SeamlessAccess button
  thiss.DiscoveryComponent.render({
    loginInitiatorURL: 'https://sp.example.com/Shibboleth.sso/Login?target=https://sp.example.com/',
  }, '#putMyLoginButtonHere');
};
</script>

The render function in this code, takes two parameters:

  1. The loginInitiatorURL: - See the next section, “Integration of Login Button with your SAML SP”, for more details
  2. The location where to render the button - here you will use the id tag that you used for your html <div> container, formatted using CSS selector styling in quotes.

Content-Security-Policy considerations

If your website publishes a Content-Security-Policy you will need to make provision for the components served from the service.seamlessaccess.org CDN (or from your domain if you deploy your own version of thiss) by merging the following into your existing CSP:


Content-Security-Policy: script-src 'unsafe-inline' service.seamlessaccess.org; frame-src service.seamlessaccess.org;

The 'unsafe-inline' is required for the above DiscoveryComponent.render example, but could be removed if the onload function was included e.g. from a file.

Integration of Login Button with your SAML SP

The first step is easy to describe in general but the second step depends on exactly how your SAML implementation works. We provide examples below for the Shibboleth SP but if you run something other than Shibboleth you need to consult your documentation to figure out how the integration works.

The example above works out of the box for Shibboleth assuming you have configured https://service.seamlessaccess.org/ds as the discovery service as in the example above. The Shibboleth simplified SP configuration uses the URL /Shibboleth.sso/Login to trigger an authentication request using the discovery service configured in the <SSO> element.

In general the idea is to provide two hooks for the button component:

  1. A way to initialize a SAML discovery protocol request in the SAML SP
  2. A way to receive the response from the SAML discovery protocol request

For Shibboleth the loginInitiatorURL serves both purposes but in general you need to provide two parameters discoveryRequest and discoveryResponse which can be either URLs (in which case a redirect is performed) or JavaScript functions that are called by the component.

The discoveryRequest function is called with a single argument containing a JS object representing the chosen IdP - parameters include entity ID, icon, title etc. Normally this function will be used to initialize a SAML authentication request to the identity provider identified by entity.entityID.

For Shibboleth this is all handled by providing the single loginInitiatorURL parameter as in the example above.

The SeamlessAccess user experience

When implementing the “Advanced” flavor, you will need to recreate the SeamlessAccess user experience and interface. SeamlessAccess requires consistency in the user’s experience when using the service across different service providers. To this end, we provide several resources:

  • Advisory/Review Meeting - During the beta period, we are requiring at least one meeting for each service provider with our UI/UX team to review and advise on your plans for incorporating SeamlessAccess into your service. We highly recommend that you schedule this meeting as early as possible in your planning process. Approval from this team is required before you’ll be able to enable your service to work with the production service. You can contact contact@seamlessaccess.org to set up a meeting.
  • UI/UX guidelines - The guidelines for the user experience and interface can be found in section 2.4 - Improve the User Experience of Identity Provider Discovery of the Recommended Practices for Improved Access to Institutionally-Provided Information Resources. These guidelines have evolved since their writing, so it will be important to pair your understanding of these practices with the Advisory/Review Meeting described above.
  • Usability testing results - In planning the user experience for SeamlessAccess, the solution went through extensive usability testing. See the insights: RA21 User Research Summary

Install the SeamlessAccess service software

The SeamlessAccess software (thiss-ds) is registered as a package on npm. You can install the latest version of SeamlessAccess with the npm CLI command


> npm install [--save] @theidentityselector/thiss-ds

The thiss-ds package supports both CommonJS-style and ES6-style import as well as CDN delivery.

CommonJS:


var thiss = require("this-ds.js");

ES6-style:


import {DiscoveryService} from "thiss-ds";
import {PersistenceService} from "thiss-ds";

CDN:


<head>
<!-- Include the downloaded SeamlessAccess Discovery Client API -->
<script src="//unpkg.com/browse/@theidentityselector/thiss-ds"></script>
</head>

Also see the software documentation for more information.

Use the SeamlessAccess service software

To use the SeamlessAccess software (and related API), you will first create an instance of the DiscoveryService and/or PersistenceService object (installed by the package above), and make calls on it to perform the functions of interacting with the service. Note that the DiscoveryService object enables one to add their own MDQ-style lookup for entity objects and include the URL for the SeamlessAccess persistence service.

Creating the service software objects

When you use the SeamlessAccess software, you will be instantiating a client for the persistence or discovery service.

NOTE: the code snippets below assume that the software package has already been installed and is available for object and function calls.

EXAMPLE: persistence service object


  var ps = new thiss.PersistenceService('<persistence service URL>');

EXAMPLE: discovery service object


  var ds = new DiscoveryService('<mdq URL>', '<persistence service URL>');

SeamlessAccess service URLs

NOTE: production URLs are only accessible for services that have completed the review and acceptance processes.

SeamlessAccess persistence service URLs

SeamlessAccess service MDQ URLs

NOTE: you may substitute your own MDQ service

Full software documentation

Please refer to the full documentation and examples for information on how to use the service software. We recommend that you join the SeamlessAccess Slack conversation to ask technical questions and share experiences with other beta developers.

Request production access for your implementation

Before your advanced flavor implementation can go live, you will need to request your service domains to be included in our list of production implementations. Your user experience will need to have been reviewed before moving to production, so, be sure that you have allowed enough time for this process.

Once you are approved to go live, use this form to submit your production domains for access. Your request will be reviewed by the SeamlessAccess team, and you will be notified when everything is ready.

NEXT: Step 4. Tell your users

© 2020 All Rights Reserved SeamlessAccess

CONTACT