As part of an ongoing series, we’re helping to explain ways to configure SimpleSAMLphp as a centralized identity provider (IDP) for your organization.

The easiest way to keep online systems secure is to lessen the burden on that weakest factor – users keeping track of multiple passwords. We’re working through a series aimed at configuring SimpleSAMLphp allow systems administrators to centralize their identity and authentication services. Users log in once and are known across multiple applications.

Last week we walked through the steps required to install and configure a SimpleSAMLphp server using basic, hard-coded username and password authentication. This week we’ll modify that same server to leverage Tozny’s secure, password-free authentication platform for identity verification.

(Full Disclosure: As a member of the Tozny development team, I am, unsurprisingly, a huge advocate of this solution.  This week’s post will focus on our technology with SimpleSAMLphp, but the blog series will help you use any authentication method in conjunction with SimpleSAMLphp.)

Key Components

In order to follow along with this tutorial, you’ll need access to the following components:

Tozny’s Authenticator – the service that powers everything about this tutorial. You will need to set up a Realm with Tozny to house data about your users. In turn, end users will authenticate via the Tozny app using cryptographically strong keys stored on their mobile device. If you don’t yet have an administrative account with Tozny, sign up for the beta today and get started.

Tozny App – You will need to have the app installed on either an Android or iOS device to both enroll with and authenticate against your Realm.

SimpleSAMLphp Server – You can use the same SimpleSAMLphp server we set up last week, but we will make changes to its configuration so that it authenticates against Tozny’s server. Using a real identity provider rather than using hard-coded placeholder credentials converts our experimental server into a production-ready installation.

Tozny’s External Authentication Module – This is a fork of the default SimpleSAMLphp examplauth module, and it acts as the intermediary between your SAML server and Tozny itself. It’s open source and works without modification for services like Google’s G-Suite, SugarCRM, and Azure Active Directory.

Configuring Tozny

After registering for the Tozny beta, you’ll receive an introduction email and instructions for how to log in to the Administration Portal to manage your Realm. Take some time to locate your Realm’s key ID and secret – these are the pieces of information used to authenticate requests to the API.

Next, use the hamburger menu on the right hand side to select the Fields management page. You want to add a field (so click the “Add Field” button) named IDPEmail. This isn’t anything magic, but will allow you to configure two email addresses for users: the one they use to log in (their identity provider email, or IDPEmail) and the one through which they’ll receive a Tozny enrollment email.

While these two email address might eventually coalesce into a single address, it’s useful to have different addresses for the sake of account recovery. If a user loses access to their primary device, and you’re using the SAML server to protect your organization’s email (i.e. G-Suite or Office 365), they’d have no way to re-enroll a new device as they won’t be able to receive email.

Using your organization’s address for IDPEmail ensures smooth authentication, while using a secondary address for the user’s actual email ensures they can receive Tozny enrollment information.

At this point, you should create a user in your Realm for testing purposes. The username and email can be whatever you want, but the IDPEmail should use the somesite.com email domain we’ve been working with through these tutorials.

Installing Tozny’s SimpleSAMLphp Module

If you followed the default SimpleSAMLphp installation instructions, there will be a set of modules located in the /var/simplesaml/modules directory on your server. Move into this directory and download the Tozny module to that location:

$ cd /var/simplesamlphp/modules
$ wget https://github.com/tozny/simplesamlphp-toznyauth-external/releases/download/1.0.0/toznyauth.tgz

Extracting this archive file in the current location will unpack a /toznyauth directory with the module in its default disabled state. We need to both extract and enable the module:

$ tar -xzvf toznyauth.tgz
$ touch toznyauth/enable

The module is now installed and available for the server to use!

Configuring SimpleSAMLphp

As with our previous walkthrough, we will assume the users’ authentication domain is somesite.com and the SimpleSAMLphp server is running on a subdomain like sso.somesite.com.

Authentication Sources

After the completion of our first tutorial, there was an authentication source called “somesite” configured for your server using the default “exampleauth:userPass” module. We will tweak that existing source to switch from a static placeholder setup to use the Tozny module. The configuration block in authsources.php then becomes:

'somesite' => array(
    'toznyauth:External',
    'realm_key_id'     => 'sid_...',
    'realm_secret_key' => '49f127...fd9',
    'api_url'          => 'https://api.tozny.com',
    'attributes'       => array(
        'IDPEmail' => 'urn:oasis:names:tc:SAML:2.0:attrname-format:emailAddress',
    ),
),

The first line identifies that we are now using Tozny as an external authentication source. Further lines configure the Realm’s information (using the key ID and secret gathered from the Tozny administration portal). We are also adding a section to define the custom attribute we set for our users when configuring our Realm with Tozny earlier.

Identity Provider

Unlike the authentication source configuration, nothing needs to change about our hosted IDP metadata. We are still using the same server and keys and hitting the same authentication source. For reference, our /metadata/saml20-idp-hosted.php should still contain:

$metadata['https://sso.somesite.com'] = array(
    // The hostname of the server this SAML entity will use.
    'host'        =>  'sso.somesite.com',
    // X.509 key and certificate. Relative to the /cert directory.
    'privatekey'  => 'somesite.key',
    'certificate' => 'somesite.crt',
    'auth'        => 'somesite',
);

Testing the Workflow

Once the server is configured, testing the Tozny integration is as straightforward as testing any other authentication source. Navigate to https://sso.somesite.com and click the Authentication tab. Next, click “test authentication sources” and select the “somesite” configuration from the list.

Instead of being prompted for credentials, you will be presented with a Tozny QR code.

Scan this code with the same mobile device you used while enrolling your test user, and you will be logged in to SimpleSAMLphp as that user – the server will present you with identifying and meta information about you. This proves that the server is configured properly to interact with Tozny as an identity provider!

Now SimpleSAMLphp is configured with a real authentication provider; come back next week to learn how to integrate with a remote service provider – Microsoft’s Office 365.

Series Navigation

<< SimpleSAMLphp as an IDP for Google’s G-Suite