tiqr simpleSAMLphp installation howto

Posted by: Ivo Jansch in: Development

tiqr is available in a number of flavours. One is the base library that you can integrate into your own security solution, another is a plugin for simpleSAMLphp that allows easy tiqr integration into an existing simpleSAMLphp setup.

This post explains how to install the simpleSAMLphp plugin and how to configure it.

We are going to assume you have a working simpleSAMLphp installation. If you don’t, we’d like to refer you to the excellent documentation of simpleSAMLphp itself.

Downloading the plugin and required libraries

Download the latest version of the simpleSAMLphp plugin from the download page. There’s a package with a demo setup, but for this howto we’re focussing on the plugin itself, which is what you’ll be using to integrate tiqr into your own setup.

Also download the tiqr library from the download page, as the plugin as basically a wrapper around this library, which does all the hard work.

Install the plugin in the modules/ directory of your simpleSAMLphp setup (or symlink it if you want to keep the directory structure clean). Also do ‘touch enable’ inside the plugin directly to enable the plugin in simpleSAMLphp. In the rest of this post, we’re going to assume the plugin is in /var/www/simplesamlphp/modules/authTiqr

Install the library anywhere you like, but preferably outside your document root so it can’t be browsed directly. In the rest of this post we’ll assume it’s in /var/www/library/libTiqr – adjust accordingly if you have it installed somewhere else.

Finally you’ll need to download phpqrcode and if you plan on using step-up authentication you’ll also need c2dm (for android) and apns-php (for iphone) for the push notifications. We’re assuming /var/www/library/apns-php and /var/www/library/c2dm in this post; again, adjust accordingly.

Configuration

Copy the file /var/www/simplesamlphp/modules/authTiqr/config-templates/module_tiqr.php to /var/www/simplesamlphp/config and edit the file. Here’s a description of the configuration values:

  • identifier: this is an identifier of your identity provider. This is typically a domainname and it’s what the user sees if they enroll an account. If you’re installing tiqr to enroll accounts at my.piggybank.com then my.piggybank.com would be a suitable identifier.
  • name: The name of your service, e.g. ‘Piggybank’
  • auth.protocol: Every tiqr based mobile app is identified by a set of url specifiers. If you use the tiqr application from the appstore, the value for this would be ‘tiqrauth’. If you build your own iphone app and that uses the url specifier ‘piggyauth’, then that’s what you’d configure here. It ties the identity provider to the mobile apps.
  • enroll.protocol. Similar to the previous entry but for enrollment. ‘tiqrenroll’ for the default tiqr app, ‘piggyenroll’ if that’s what you used while compiling your own apps.
  • ocra.suite: The challenge response algorithm to use for authentication. Must be a valid OCRA suite value (see the OCRA spec). Note that we don’t support counter and time based input, so you can only use OCRA suites that do not contain counter or time inputs. If you’re confused by this setting, you can leave it to the default, which results in the system using 10-digit hexadecimal challenges, a 6 digit numeric response, and SHA1 as the hashing algorithm.
  • logoUrl: An url that points to your logo. The logo is automatically scaled down but to avoid high download times, try to stay under 250×250 resolution. The logo will be displayed in the app during enrollment and authentication steps.
  • infoUrl: An url that contains a page with more information about your enrollment process. If a user enrolls for your service, this page is where they’ll go to for questions. You can provide any url that you like but typically it’s a page on your main company website.
  • tiqr.path: This is the path where you installed the tiqr library, e.g. /var/www/libary/libTiqr. You can provide an absolute path or a relative path (relative to the location of this config file!)
  • phpqrode.path: The location of phpqrcode, e.g. /var/www/library/phpqrcode
  • apns.path: The location of apns-php, e.g. /var/www/library/apns-php
  • apns.certificate: Your Apple push notification certificate.Note: if you use the tiqr app store app, you can’t send push notifications, to use this feature you need your own apps and your own certificates.
  • apns.environment: Set to ‘sandbox’ if you’re testing the push notifications, set to ‘production’ if you use the push notifications in a production environment.
  • c2dm.username: The username you use for your google Cloud 2 Device Messaging account (android push notifications).
  • c2dm.password: The password for the C2DM account.
  • c2dm.application: The application identifier of your custom android app, typically com.yourorganization.yourapp
  • statestorage: This is the name of the storage class that you will be using to store temporary session data. The default is ‘file’ which stores the state information in the /tmp folder. If you have memcache installed, you can use ‘memcache’ instead. See the documentation inside the statestorage folder for memcache or file based specific configuration options.
  • devicestorage: Tiqr supports exchanging hardware based devicetokens for more generic notification tokens. This is only required if you use the push notifications. You can use a tokenexchange server to handle the token swapping. Set this to ‘dummy’ if you do want push notifications but do not want to use a token exchange (not recommended).
  • userstorage: Tiqr must store user secrets and other details for a user. By default this setting is set to ‘file’ which stores the data in JSON files in the specifified directory. While this is great for testing purposes, we recommend you implement your own user storage (e.g. your existing user database or an LDAP server). To do this, have a look at the userstorage subdirectory in the authTiqr diretory.

Using tiqr for general authentication

To use tiqr for general authentication in a simpleSAMLphp setup, you should configure tiqr as an authsource. To do this, you have to add it to simpleSAMLphp/config/authsources.php like this:

    'authTiqr' =>
         array(          
             'authTiqr:Tiqr',
         ),

This allows users to login using the tiqr mechanism. The default implementation has a ‘create new account’ link in the login screen which allows uses to do a simple enrollment (typically you’ll want to integrate enrollment into your business processes, but this should get you started).

Using tiqr for step-up authentication

Tiqr works great as a step-up authentication method. This means that the user logs in using a regular username/password method first, and then confirms his identity using his phone and a tiqr app. To accomplish this, tiqr supports use as a processing filter. This way you can append tiqr authentication to an existing authsource. To do this, edit config/authsources.php and hook up tiqr like this:

'default-sp' =>
    array(      
        'saml:SP',
        'idp' => 'https://login.yourdomain.com/simplesaml/saml2/idp/metadata.php',
        'authproc' => array(
               10 => array(
                   'class' => 'authTiqr:Tiqr',
                   'uidAttribute' => 'urn:oid:0.9.2342.19200300.100.1.1',
                   'cnAttribute' => 'urn:oid:2.5.4.3',
               ),
           ),
       ),

This configures a federated authsource that uses a hypothetical Identity Provider for the first login. It then attaches a processing filter to it by adding an entry to the authproc array. All it takes is defining that the class for this filter is authTiqr:Tiqr, and a definition of which attributres Tiqr should use as the display name and user id in its authentication process. (in this case urn:oid:… identifiers since our hypothetical IDP uses oids).

Using tiqr for basic authentication, but another source for enrollment

There is a third way to use Tiqr. Suppose you want to use it as the primary authentication method for a site, but you don’t want anybody to be able to create accounts. Suppose you have an alternative login through another authsource that you want users to complete before they can enroll for Tiqr. This usecase is supported.

Suppose that we want the user to login to the authsource ‘example-userpass’ first (one of the simpleSAMLphp demo authsources) before they can enroll, and effectively link the phone identity to a userpass identity. In that case, we would configure tiqr in config/authsources.php like this:

'authTiqr' => array(
       'authTiqr:Tiqr',
       'enroll.authsource'=>'example-userpass',
       'enroll.uidAttribute'=>'uid',
       'enroll.cnAttribute'=>'cn',
    ),

This configures authTiqr as the main authsource, but it tells tiqr that for enrollment, it should use example-userpass (or any other authsource you have defined in authsources.php). Similar to the previous example we need to map the userid and display name of the other authsource to tiqr’s fields, so that tiqr knows which fields to use for the user.

 

7 comments to “tiqr simpleSAMLphp installation howto”

  1. Rehan zegt:

    Hi
    I have implemented the tiqr server.
    http://hangman.move.pk/www/enrol.php

    every thing working fine but when enroll a user then read the qr code it always “enrolment failed can not connect ……”
    The qr generated key when I hit in browser it
    Shows the result as attached picture.
    whats the issue is.
    May I change the android app coding or something.

    Rehan Ahmed | Sr Software Engineer

  2. Joost van Dijk zegt:

    Hi Rehan,

    This typically happens when your phone cannot connect to your web server.
    Please check if your web server can be reached at http://hangman.move.pk from your phone by opening that page in your phone’s browser. If you are using an iPhone with tiqr version 2.5 or later, another issue could be that backend communication is restricted to TLS v1.2 by Apple, so you should run your server on https. The Android version does not have this restriction.

  3. Joeri zegt:

    Hi Joost,

    We hebben geprobeerd Tiqr te implementeren in SimpleSAMLphp. Alles gaat goed tot dat we de Enroll QR code scannen in de Android App.

    We krijgen dan de volgende melding in de app te zien:
    Ongeldig antwoord van de registratieserver. Neem contact op met de website beheerder.

    Alvast bedankt!

    Met vriendelijke groet,
    J. van den Bergen

  4. Joost van Dijk zegt:

    Hi Joeri,

    Are you using the latest version of the simplesamlphp tiqr module?

    Also make sure your tiqr server can be reached from your Android device (localhost won’t work!). If you scan the QR code with a QR code scanner, and strip the tiqrenroll:// prefix, you will get a URL. Can this URL be openen from the android device?

  5. Joeri zegt:

    Hi Joost,

    Yes, we are using the latest version of the SimpleSAMLphp Tiqr module.

    The server can reached from the Android app, the server is attainable external. So this couldn’t be the problem. Further we’ve checked the QR code with an other QR-code app, and I think the problem is in the conversion of the QR-code. The url starts with tiqrenroll:// but it carry on directly with http://. So the url in the QR-code looks like this: tiqrenroll://http://verify.novotix.online/module.php?……….. Beside that the url looks different from the demo at tiqr.org.

    Btw, we have installed SimpleSAMLphp as a hosted platform directly in DirectAdmin outside the public_html directory. And the www directory within public_html. We are able to install it in the directory /opt or /var but we can’t change the Virtualhost in httpd.conf because of the installation of our hostplaform DirectAdmin.

    Thanks in advance.

    Regards,
    Joeri

  6. Joeri zegt:

    Hi Joost,

    We have executed the url after the prefix tiqrenroll:// from the demo.tiqr.org authentication and our own authentication. After a comparison the metadata respons is exactly the same in structure as the demo on demo.tiqr.org. So I am a bit lost right now…

    Can you please help me out?

    Thanks again!

    Regards,
    Joeri

  7. Joost van Dijk zegt:

    Hi Joeri,

    Weird, can you reproduce using a local install, using

    https://github.com/SURFnet/tiqr/wiki/Quick-Start

    If that doesn’t work either, please create an issue here:

    https://github.com/SURFnet/simplesamlphp-module-authtiqr/issues

Leave a comment