.. _pushprovider: =========================================== Push Provider for KeyIdentity Push Token =========================================== .. image:: images/ki_push_token_overview.svg :width: 90% | 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. 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: :ref:`policy_ki_push_token`. 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. | .. figure:: images/menu_pushprovider.png :width: 60% Access Push Provider Configuration | .. figure:: images/webui_popup_pushprovider_empty.png :width: 60% 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. | .. figure:: images/webui_popup_multiple_push_provider_populated.png :width: 80% Multiple Push Provider configured 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=** * User: This is a comma separated list of usernames or resolver names. Please see :ref:`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. .. index:: PushProvider, PushProviderConfig 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. Configuration details of the DefaultPushProvider -------------------------------------------------- .. index:: DefaultPushProvider The Push Provider configuration itself contains three configuration items: .. code:: { "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:** .. code:: "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:** .. code:: "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:** .. code:: "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. | .. figure:: images/webui_popup_pushprovider_filled_keyidentity.png :width: 80% 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. .. _Testing of the KeyIdentity Push Token: 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). .. _push_test_page: 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`. .. image:: images/auth_pushtoken_get_challenge.png :width: 100% | 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` .. _push_test_api: Test Push via API `````````````````` The testing requires two API calls to: * trigger the push message * check the confirmation of the push message 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: .. code:: { "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. 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.: .. code:: { "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.