Using SAML

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.

🔗︎ click to copy Information Flow

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 provides registration and authentication services in the context of SSO and services like change password and password reset.

Mydex CIC provide additional Identity Assurance Services for some clients but this is distinct from SSO 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 a 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 Subscribing organisation. There are a number of ways this can be implemented and each Subscribing organisation’s context will be different depending on the applications being connected to the SSO environment and the corporate approach to directory services e.g. use of an LDAP compliant directory.

Production Environments 🔗︎ click to copy

Mydex provides Subscribing 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 Subscribing 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 is 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 Subscribing organisation, its connections and the 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 🔗︎ click to copy

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

🔗︎ click to copy PKI representation

Securing your Keys 🔗︎ click to copy

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 🔗︎ click to copy

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 with SAML 🔗︎ click to copy

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 Subscribing 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',
      ),
      ),
      ),
      '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.