Using SAML

Business Perspective

SAML as a protocol was created to support federated identity services and the notion of Single Sign-On (SSO) within organisations and across organisational boundaries as part of an identity federation. Mydex Identity Services supports SAML in the context of a federated identity service and for Single Sign-On.

At it’s core, it is the MydexID which in its own right is a multi-protocol ID, enabling the individual to use a single identity to access services across the internet using different protocols adopted in different federations and open standards. Currently the protocols supported are SAML, Mozilla Persona and shortly OpenID.

SAML itself has been adopted by a number of identity federations and for each specific profile have been created to support the needs of that federation. Mydex Identity Services can support multiple profiles of SAML. We provide a standard Mydex profile that any service provider can adopt and use. Alternatively if the objective is to join a federation then a specific profile can be selected and implemented such as Shibboleth.

These guidance notes provide specific information for organisations seeking to:

  • be service providers (relying parties) in the implementation of the SAML protocol
  • deliver Single Sign-On to two or more of its systems within the organisation or across organisations and other service providers that need access to these services
  • remove the need for multiple sets of credentials and repetitive logging and deliver a more seamless experience

Organisational and environment verification

Your organisation is connecting to the Mydex Trust Framework and as such a series of verification steps are carried out by Mydex in a similar way to that of issuing Extended Validation certificates. This process is currently manual and seeks to verify:

  • that your organisation as a legal entity exists
  • is in control of the domains being connected to
  • has authority to sign the terms of connection

This process requires some specific information as follows which is also used to configure your organisation and the connecting services into our production environments.

You control the registration and authentication journeys

The registration and authentication journeys are totally under your control and can be branded to suit your organisation’s goals and objectives. They are best thought of as wizards which you produce and make specific calls to the Mydex API’s. We have developed example journeys and simulations and made the code for these available as templates that are free to copy and make use of by your own organisation.

You can try out the simulated connection to the Mydex platform at

https://dev.mydex.org/simulated-connections/z9-mobile/

This journey shows an organisation (Z9) offering an individual the opportunity to connect an existing account with the organisation to their MydexID and personal data store. As you will see the branding, look and feel and journey is totally under the organisation’s control (Z9 is a fictional brand we created for the purpose of illustration). There are some specific iFrames we serve up to you during the process in order to protect a members personal data, namely their password and private encryption key.

Z9 Simulated Connection

If the individual does not have a MydexID or personal data store they can simply get one by going through a simple registration process which is controlled by the organisation. At the end of the process the individual has a permanent connection between their customer records and their MydexID and personal data store.

Basic identity services

Where only basic identity services are being used the registration process is very similar but the subsequent authentication process for login next time is a simple matter of entering their MydexID and password once and then being able to access any application that supports the MydexID.

Technical Perspective

Implementing SAML is relatively straightforward. There are many open source and commercial solutions that provide SAML support for service providers (relying parties).

Mydex CIC itself uses an open source solution called SimpleSAMLphp. We operate the Identity Provider configuration to support our SAML based services and we also use SAML as a protocol ourselves for our personal data services platform where our members login into their personal data store. In this context we have configured SimpleSAMLphp to act as service provider.

The diagram that follows shows the basic flow of information during the authentication process for an individual seeking to sign in using their MydexID to a service provider who supports SAML with Mydex Identity Services.

Most commercial off-the-shelf and open source applications support SAML in the context of a service provider out of the box. Please refer to your application documentation for information on how you configure these to use an external identity service.

SAML 2.0 enables web-based authentication and authorisation scenarios including cross-domain single sign-on (SSO), which helps reduce the administrative overhead.

Mydex Identity Services providers registration and authentication services in the context of Single Sign-On and services like change password and password reset.

Mydex CIC provide additional Identity Assurance Services for some clients but this is distinct from Single Sign-On and is an additional chargeable service.

The service provider (sometimes called a relying party) is responsible for access control to their services. This means giving authorisation for an registered and authenticated MydexID to access each application. The precise level of access and functionality they can make use of is an internal decision by each organisation. There are a number of ways this can be implemented and each organisation’s context will be different depending on the applications being connected to the Single Sign-On environment and the corporate approach to directory services e.g. use of an LDAP compliant directory.

Production Environments

Mydex provides organisations with two environments to work with as follows:

  • The Sandbox environment - This is a replica of our live environments for identity and personal data services and enables any organisations to experiment, develop and test their connections easily and quickly.
    • https://sbx.mydex.org is the personal data services environment from which profile information and other data is sourced.
    • https://sbx-idp.mydexid.org is where the Mydex implementation of SimpleSAML identity provider is located. There is no actual UI for this site, but it is where the config files for your SAML setup will point to.
  • The live environment - This the live operational environment subject to the terms of connection and is part of the Mydex Trust Framework. Connection to this environment requires verification of your organisation, its connections and environments that are to be connected.
    • https://api.mydex.org - this is the API services that is used to send and receive profile information from and to the individual personal data store. It can be used for a wider range of data services as well.
    • https://idp.mydexid.org is where the SimpleSAML identity provider is located. There is no actual UI for this site, but is where the config files for your SAML setup will point to.

Basic configuration overview

We use PKI (public key infrastructure) to secure our service, all traffic is encrypted. We issue the public and private keys needed by you.

Securing your Keys

Mydex is the key issuing authority and we will distribute a public and private key pair to you for use within our identity services environment. We will also issue you with our public key as an IDP which you will use to encrypt all traffic sent to us.

The process flows and how it works both for registration and authentication are shown below. Our service is largely API driven with some specific iFrames served up during the processes to ensure protection of the individuals personal information.

Mydex Identity Services are delivered as a web service. You can control the journey your customers or citizens take through registration and authentication and embed these into your website or application.

Metadata

Metadata ensures a secure transaction between an identity provider and a service provider. Before metadata, trust information was encoded into the implementation in a proprietary manner. Now the sharing of trust information is facilitated by standard metadata. SAML 2.0 provides a well-defined, interoperable metadata format that entities can leverage to bootstrap the trust process.

In order to connect to the Mydex IDP, we must send you as the service provider our metadata and then receive metadata from you as the service provider to complete the two-way connection.

The meta data is in a predefined format as follows and can be generated from your SAML utility.

Once this is completed, the requests and responses can flow between the Service Provider and Mydex as the IDP as shown above.

Getting Started

Setting up with the Mydex Sandbox

Mydex has a sandbox and live environment. We recommend you get set up against our sandbox first to test your connection. Once you have got it working correctly at a technical level and your organisation has completed verification we will move you across to our live environment when you are ready.

The key steps you need to take are as follows:

  1. SAML Service Provider - If you have a SAML package already go to step 2, if not then select a suitable SAML package to meet your needs:
    1. We use SimpleSAMLphp for both identity provider and service provider side of our work.
    2. There are many open source options to choose from.
    3. Many commercial applications support use of SAML for Single Sign-On.
  2. Request PKI keys from Mydex - We manufacture the keys for you, one private and one public.
    1. send an email to developersupport@mydex.org
      1. Please include the following information in your email as it is essential to creating your certificate:
        1. Country
        2. State or Province Name/County
        3. City
        4. Organisation Name
        5. Common Name (your server FQDN) This is this domain name that your server is located on (ie. pds.mydex.org)
        6. Email address
  3. Configure your SAML environment for use with our Sandbox with the endpoints below
    1. IDP root URL:
      https://sbx-idp.mydexid.org/pt/saml
    2. SingleSignOnService URL:
      https://sbx-idp.mydexid.org/pt/saml/saml2/idp/SSOService.php
    3. SingleLogoutService URL:
      https://sbx-idp.mydexid.org/pt/saml/saml2/idp/SingleLogoutService.php
    4. Direct link to iframe login form:
      https://sbx-idp.mydexid.org/pt/saml/saml2/idp/SSOService.php?spentityid=https://sbx-idp.mydexid.org/pt/saml/saml2/idp/metadata.php&source=idp-userpass&RelayState=<your-redirection-url>
  4. Request Mydex metadata
    1. Mydex will respond with their metadata. In the case of SimpleSAMLphp, it may look something like this:
    2. $metadata['https://sbx-idp.mydexid.org/pt/saml/saml2/idp/metadata.php'] = array (
        'entityid' => 'https://sbx-idp.mydexid.org/pt/saml/saml2/idp/metadata.php',
        'contacts' =>
        array (
          0 =>
          array (
            'contactType' => 'technical',
            'surName' => 'Administrator',
            'emailAddress' =>
            array (
            0 => 'support@mydex.org',
            ),
          ),
        ),
        'metadata-set' => 'saml20-idp-remote',
        'SingleSignOnService' =>
        array (
          0 =>
          array (
          'Binding' => 'urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect',
          'Location' => 'https://sbx-idp.mydexid.org/pt/saml/saml2/idp/SSOService.php',
          ),
        ),
        'SingleLogoutService' =>
        array (
          0 =>
          array (
          'Binding' => 'urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect',
          'Location' => 'https://sbx-idp.mydexid.org/pt/saml/saml2/idp/SingleLogoutService.php',
          ),
        ),
        'ArtifactResolutionService' =>
        array (
        ),
        'keys' =>
        array (
          0 =>
          array (
          'encryption' => false,
          'signing' => true,
          'type' => 'X509Certificate',
          'X509Certificate' => '#######################',
          ),
          1 =>
          array (
          'encryption' => true,
          'signing' => false,
          'type' => 'X509Certificate',
          'X509Certificate' => '#######################',
          ),
        ),
        'assertion.encryption' => TRUE,
      );
                              

      assertion.encryption = TRUE is essential for ensuring encrypted SAML messages.

    3. You need to place this metadata in your SAML configuration. In SimpleSAMLphp this would be in the following file:
      metadata/saml20-idp-remote.php
  5. Send Mydex your metadata
    1. To generate your metadata you need to do (if using SimpleSAML), set your config/authsources.php to:
    2. 'default-sp' => array(
          'saml:SP',
          'entityID'  => 'https://sbx-idp.mydexid.org/pt/saml/',
          'idp'       => 'https://sbx-idp.mydexid.org/pt/saml/saml2/idp/metadata.php',
          'ssoPortalUrl'=> 'https://sbx-idp.mydexid.org/pt/saml/saml2/idp/SSOService.php',
          'privatekey' => 'server.pem',
          'certificate' => 'server.crt',
      ),            
      • entityID' needs to be changed to be something unique for each SP (not https://sbx-idp.mydexid.org/pt/saml/ or anything in the https://sbx-idp.mydexid.org domain), ie. https://yoursp-url.com/simplesaml.
      • Make sure there are no other ‘default-sp’ entries, so comment (or delete) any other ones out!
      • Go to: http://your-sp.com/simplesaml/module.php/core/frontpage_federation.php Then click on ‘Show metadata’ for SAML 2.0 SP Metadata, copy and paste the SimpleSAMLphp flat file format and send it over to us so we can add it as an SP for the IDP to recognise.
  6. Await confirmation from Mydex
    1. Mydex will normally respond within 24 hrs with confirmation that everything is in place.
  7. Test
    1. You should now be able to register users and authenticate against Mydex Identity Services.
    2. Report any problems to developersupport@mydex.org.

Once an individual has successfully registered and logged into to their first service, they will subsequently be able to seamlessly login to all subsequent services within your domain.