11. Push Provider for KeyIdentity Push Token

Starting with LinOTP 2.10 the Keyidentity Push Token v2 has been implemented which can be used to secure logins and transactions. The token is paired during the rollout procedure with the KeyIdentity APP (available for Android and iOS) at the smart phone of the user. For authentication the user initiates the login (e.g. with the user name and the password). The login procedure sends the authentication request to the LinOTP server. LinOTP contacts the dedicated Challenge Service (made available to customers of KeyIdentity) which in turn generates and sends a push messages to the user’s mobile. The user approves (or denys) the action in the APP. The result is sent back to the challenge service server. LinOTP checks the result and tells the login program whether the login is allowed or not.

Besides the very convenient work flow for the user (no OTP must be entered, just confirm action via APP) the approval by the user is exactly for the displayed login (or transaction) and can only be used for this purpose. Traditional OTPs are universal - any can be used for any kind of login which makes them potentially vulnerable (e.g. an attacker getting hands on an event based token for a short moment can pregenerate a number of OTPs which can be used for any 2FA secured login procedure of this user+token).

The KeyIdentity Push Token is fully supported by the KeyIdentity Authentication Provider (KAP).

Note

The Challenge Service server must provide a web server certificate accepted by the mobile the KeyIdentity Authenticator App is running at. So please make sure the certificate is signed by a trusted certificate authority.

Note

The use of the Challenge Service is permitted by a corresponding support contract. Please contact support@keyidentity.com for help and more detailed documentation, KeyIdentity GmbH provides the required infrastructure for the Push Token to their customers.

11.1. Configuration

For using the KeyIdentity Push Token at least one “Push Token Provider” must be configured and policies have to be set accordingly as described in: KeyIdentity Push Token Policies.

The Push Token Provider configuration can be found at the token management GUI (https://LINOTPSERVER/manage) “LinOTP Config” –> “Provider Config” –> “Push Provider Config” where the Providers can be created, edited and deleted.

Access Push Provider Configuration

Create a new Push Provider

Set up as many Push Providers as required. Which one will be used can be configured by policies. If no policy exists or no existing policy applies the Push Provider marked as “(Default)” will be used.

Multiple Push Provider configured

11.1.1. Policy to Choose Push Provider

Different Push Provider can be used depending on username, realm or client.

• Policy name: This is a unique name of the policy.

• Scope: authentication.

• Action: push_provider=<CONFIGURED_PROVIDER_NAME>

• User: This is a comma separated list of usernames or resolver names. Please see Users in policies. * Realm: Enter the name of the realm.

• Client: This is a list of IP addresses or subnets this policy is valid for.

11.1.2. Configure Push Provider

A Push Provider is a LinOTP module, that defines how the push messages are transmitted to the user’s phone.

Note

Push Token Provider, mobile APP (available for Android and iOS) as well as a compatible extension for the Windows login procedure (KAP) are provided by the KeyIdentity GmbH.

These four values can be configured in the server configuration:

Name

Name of the Push Provider as to be used in the policies.

Class

The Push Provider module to be used for sending messages. At the moment LinOTP comes with one Push Provider class: DefaultPushProvider

Config

The configuration parameter for the Push Provider Class.

Timeout

This configuration key holds the time the challenge that was pushed to the user’s phone is valid. The number is interpreted in seconds. The default value is 120 i.e. 2 minutes. That means that after a confirmation message was sent a user will be able to approve this message within the next 2 minutes. If the push message arrives later or the user has not confirmed the login/transaction within 2 minutes, the challenge is not valid anymore.

11.1.2.1. Configuration details of the DefaultPushProvider

The Push Provider configuration itself contains three configuration items:

{
"push_url": "[
               https://CHALLENGE-SERVICE_1_FQDN/v1/challenge",
               https://CHALLENGE-SERVICE_2_FQDN/v1/challenge"
             ]
"access_certificate": "FULLPATH_TO_CLIENT_CERTIFICATE",
"server_certificate": "FULLPATH_TO_CHALLENGE-SERVICE_SERVER_CERTIFICATE"
}

push_url

holds the link to the API of the Challenge Service servers.

Example:

"push_url": "[
               https://challenge-service1.example.com/v1/challenge",
               https://challenge-service2.example.com/v1/challenge"
             ]"

access_certificate (optional)

points to the client certificate used to authenticate against the Challenge Service server. This certificate is only required if the challenge server has been configured accordingly.

Example:

"access_certificate": "/etc/linotp2/cs_client.key"

server_certificate (optional)

points to the server certificate (or certificate chain) of the Challenge Service server in order to ensure encrypted communication with the correct server. This is only required if the certificate of the challenge server can not be validated with the CA-chains in the operating system SSL store.

Example:

"server_certificate": "/etc/linotp2/cs-ca-cert.pem"

Tip

If a new Push Provider is created it the configuration parameters are prefilled with the required data to connect to the PNP server provided by KeyIdentity GmbH.

Complete Push Provider Configuration

Note

The LinOTP server must provide a web server certificate accepted by the mobile the KeyIdentity Authenticator App is running at. So please make sure the certificate is signed by a trusted certificate authority.

11.2. Testing of the KeyIdentity Push Token

After the rollout and the successful activation of the token the authentication procedure can be tested.

There are two ways for testing: via test page (LinOTP 2.10+) or API.

The KeyIdentity Push Token is a challenge response token. The push message is triggered depending on the LinOTP configuration using the user’s name and the token PIN (which can be the user’s password if otppin=1 policy is in place).

11.2.1. Push Token via Test Page

As of LinOTP 2.10 a test page is available:

https://LINOTP/auth/pushtoken

Enter username[@realmname] and OTP PIN (the PIN depends on the otppin policy, realmname is necessary for users in non-default realm) and press get challenge.

The push message should be received correctly by the user’s mobile. After the user confirmed the transaction the result can be checked via check status

11.2.2. Test Push via API

The testing requires two API calls to:

• trigger the push message

• check the confirmation of the push message

11.2.2.1. Trigger the Push Messages

The generic API call is:

https://LINOTP/validate/check?user=USERNAME[@REALM]&pass=TOKENPIN&data=TRANSACTIONDATA&content_type=0

Parameters:

LINOTP - The IP or FQDN of the LinOTP server, e.g.

https://linotp.example.net

user - The user’s name, can be USER@REALM if the user is not member of the

default realm

pass - The token PIN, depending on the configured otppin policy this can be either:

• PIN of the token (otppin=0 / default behavior)

• Password of the user (otppin=1)

• empty (otppin=2)

data - The data of the transaction, e.g. details on the login

content_type - Needs to be 0 to trigger the challenge

This is an example with actual values:

https://linotp.example.net/validate/check?user=tux&pass=tHisIsthesECRetToKENPIN&data=Login to dc1.example.net&content_type=0

The LinOTP server returns the transaction details in case of a successful creation of the challenge. This contains the serial number of the token and the transactionid:

{
  "detail": {
     "linotp_tokenserial": "KIPT00031EDC",
     "transactionid": "353846450659",
     "message": "",
     "linotp_tokentype": "push"
  },
  "version": "LinOTP 2.9.1.3",
  "jsonrpc": "2.0802",
  "result": {
     "status": true,
     "value": false
  },
  "id": 0
}

The transaction should now be displayed in the KeyIdentity Authenticator App and be approved there by the user. The mobile communicates the result of the user’s decision back to the LinOTP server.

11.2.2.2. Check Result

The generic API call to fetch the result from the LinOTP server looks like this:

https://LINOTP/validate/check_status?user=USER&pass=OTPPIN&transactionid=TRANSACTIONID

Parameters:

LINOTP - The IP or FQDN of the LinOTP server, e.g.

https://linotp.example.net

user - The user’s name, can be USER@REALM if the user is not member of the

default realm

pass - The token PIN, depending on the configured otppin policy this can be either:

• PIN of the token (otppin=0 / default behavior)

• Password of the user (otppin=1)

• empty (otppin=2)

transactionid - The transactionid as displayed in the return page of the

above push API call.

This is an example with actual values:

https://linotp.example.net/validate/check_status?user=tux&pass=tHisIsthesECRetToKENPIN&transactionid=353846450659

In return the status of the transaction is received.:

{   "detail": {
     "transactions"353846450659": {
        "": {
           "status": "open",
           "token": {
              "serial": "KIPT00031EDC",
              "type": "push"
           },
           "received_tan": true,
           "message": "",
           "received_count": 1,
           "valid_tan": true
        }
     }
  },
  "version": "LinOTP 2.9.1.3",
  "jsonrpc": "2.0802",
  "result": {
     "status": true,
     "value": true
  },
  "id": 0
}

In the output the “valid_tan”: true indicates that the transaction has been approved by the user.