No description, website, or topics provided.
Branch: master
Clone or download
Latest commit 6be1954 Feb 7, 2019
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.tx
_config FIX RealMe authenticator should only enable if it appears configurati… Jul 27, 2018
client
docs/en Update configuration.md Nov 27, 2018
lang
src
templates Updated the assert What's RealMe? pop-up text. (#35) Nov 29, 2018
tests
.codecov.yml Adding/updating various configs Jul 4, 2018
.editorconfig
.gitattributes API Supported module status improvements: Nov 27, 2015
.htaccess Move LICENSE.md, and ensure that all files are denied from user access Sep 22, 2015
.scrutinizer.yml
.travis.yml Update root version Sep 22, 2018
.upgrade.yml Fixing tests Jul 4, 2018
CONTRIBUTING.md Authentication Checks, licenses and contributing Nov 18, 2015
LICENSE.md Authentication Checks, licenses and contributing Nov 18, 2015
README.md DOCS update readme to emphasise support Sep 27, 2018
changelog.md [MAJOR] v2 rewrite, removes SimpleSAMLphp for onelogin/php-saml (#19) May 1, 2018
code-of-conduct.md API Supported module status improvements: Nov 27, 2015
composer.json
phpcs.xml.dist Adding/updating various configs Jul 4, 2018
phpunit.xml.dist Adding/updating various configs Jul 4, 2018

README.md

silverstripe-realme

Build Status SilverStripe supported module Code Quality License Version

Adds support to SilverStripe for authentication and identity assertion via RealMe.

This module provides the foundation to support a quick integration for a SilverStripe application with RealMe as an identity provider. This module requires extensive setup prior to being utilised effectively.

If integration with RealMe is wanted, it is best to get in touch with the RealMe team as early as possible. This can be accomplished by getting in touch with the RealMe team.

Releases

There are multiple releases of this module. The current stable version is the 3.x line. This is a stable module that provides logon (authentication) and assert (identity assertion) capability. The 2.x line can be used for SilverStripe 3.x support, and the older 0.9.x line is considered end of life and should not be used for new integrations.

Support

Support is provided via the GitHub Issues for this module. As the 3.0.0 release has not been fully tested for all project scenarios, if you encounter any issues please open a new issue here.

Requirements

This module doesn't have any specific requirements beyond those required by onelogin/php-saml, the tool used to control authentication with the RealMe systems.

These requirements are PHP 5.6, with the following required PHP extensions enabled: date, dom, hash, libxml, openssl, pcre, SPL, zlib, and mcrypt with the PHP bindings.

This module is designed to be run on a CWP instance, and there are two sets of installation instructions - one for use on CWP, and one for generic use.

Installation

The module is best installed via Composer, by adding the below to your composer.json. For now, we need to specify a custom version of the excellent onelogin/php-saml module to fix some XMLDSig validation errors with the RealMe XML responses, hence the custom repositories section.

{
    "require": {
        "silverstripe/realme": "^3.0",
        "onelogin/php-saml": "dev-fixes/realme-dsig-validation as 2.11.0"
    },

    "repositories": [
        {
            "type": "vcs",
            "url": "https://github.com/madmatt/php-saml.git"
        }
    ]
}

Once installation is completed, configuration is required before this module will work - see below.

Using in PHP 7.1

If you are installing this module on PHP 7.1 you may have to supress deprecation notices as this module requires php-saml which relies on the deprecated mcrypt library. You can add to your sites _config.php file:

use SilverStripe\Control\Director;

if (Director::isDev()) {
    error_reporting(E_ALL ^ E_DEPRECATED);
}

Configuration of RealMe for your application

RealMe provide two testing environments and a production environment for you to integrate with. Access to these environments is strictly controlled, and more information on these can be found on the RealMe Developers site.

See configuration.md for environment and YML configuration required before the module can be used.

Providing RealMe login buttons

By default, the module provides an Authenticator class in SilverStripe, adding a new login form. If you want to provide your own separate login form just for RealMe, then the built-in templates can help with this. They have been designed to integrate as cleanly as possible with SilverStripe templates, but it is up to you whether you use them, or roll your own.

See the templates documentation for more information on using or modifying these.

Testing for authentication

The RealMeService service object allows you to inject authentication where-ever it is required. For example, let's take a simple Controller that ensures that all users have a valid RealMe 'FLT' (a unique string that identifies a RealMe user, but is not their username):

class RealMeTestController extends Controller {
	/**
	 * @var RealMeService
	 */
	public $realMeService;

	private static $dependencies = array(
		'realMeService' => '%$SilverStripe/RealMe/RealMeService'
	);

	public function index() {
		// enforceLogin will redirect the user to RealMe if they're not authenticated, or return true if they are
		// authenticated with RealMe. It should only ever return 'false' if there was an error initialising config
		if($this->service->enforceLogin()) {
			$userData = $this->service->getUserData();

			printf("Congratulations, you're authenticated with a unique ID of '%s'!", $userData->SPNameID);
		} else {
			echo "There was an error while attempting to authenticate you.";
		}
	}
}

Appreciation

  • Sincere thanks to Jackson (@jakxnz) for his work reviewing and updating pull requests.