With "Shibbolized Tiqr" (or "tiqrshib"), Shibboleth IdP is able to rely on "tiqr" as an additional authentication method.
For more information about the tiqr project, visit https://tiqr.org/
Visit our website https://meatwiki.nii.ac.jp/confluence/display/tiqr/Installing%20Shibbolized%20Tiqr for latest updates about the project.
There are one document (README.md, this doc) and two packages. Two packages are placed in two different directories, named "tiqrzend/" and "idp/". We call the first package "tiqrzend", and call the second package "the IdP extension" or just "the extension".
"Tiqrzend" is a software written in PHP, which is responsible for the tiqr authentication itself. Technically, it is written with Zend Framework v1.
"The IdP extension" is a software written in Java, which runs as one of Shibboleth IdP's "External Authentication" extensions.
This whole project is tested under the following environment and softwares.
- CentOS 7.3
- httpd 2.4.6-45
- PHP 5.4.16
- Oracle JDK 1.8.0_144
- Apache Maven 3.2.1
- Tomcat 8.0.45
- Shibboleth IdP 3.3.1
- Shibboleth SP 2.6.0-2.1
This project depends on the following libraries:
- phpqrcode 1.1.4
- Zend framework 1.12.9-minimal
- tiqr 1.0.0 (with bug fixes and backports)
- tiqr-zf 1.0.0 (with bug fixes)
Prepare phpqrcode library, which is not bundled in this project.
* http://phpqrcode.sourceforge.net/
This document assumes Shibboleth IdP and Shibboleth SP are already installed and configured appropriately. That is, IdP should be able to authenticate users per SP's authn request, and supply users' attributes back to SP.
Because Shibbolized Tiqr implicitly requires them, check if appropriate attributes are passed to SP.
- ePPN (eduPersonPrincipalName)
- displayName
On CentOS 7, the following packages must be installed.
- httpd php mod_ssl php-gd php-pdo php-mcrypt
If you want to use sqlite3 for a backend db, "sqlite" package is also required. Note that the sample configuration bundled in this project requires it.
If you are going to use MySQL instead, "mysql-connector-odbc" and "php-mysql" will be needed.
The following command will install all the modules possibly required. Not minimal, but probably enough.
$ sudo yum -y install httpd php mod_ssl php-gd php-pdo php-mcrypt sqlite mysql-connector-odbc php-mysql
Extract all the content in "tiqrzend" package under /opt/tiqrzend, and
unarchive phpqrcode in /opt/tiqrzend/library/phpqrcode.
Make /opt/tiqrzend/application/logs writable from your httpd.
If you have "tree" command in your environment, you can check the result like this:
$ tree --charset=ascii -L 2 /opt/tiqrzend/
/opt/tiqrzend/
|-- application
| |-- Bootstrap.php
| |-- configs
| |-- controllers
| |-- layouts
| |-- modules
| `-- views
|-- library
| |-- phpqrcode
| |-- tiqr
| |-- tiqrshib
| |-- tiqr-zf
| |-- zend -> ZendFramework-1.12.9-minimal
| `-- ZendFramework-1.12.9-minimal
|-- public
| |-- images
| |-- index.php
| `-- scripts
|-- resources
| `-- Sample.php
`-- tests
|-- application
|-- library
`-- phpunit.xml
20 directories, 4 files
Copy /opt/tiqrzend/application/configs/application.example.ini to /opt/tiqrzend/application/configs/application.ini.
$ cp /opt/tiqrzend/application/configs/application.example.ini \
/opt/tiqrzend/application/configs/application.ini
Modify the configuration per your system's requirement. Detailed instruction should be included in the file.
At the very least, you probably need to configure the following settings.
- resources.tiqrshib.eppnScope
- resources.tiqr.identifier
resources.tiqrshib.eppnScope must be exactly same
as idp.scope in /opt/shibboleth-idp/conf/idp.propeties.
Also you need to prepare DB for tiqrshib's "SecretStorage".
For evaluation purpose, run the following commands:
$ mkdir -p /opt/tiqrzend/db/
$ sqlite3 /opt/tiqrzend/db/secrets.db
sqlite> CREATE TABLE IF NOT EXISTS tiqrshibsecrets (
...> `id` integer NOT NULL PRIMARY KEY AUTOINCREMENT,
...> `uid` text NOT NULL UNIQUE,
...> `secret` text DEFAULT NULL,
...> `isActive` integer DEFAULT NULL,
...> `loginattempts` integer DEFAULT NULL,
...> `isBlocked` integer DEFAULT NULL);
sqlite> (exit)
$ sudo chown -R apache: /opt/tiqrzend/db
This means all the secrets for enrolled users will be stored in the sqlite3 DB.
Modify /etc/httpd/conf.d/ssl.conf
(or whatever httpd config file you prefer)
so it contain the following settings:
Alias /tiqr/ "/opt/tiqrzend/public/"
<Location /tiqr>
RewriteEngine On
RewriteBase /tiqr
RewriteCond %{REQUEST_FILENAME} -s [OR]
RewriteCond %{REQUEST_FILENAME} -l [OR]
RewriteCond %{REQUEST_FILENAME} -d
RewriteRule ^.*$ - [NC,L]
RewriteRule ^.*$ /tiqr/index.php [NC,L]
require all granted
</Location>
<Location /tiqr/shib/enroll/process>
AuthType shibboleth
ShibRequestSetting requireSession 1
require valid-user
</Location>
Don't forget reloading your httpd's config file.
With the modifications above, tiqr authentication flow should be ready for your evaluation. Try the following "enrollment" and "login" flow.
Visit https://(your host name)/tiqr/shib/enroll,
and check if a QR code is shown to the screen.
Scan the code using Tiqr mobile application, and enter a 4-digit PIN code
which will be used soon later so you must remember.
You should be able to register the service via the mobile app.
This flow is called "enrollment".
After the enrollment, visit https://(your host name)/tiqr/shib/login.
Now you will see another QR code that is for "login" step.
Scan the QR code with the Tiqr mobile app.
You are asked to enter the 4-digit PIN code that you entered
in the previous step.
If you enter the correct PIN, Tiqr mobile app will show
the message "Login is successful".
Note that at this point web interface will show some error message at the last step, which is normal. The tiqrzend's login interface is intended for IdP integration, and without IdP, it cannot correctly redirect back to the IdP. What you should check here is if the redirect happens at this point. If the redirect does not happen and some other problem happens, you will need to trouble-shoot it here.
There are multiple logs to be checked when there are some errors.
- httpd's logs in
/var/log/httpd - PHP's logs in syslog or whatever you configured at
/etc/php.ini - tiqrzend's login
/opt/tiqrzend/application/logs/
Building the IdP extension requires Apache Maven. Note you can build the extension outside where IdP resides, but you need the same Java environment to build the extenion there.
Here is how to install Apache Maven in /opt/ directory.
$ export MVN_VERSION=3.5.0
$ wget http://ftp.riken.jp/net/apache/maven/maven-3/${MVN_VERSION}/binaries/apache-maven-${MVN_VERSION}-bin.tar.gz
$ tar xf apache-maven-${MVN_VERSION}-bin.tar.gz -C /opt/
$ export PATH=/opt/apache-maven-${MVN_VERSION}/bin:$PATH
$ mvn --version
(Check Maven is installed)
Under the "idp/" directory in this project, run the following commands:
$ ls
pom.xml src
$ mvn -DskipTests=false clean package
... (a lot of logs) ...
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 1.683 s
[INFO] Finished at: 2017-09-05T16:41:39+09:00
[INFO] Final Memory: 24M/361M
[INFO] ------------------------------------------------------------------------
$ ls
pom.xml src target
$ ls target/
classes maven-archiver tiqrshibauthn-2.0.jar
Here, tiqrshibauthn-2.0.jar is what we want.
If you are outside the host where IdP resides,
copy the jar file to the server.
From here, we assume you logged in the host where IdP resides as root.
# pwd
/root/shibboleth-identity-provider-3.3.1
Before going forward, we recommend to stop Tomcat.
# systemctl stop tomcat
Place tiqrshibauthn-2.0.jar in IdP installer's
webapp/WEB-INF/lib/ directory.
Configure webapp/WEB-INF/web.xml
so that it contain the following configurations.
<servlet>
<servlet-name>TiqrShibAuthnHandler</servlet-name>
<servlet-class>jp.gakunin.tiqrshib.TiqrShibAuthnServlet</servlet-class>
<load-on-startup>4</load-on-startup>
</servlet>
<servlet-mapping>
<servlet-name>TiqrShibAuthnHandler</servlet-name>
<url-pattern>/Authn/TiqrShib</url-pattern>
</servlet-mapping>
Note: /Authn/TiqrShib is hard-coded in both tiqrzend and the IdP extension. You should not alter it.
Install the modified IdP using bin/install.sh as usual installation.
# bin/install.sh
Depending on your Tomcat configuration,
you may need to copy idp.war in /usr/java/tomcat/webapps/ and
remove idp/ directory there.
# cp -f /opt/shibboleth-idp/war/idp.war /usr/java/tomcat/webapps/
# rm -rf /usr/java/tomcat/webapps/idp
If you choose to run Tomcat under the user "tomcat",
you may also need to review directory permissions in
/opt/shibboleth-idp/ again.
# chown -R tomcat:tomcat /opt/shibboleth-idp/logs
# chgrp -R tomcat /opt/shibboleth-idp/conf
# chmod -R g+r /opt/shibboleth-idp/conf
# find /opt/shibboleth-idp/conf -type d -exec chmod -R g+s {} \;
# chgrp tomcat /opt/shibboleth-idp/metadata
# chmod g+w /opt/shibboleth-idp/metadata
# chmod +t /opt/shibboleth-idp/metadata
Move to /opt/shibboleth-idp/ and modify relevant configuration files.
# cd /opt/shibboleth-idp
Create flows/authn/tiqrshib/ directory and copy some relevante XML files.
Then edit copied files so they become ready for tiqrshib authentication.
You can use the following sequence of sed commands if original XML are untouched:
# mkdir flows/authn/tiqrshib/
# cp system/flows/authn/external-authn-flow.xml flows/authn/tiqrshib/tiqrshib-flow.xml
# sed -i 's/external-authn-beans\.xml/tiqrshib-beans.xml/' flows/authn/tiqrshib/tiqrshib-flow.xml
# cp system/flows/authn/external-authn-beans.xml flows/authn/tiqrshib/tiqrshib-beans.xml
# sed -i 's/external-authn-config\.xml/tiqrshib-authn-config.xml/' flows/authn/tiqrshib/tiqrshib-beans.xml
# cp dist/conf/authn/external-authn-config.xml.dist conf/authn/tiqrshib-authn-config.xml
# sed -i 's/Authn\/External/Authn\/TiqrShib/' conf/authn/tiqrshib-authn-config.xml
Here, all the procedures are case-sensitive. Distinguish between "authn/tiqrshib" and "Authn/TiqrShib".
Add the following XML content in conf/authn/general-authn.xml.
<bean id="authn/tiqrshib" parent="shibboleth.AuthenticationFlow"
p:nonBrowserSupported="false">
<property name="supportedPrincipals">
<list>
<bean parent="shibboleth.SAML2AuthnContextClassRef"
c:classRef="urn:oasis:names:tc:SAML:2.0:ac:classes:MobileTwoFactorUnregistered" />
</list>
</property>
</bean>
You probably want to modify classRef settings,
depending on what authnContext you want to use for the tiqrshib authn.
Modify conf/idp.properties so idp.authn.flows contain "tiqrshib"
idp.authn.flows=Password|tiqrshib
Finally, start Tomcat.
# systemctl start tomcat
If you enable DEBUG log for net.shibboleth.idp namespace, you will see the log like bellow on boot:
Registered flow ID 'authn/tiqrshib' using 'file [/opt/shibboleth-idp/flows/authn/tiqrshib/tiqrshib-flow.xml]'
Now that IdP is ready for Tiqr authentication.
Modify SP so that it requests to the authnContext you specified in general-authn.xml on certain path.
Here's an example of httpd configuration on a Shibboleth SP server, assuming it is already under a same federation with the IdP.
<Location /shibtiqr_protected>
AuthType shibboleth
ShibRequestSetting requireSession 1
ShibRequestSetting authnContextClassRef urn:oasis:names:tc:SAML:2.0:ac:classes:MobileTwoFactorUnregistered
Require valid-user
</Location>
After the instruction above, the server contains several configurations that are suitable only for evaluation. For production use, you should configure settings for more security, availability, etc.
See your application.ini that was copied from application.example.ini, and read descriptions there.
Here we'll describe some most important aspects of possible configurations.
Change secrets shared between tiqrzend and the IdP extention.
On tiqrzend side, modify resources.tiqrshib.encryption.key and
resources.tiqrshib.encryption.iv.
On the extension side, modify AES_KEY and AES_IV in
TiqrShibConstants.java in the IdP extension.
Note that the modification requires recreating jar file and IdP re-installation.
Tiqr mobile application will show users basic information about the Tiqr server. The information is provided from Tiqr server on enrollment process. You probably want to change it before production use.
Check the following three settings.
- resources.tiqr.identifier
- resources.tiqr.name
- resources.tiqr.logoUrl
Consult to the officitial document (https://tiqr.org/tiqr-simplesaml-integration-guide) for more information.
SQLite3 is used for "evaluation" installation, which means all the secret for users will be stored in local storange.
You may want some redundancy or possibly more performance. In that case, consider using MySQL instead of SQLite3. There are descriptions in the example config how to achieve it.
We also recommend you check if you are ok with local files containing session information. Zend and tiqr need some session management, and the default config allows them to rely on local /tmp directory. Because they are temporary (unlike tiqr secret), it is OK.
However, if you want make the server redundant with two logical hosts, for example, it may be worth considering to use Memcached or other DBs like MySQL (again). Consult to the descriptions in the example config for more info.
There are a bunch of other configurations available. Read it through before publishing your tiqr server.
Licences of bundled libraries are as follows.
- Zend framework ... released under New BSD
- Copyright (c) 2005-2014, Zend Technologies USA, Inc. All rights reserved.
- tiqr (and tiqrzend) ... released under New BSD
- Copyright (c) 2010-2011 SURFnet bv http://www.surfnet.nl/en