Managing Web Pages

With MIRACL Trust it is possible to configure web pages to display error messages, a logout page and a list of authorized Service Providers the logged in user has access to.

A simple example of an authorized SP page would be:

In order of priority, to display the web pages, the program looks in the config files for:

  1. Populated url parameters i.e. pages: error: url:, pages: logout: url: and pages: services: url: which can be used to serve remotely loaded web pages hosted by a web server (accessible by the MIRACL Trust SSO IdP server)
  2. If no populated url parameters are found then it will look for html template parameters, i.e. pages: error: template:, pages: error: template: and pages: error: template: which can be used to directly input simple html code
  3. If none of these pages parameters are populated then it will default to auto-populating the template parameters with very simple html 1.0 code, which is suitable for local testing of the program

Please choose a tab to see examples which show how the template and url parameters can be used to manage the web pages:

For testing, the /etc/srv-idp/integrations/pages_template.yaml file contains parameters that can be used to load simple html templates for displaying error, logout and services pages (remember that these parameters do not have to be stored in this file, they can be stored in any file that is then listed in the config.yaml includes list):

pages:
  error:
    template: >-
      <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>SSO ERROR</title></head><body><h1>SSO ERROR</h1><h2>{{.Data}}</h2><div><a href="{{.URL}}/services" title="SSO Login">SSO LOGIN</a> <a href="{{.URL}}/logout" title="Terminate the main SSO session">SSO LOGOUT</a></div><div><table><tr><th>FIELD</th><th>VALUE</th></tr><tr><td>Program</td><td>{{.Program}}</td></tr><tr><td>Version</td><td>{{.Version}}</td></tr><tr><td>Release</td><td>{{.Release}}</td></tr><tr><td>IdP URL</td><td>{{.URL}}</td></tr><tr><td>DateTime</td><td>{{.DateTime}}</td></tr><tr><td>Timestamp</td><td>{{.Timestamp}}</td></tr><tr><td>Status</td><td>{{.Status}}</td></tr><tr><td>Code</td><td>{{.Code}}</td></tr><tr><td>Message</td><td>{{.Message}}</td></tr><tr><td>Data</td><td>{{.Data}}</td></tr></table></div></body></html>
  logout:
    template: >-
      <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>SSO LOGOUT</title></head><body><h1>SSO LOGOUT</h1><h2>The IDP Session has been successfully deleted</h2><div><a href="{{.URL}}/services" title="SSO Login">SSO LOGIN</a></div><h3>Logout links of visited Service Providers:</h3><ul>{{ range $name, $logout := .SPList }}<li><a href="{{ $logout }}" title="Logout from {{ $name }}" target="_blank">{{ $name }}</a></li>{{ end }}</ul></body></html>
  services:
    template: >-
      "<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>SSO Authorized Service Providers</title></head><body><h1>SSO Authorized Service Providers</h1><h2>{{.SessionUserName}}</h2><div><a href="{{.URL}}/logout" title="Terminate the main SSO session">SSO LOGOUT</a></div><ul>{{ range $sp := .SPList }}<li><strong>{{ $sp.Name }}</strong><br /><em>{{ $sp.Description }}</em><ul><li><a href="{{ $sp.IDPLogin }}" title="IdP-Login: {{ $sp.Description }}" target="_blank">IdP-initiated login</a></li><li><a href="{{ $sp.Login }}" title="Login: {{ $sp.Description }}" target="_blank">Login Page</a></li><li><a href="{{ $sp.Logout }}" title="Logout: {{ $sp.Description }}" target="_blank">Logout</a></li></ul></li>{{ end }}</ul></body></html>"

You will note that the above snippet is different to the actual /etc/srv-idp/integrations/pages_template.yaml file. It contains the templates that the config schema loads by default if no web page parameters are filled in (for either html templates or fully-configured web pages)

  • The program is set up to serve authentication errors (404s, LDAP errors, SAML errors etc.) in json format. The above error page template example shows the variables that are available. Note that the Data field contains the error message.

  • It is possible to configure a logout page which gives a list of services the user is logged into for the current session. The logout page will be served at the /logout endpoint of your server. Visiting this will delete the cookie associated with the session. The user can then click on any of these services to log out of that particular service (the logout links are configured in the individual SP config sections, as will be explained below).

  • It is possible to make use of the /services endpoint to present a 'landing page' list of services that the user is authorized to access. Accessing this endpoint will present the user with a QR code to login, followed by a 'landing page' which presents the SPs that user is authorized to access by LDAP/AD config as below.

Using the examples below as guidance, it is also possible to load remote web pages to display the services, error and logout information.

Note that these pages need to be served with a web server on urls which are accessible to the MIRACL Trust SSO IdP server:


Example pages:

- Example Error Page
- Example Logout Page
- Example Services Page
- Example php Sanitize Page


The /etc/srv-idp/integrations/pages_url.yaml file contains parameters that can be used to specify the urls for remotely configured web pages that can be used for displaying error, logout and services pages (remember that these parameters do not have to be stored in this file, they can be stored in any file that is then listed in the config.yaml includes list):

pages:
  error:
    url: https://example.com/error
  logout:
    url: https://example.com/logout
  services:
    url: https://example.com/services

Example Error Page

The following example error page could be hosted at the above https://example.com/error url and could be used for handling error messages coming from the server. Note that, for an error page URL, the JSON error message is compressed with FLATE, encoded in base64 and added as a query parameter "e":

<?php
// Example PHP page to display errors generated by srv-idp.

$srvIdpURL = '';
$error_message = 'Unknown error';
if (!empty($_GET['e'])) {
    $data = base64_decode($_GET['e']);
    if ($data !== false) {
        $decoded = @gzinflate($data);
        if ($decoded !== false) {
            $json = json_decode($decoded, true);
            $srvIdpURL = $json['url'];
            filter_var($srvIdpURL, FILTER_SANITIZE_STRING);
            $error_message = $json['data'];
            filter_var($error_message, FILTER_SANITIZE_STRING);
        }
    }
}

$out = '<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" '
    .'"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">'."\n"
    .'<html xmlns="http://www.w3.org/1999/xhtml">'."\n"
    .'<head>'."\n"
    .'<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />'."\n"
    .'<title>SSO ERROR</title>'."\n"
    .'</head>'."\n"
    .'<body>'."\n"
    .'<h1>SSO ERROR</h1>'."\n"
    .'<h2>'.$error_message.'</h2>'."\n";

if (!empty($json)) {
    $out .= '<div><pre><code>'.json_encode($json, JSON_PRETTY_PRINT).'</code></pre></div>';
}

$out .= '<div>'
    .'<a href="'.$srvIdpURL.'/services" title="SSO Login">SSO LOGIN</a> '
    .'<a href="'.$srvIdpURL.'/logout" title="Terminate the main SSO session">SSO LOGOUT</a>'
    .'</div>'."\n";

$out .= '</body>'."\n"
    .'</html>'."\n";

echo $out;

Example Logout Page

The following example logout page could be hosted at the above https://example.com/logout url to give a list of services the user is logged into for the current session. The logout page will be served at /logout endpoint of your server. Visiting this will delete the cookie associated with the session. The user can then click on any of these services to log out of that particular service (the logout links are configured in the individual SP config sections, as will be explained below).

Note that, for a logout page URL, a JSON struct containing a map of logout links for each Service Provider will be compressed with FLATE, encoded in base64 and added as a query parameter "x". This example simple php page could be used to decompress and display the logged-in services for the current session. This provides links to the logout url that is configured in the individual SP config sections

<?php
// Example PHP page to display logout message from srv-idp.

require 'sanitize.php';

$srvIdpURL = '';
if (!empty($_GET['x'])) {
    $data = base64_decode($_GET['x']);
    if ($data !== false) {
        $decoded = @gzinflate($data);
        if ($decoded !== false) {
            $json = json_decode($decoded, true);
            $srvIdpURL = $json['url'];
            filter_var($srvIdpURL, FILTER_SANITIZE_STRING);
        }
    }
}

$out = '<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" '
    .'"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">'."\n"
    .'<html xmlns="http://www.w3.org/1999/xhtml">'."\n"
    .'<head>'."\n"
    .'<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />'."\n"
    .'<title>SSO LOGOUT</title>'."\n"
    .'</head>'."\n"
    .'<body>'."\n"
    .'<h1>SSO LOGOUT</h1>'."\n"
    .'<h2>The IDP Session has been successfully deleted</h2>'."\n"
    .'<div><a href="'.$srvIdpURL.'/services" title="SSO Login">SSO LOGIN</a></div>'."\n";

if (!empty($json['splist'])) {
    filter_var($name, FILTER_SANITIZE_STRING);
    $logout = sanitizeURL($logout);
    $splist = '';
    foreach ($json['splist'] as $name => $logout) {
        $splist .= '<li><a href="'.$logout.'" title="Logout from '.$name.'" target="_blank">'.$name.'</a></li>'."\n";
    }
    if (!empty($splist)) {
        $out .= '<h3>Logout links of visited Service Providers:</h3>'."\n"
            .'<ul>'.$splist.'</ul>'."\n";
    }
}

$out .= '</body>'."\n"
    .'</html>'."\n";

echo $out;

Example Services Page

The following example error page could be hosted at the above https://example.com/services url to make use of the /services endpoint to present a 'landing page' list of services that the logged in user is authorized to access. Accessing this endpoint will present the user with a QR code to login, followed by a 'landing page' which presents the SPs that the user is authorized to access:

<?php
// Example PHP page to display services message from srv-idp.
require 'sanitize.php';

$srvIdpURL = '';
if (!empty($_GET['x'])) {
    $data = base64_decode($_GET['x']);
    if ($data !== false) {
        $decoded = @gzinflate($data);
        if ($decoded !== false) {
            $json = json_decode($decoded, true);
            $srvIdpURL = $json['url'];
            filter_var($srvIdpURL, FILTER_SANITIZE_STRING);
        }
    }
}

$out = '<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" '
    .'"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">'."\n"
    .'<html xmlns="http://www.w3.org/1999/xhtml">'."\n"
    .'<head>'."\n"
    .'<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />'."\n"
    .'<title>SSO Authorized Service Providers</title>'."\n"
    .'</head>'."\n"
    .'<body>'."\n"
    .'<h1>SSO Authorized Service Providers</h1>'."\n"
    .'<div><a href="'.$srvIdpURL.'/logout" title="Terminate the main SSO session">SSO LOGOUT</a></div>'."\n";

if (!empty($json['splist'])) {
    filter_var($item['name'], FILTER_SANITIZE_STRING);
    filter_var($item['description'], FILTER_SANITIZE_STRING);
    $item['login'] = sanitizeURL($item['login']);
    $item['logout'] = sanitizeURL($item['logout']);
    $item['idplogin'] = sanitizeURL($item['idplogin']);
    $splist = '';
    foreach ($json['splist'] as $item) {
        $splist .= '<li><strong>'.$item['name'].'</strong><br />'
            .'<small><em>'.$item['description'].'</em></small>'
            .'<ul>'
            .'<li><a href="'.$item['idplogin'].'" title="IdP-Login: '
            .$item['description'].'">IdP-initiated login</a></li>'
            .'<li><a href="'.$item['login'].'" title="Login: '.$item['description'].'" target="_blank">Login Page</a></li>'
            .'<li><a href="'.$item['logout'].'" title="Logout: '.$item['description'].'" target="_blank">Logout</a></li>'
            .'</ul>'
            .'</li>';
    }
    if (!empty($splist)) {
        $out .= '<ul>'.$splist.'</ul>'."\n";
    }
}

$out .= '</body>'."\n"
    .'</html>'."\n";

echo $out;

Example php sanitize page

<?php

// Sanitize URL string
function sanitizeURL($url)
{
    filter_var($url, FILTER_SANITIZE_URL);
    return preg_replace('/&(?!amp;)/', '&amp;', $url);
}

Top