simplesamlphp / simplesamlphp-module-yubikey
A SimpleSAMLphp module that adds support for YubiKey devices.
Installs: 956
Dependents: 0
Suggesters: 0
Security: 0
Stars: 5
Watchers: 6
Forks: 2
Open Issues: 1
Type:simplesamlphp-module
Requires
- php: >=7.4 || ^8.0
- enygma/yubikey: ^3.3
- simplesamlphp/composer-module-installer: ^1.3.2
- simplesamlphp/simplesamlphp: ^2.0.0-rc2
Requires (Dev)
This package is auto-updated.
Last update: 2024-10-26 17:56:03 UTC
README
This is a SimpleSAMLphp module to leverage YubiKey devices to authenticate users in different ways. For the moment, it provides an authentication processing filter that allows you to require a user to use a YubiKey to complete authentication, effectively implementing two-factor authentication. This filter can be combined with any other authentication source, provided that the identifier (or identifiers) of the key registered for that user is available as an attribute.
Installation
Once you have installed SimpleSAMLphp, installing this module is very simple. Just execute the following command in the root of your SimpleSAMLphp installation:
vendor/bin/composer require simplesamlphp/simplesamlphp-module-yubikey
Then, you need to do is to enable the Yubikey module: in
config.php
, search for the module.enable
key and set yubikey
to true:
'module.enable' => [ 'yubikey' => true, … ],
OTP authentication processing filter
This filter allows you to ask for YubiKey authentication before proceeding further. As any other processing filter, it can be configured either in the general configuration, in the authsources, in the hosted IdP metadata or in the remote SP metadata. See documentation.
You can configure the filter by adding an authproc filter with the class
yubikey:OTP
. At the very least, you will need an API client identifier and an
API key. By default, the filter will let you use YubiCloud, which
will require you to register to obtain a client identifier and an
API key.
If you would like to run the YubiKey validation server yourself (i.e. the server running the API), you can also do it(you can also do it). In that case, you will need to configure the hostname of your validation server instead of the default addresses.
Here are all the options available:
API configuration options
api_client_id
: The client identifier to present to the API. This option is mandatory.api_key
: The key that grants you access to the YubiKey API. This option is mandatory.api_hosts
: An array containing the hosts where the API can be contacted to authenticate a given YubiKey. Please note that all hosts will be queried, and all the responses must be successful in order to consider the authentication of a device to be successful. Therefore, if you want to use your own API with high availability, you should only specify one hostname here and configure a high availability setup for that hostname. This is optional and defaults to Yubico's public API servers, those being:api.yubico.com
Operational configuration options
abort_if_missing
: A boolean value telling whether the whole login process should be aborted if the user has no YubiKey devices registered (set totrue
) or continue, skipping YubiKey authentication (set tofalse
). Optional. Defaults tofalse
.key_id_attribute
: This is the name of an attribute that holds one or more YubiKey device identifiers that are known and accepted for the user. Optional. Defaults toyubikey
.
Assurance configuration options
assurance_attribute
: This is the name of an attribute that we will use to indicate that a successful authentication with the YubiKey device was performed (only when authentication was successful, of course). Optional. Defaults toeduPersonAssurance
.assurance_value
: This is the value that we will add to the attribute specified byassurance_attribute
. Optional. Defaults toOTP
.