# Installation
Manually install this as any other iTop extension.

When installed, users will be able to change their two secret key from iTop's web portal or in iTop's backend preferences.

# Configuration

In the iTop configuration file (config-itop.php), :

```
'jb-login-authenticator' => array(
	'default_issuer' => 'iTop Platform', // Set the name of the issuer (normally the name of the company or application)
	'trusted_networks' => array(), // List of trusted networks (IPv4 and IPv6 are both supported) - example: array('10.6.0.0/16', '2a01:fe8:95::/48')
	'trusted_networks_accept_forwarded_ip' => false, // Whether or not to accept forwarded IP addresses. Useful if behind a firewall, proxy, CloudFlare, ...
	'trusted_browser_duration_days' => 0, // How long the browser fingerprints will be accepted (they will be cleaned up automatically afterwards). Set to 0 to disable.
	'trace_log' => false, // Unless explicitly told to temporarily enable for troubleshooting: keep disabled.
),

```

## Trusted networks


⚠️ Note that this makes the authentication process less secure. Evaluate whether or not to take the risk that an attacker spoofs an IP address.  
It's recommended to use the trusted networks feature only for clients which can directly connect to the internal web server.  
So the recommended value for `trusted_networks_accept_forwarded_ip` is `false`.

If a user signs in with an IP which is listed in the **trusted_networks** setting, multi factor authentication is not needed.

The trusted networks feature was sponsored by [PC-Notdienst](https://www.pc-notdienst.com/).  


## Trusted browsers

⚠️ Note that this makes the authentication process less secure. 

You can specify for how many days the brower is trusted using this setting: `trusted_browser_duration_days`.
The feature is only enabled if the number is higher than 0.

When enabled, on the login screen the user will see a checkbox to optionally mark his browser as trusted.  
The OTP field and checkbox to mark as a trusted browser will always be visible at first; this is done by design.  
Upon entering the user name, those fields will be hidden. 

The browser checks if the fingerprint has already expired, after which the OTP code will be required again and the checkbox to trust the browser will be visible again.  
This is double checked by the server, which will redirect to the login screen and delete the fingerprint if it's no longer accepted in the backend.



# Enforcing two factor

Due to the way iTop works, the setting is not linked to the actual user, but to the **person** linked to a user account.

There, a new option is available to enforce the user to configure a two factor secret.
![Enforce two factor authentication](screenshots/20210305_person.png)

# Screenshots

The user can directly enter the two factor code when authenticating to iTop using classic credentials.
![Login form - user can enter two factor code](screenshots/20210305_login.png)

If it's the first time and two factor authentication has been enforced in the backend, the user will have to set up a two factor code.
![Initial set up](screenshots/20210305_first_setup_when_enforced.png)

The secret can be updated by the user (once authenticated) in the console (classic backend)
![Backend preferences](screenshots/20210305_console_preferences.png)

The secret can be updated by the user (once authenticated) in the portal (modern frontend)
![Portal preferences](screenshots/20210305_portal_preferences.png)

In the current concept (this can become more strict upon development requests!),  
people with access to the person object can configure two factor authentication to be enforced.
![Enforce two factor authentication](screenshots/20210305_person.png)

# FAQ

## Reset password

Users with modify rights on Person objects, have the option to reset the MFA secret. There's a menu item under "Other actions".

If you don't have access to iTop, you can run this query:
```
SELECT * FROM authenticationmethod AS am
WHERE 
	am.user_id IN (SELECT u.id FROM priv_user AS u WHERE u.login LIKE 'accountname') AND 
	am.authentication_method = 'two_factor_secret'
```

## User can't sign in

Check https://time.is on the user's authentication device.  
The time should be exact, down to the second.  
By default a tolerance of 30 seconds difference compared to the actual time is allowed.  


## Disabling the extension

Either remove the extension and re-run the setup.  
Or to temporarily disable all functionality, add 0.0.0.0/0 as trusted network.