Handover Documentation

Version 0.1

Stuff your users don't care to know about.


Status: work-in-progress


SAFIRE is a project run by Tertiary Education and Research Network of South Africa (TENET) to enable user identity federation single sign-on (SSO) within its user community.

The South African Identity Federation allows staff, students and researchers from participating institutions to log into web-based services using their home institution’s credentials. SAFIRE participates in the global eduGAIN inter-federation, gaining access to over 2500 services around the world.
At the time of writing, secure.dirisa.ac.za is a DNS CNAME for the load-balancer running HAProxy which is not integrated with SAFIRE.

The system described here has not been made available publicly because the backend services are not yet ready to honor user’s credentials after the user has successfully authenticated against SAFIRE.

This section explains how to integrate SAFIRE to DIRISA web services.

Registration with SAFIRE

On behalf of DIRISA, Nobubele has registered DIRISA as a service provider (SP) of SAFIRE which carries the same connotation of a SAML service provider by following https://safire.ac.za/participants/sp/join/

DIRISA’s SAML entityID is https://secure.dirisa.ac.za/

System setup


  • Host: dev (
  • CPU: 4
  • RAM: 8 GB
  • Disk: 50 GB

Network requirements

  • Internet routable public IP address
  • Permit incoming TCP ports 80 and 443 from anywhere
  • Permit incoming TCP port 22 from administrator network for management


Everything runs as Docker containers so the docker host itself may run any of the operating systems compatible for installing docker-ce.

The setup of Apache2 and Shibboleth version 3 are contained in https://gitlab.com/dirisa/safire-web-services and run in a single container.

Consult the repository README for detailed instructions on how to orchestrate Shibboleth with SADMPTool and Subscription

DNS and SSL certificate

  • DNS name secure.dirisa.ac.za

The SSL certificate used for this service was created using Comodo Certificate Manager licensed to TENET, https://hard.cert-manager.com/customer/TENET

For details about certificate creation, go to https://projects.dirisa.ac.za/projects/system/wiki/DIRISA_SSL_Certificate

Operation overview

All HTTP requests for https://secure.dirisa.ac.za/ are served by the Apache2 container.

When a request URI matches any of the locations protected by Shibboleth, mod_shib issues a HTTP REDIRECT to the SAFIRE identity provider proxy website, https://iziko.safire.ac.za/... where the user is presented with a list of identity provider (idP) in the federation.

The excerpt below taken from Apache configuration file shows two URI protected with SAFIRE:

  • /subscribe/
  • /SADMPTool/
<Location /subscribe/>
	ShibRequestSetting requireSession true
	ShibRequestSetting forceAuthn true
	Require shib-session
	ProxyPass "ajp://subscribe:8009/subscribe/"
<Location /SADMPTool>
	ShibRequestSetting requireSession true
	ShibRequestSetting forceAuthn true
	Require shib-session
	ProxyPass uwsgi://dmp:8080/

The user has to select the correct idP for which she possesses valid login credentials and proceed to the login form served by the selected idP.

Only after successful authentication that the user will be redirected back to original requested URL and served by the actual backend service as defined in the Apache configuration.

On receiving a request, the backend service should honor the environment variables set by Shibboleth as provided by the idP:

REMOTE_USER mndlovu2@csir.co.za
AJP_Shib-Authentication-Instant 2019-03-25T09:56:16Z
AJP_Shib-Handler https://secure.dirisa.ac.za/Shibboleth.sso 
AJP_Shib-Identity-Provider https://iziko.safire.ac.za/ 
AJP_affiliation staff@csir.co.za;member@csir.co.za;employee@csir.co.za 
AJP_displayName Mbuyiselo Ndlovu
AJP_eppn MNdlovu2@csir.co.za
AJP_givenName Mbuyiselo
AJP_mail MNdlovu2@csir.co.za
AJP_o Council for Scientific and Industrial Research
AJP_persistent-id https://iziko.safire.ac.za/!https://www.dirisa.ac.za/shibboleth-sp!b815fed6c233d1d7042ebee438d8bd9897264dbc;https://iziko.safire.ac.za/!https://www.dirisa.ac.za/shibboleth-sp!b815fed6c233d1d7042ebee438d8bd9897264dbc 
AJP_schacHomeOrganization csir.co.za
AJP_sn Ndlovu
AJP_unscoped-affiliation staff;member;employee
Last updated on 29 Mar 2019 / Published on 29 Mar 2019
Edit on GitHub