Service Client

The Service Client will interact with Services for interacting with authorizations and sessions. The service can be obtained from the appropriate factories.

Authorize a Transaction

The authorization process begins with an authorize call. In its most basic implementation, an End User Username is all that is provided. It will return the ID for this authorization request. This ID will be used to determine the End User's response via polling with get_authorization_response or asynchronously via a webhook with handle_webhook.

Basic Authorize Example:

from launchkey.exceptions import EntityNotFound, RateLimited
user = "my_unique_internal_identifier"
try:
    authorization_request_id = service_client.authorize(user)
except EntityNotFound:
    # The input username was not valid, so tell the user to try another one
except RateLimited:
    # Too many auth attempts are being made for a user so the LaunchKey API is rate limiting you

Adding Context

Context can be added to the authorize call by passing a context parameter. The context allows the user to have confidence that they are approving the correct request.

Context Example:

context = "Access to rear door requested";
authorization_request_id = service_client.authorize(username, context=context)

Add Dynamic Policies

Authorization policies can be set statically on the Dashboard. They can also be passed dynamically with the authorize call. The policy an be submitted by passing a policy parameter using the AuthPolicy class.

Factor Quantity Example:

from launchkey.clients.service import AuthPolicy
context = "Two factor policy request"
auth_policy = AuthPolicy(any=2)
authorization_request_id = service_client.authorize(username, context=context, policy=policy)

Factor Type Example:

context = "Knowledge and Inherence factors required policy request"
required_knowledge_factor = True
required_inherence_factor = True
required_possession_factor = False
auth_policy = AuthPolicy(knowledge=required_knowledge_factor, inherence=required_inherence_factor,
                         possession=required_possession_factor);
authorization_request_id = service_client.authorize(username, context=context, policy=policy)

Geofence Type Example:

context = "Taj Mahal Geofence policy request"
radius_meters = 175 + 20; #  1/3 the longest side of the building + 20m for GPS error.
latitude_degrees = 27.1750;
longitude_degrees = 78.0422;
auth_policy = AuthPolicy()
auth_policy.add_geofence(latitude=latitude_degrees, longitude=longitude_degrees, radius=radius_meters)
authorization_request_id = service_client.authorize(username, context=context, policy=policy)

Fetching the End User's Response

Warning

Although the functionality exists to fetch for a response, Webhooks are the preferred method for completing a Login or Authorization request. If your implementation is not externally available or cannot receive HTTP requests, you may need to resort to polling.

To poll for the status of an existing auth request, you will use the get_authorization_response method and pass the authorization request identifier returned by with the authorize call.

Example:

from launchkey.exceptions import RequestTimedOut
from time import sleep
user = "my_unique_internal_identifier"
authorization_request_id = service_client.authorize(user, context=context)
response = None
try:
    while response is None:
        sleep(1)
        response = service_client.get_authorization_response(authorization_request_id)
        if response is not None:
            if response.authorized is True:
                # User logged in
            else:
                # User denied the auth request
except RequestTimedOut:
    # The user did not respond to the request in the timeout period (5 minutes)

Starting a User Session

To start the Session, execute the session_start method with a user name and the authorization request ID. Example:

authorization_request_id = "b1d05c28-0b18-41e4-94a0-853758eeefc8"
user = "my_unique_internal_identifier"
auth_request = service_client.session_start(user, authorization_request_id)

Ending a User Session

To end the Session, execute the session_end method with a user name. Example:

user = "my_unique_internal_identifier"
authRequest = service_client.session_end(user)

Process Webhooks

Webhooks allow your service to reduce its load by not performing polling against an external API. You must create an endpoint to receive the webhook HTTP request and update your service configuration accordingly. Here is a link to the setup instructions: Webhooks.

Webhooks are HTTP POST requests utilizing a JSON Web Token (JWT) for authorization and validation and a JSON Web Encrypted payload. To process a webhook, collect the request headers as a dictionary like object and pass it with the request body as a string to the handle_webhook method. Flask Example:

from flask import request
from launchkey.clients.service import AuthorizationResponse, SessionEndRequest
package = client.handle_webhook(request.data, request.headers)
if isinstance(package, AuthorizationResponse):
    if package.authorized is True:
        # User accepted the auth, now create a session
        client.session_start(user, auth_request_id)
    else:
        # User denied the auth
elif isinstance(package, SessionEndRequest):
    # The package will have the user hash, so use it to log the user out based on however you are handling it

Authorization Response Webhook

The authorization response webhook contains information necessary to complete the authorization request as well as respond to a service user session end webhook.

handle_webhook will return the same AuthorizationResponse value as returned by the get_authorization_response call.

authorization_request_id:

The unique identifier for the authorization request. It is required that you have a way for the callback handler to alert your internal authentication mechanism of the response from the user based on this value.

authorized:

boolean value representing the response generated by the User.

service_user_hash:

Unique identifier in relation to Service and User combination. This value will be the identifying value sent in the service user session end webhook a user session be ended remotely. If authorized returns true and you wish to support remote logout, you will need to associate this value with the session created by the response.

organization_user_hash:

The getOrganizationUserHash method of the AuthorizationResponse returns a value unique to the Organization and User combination. This value may be used to ensure that you have not been sent a response for and authorization request from another Organization for the same user.

user_push_id:

The getUserPushId method of the AuthorizationResponse returns a value unique to the Service and User combination. This value can be used in place of a username in all communication in which a username is required. Using this value rather than the user name can improve security by not storing a value that is valid across Services, Directories, and Organizations. If the user push ID were to be obtained by an attacker, the only Service the attacker could use this against would be the service for which it was generated.

device_id:

The getDeviceId method of the AuthorizationResponse returns a value unique to the user that identifies the device used to response to the authorization request.

service_pins:

The getServicePins method of the AuthorizationResponse returns a FIFO buffer as a list of strings which are unique to the Service and Device. This list can aid in detecting device cloning. Over time, the original device and the cloned device will no longer contain any of the same values in the list they return in the authorization response.

Warning

Service PINs are an advanced feature that have the possibility of generating false negatives when a valid device loses synchronization with your application. If you use Service PINs to detect device cloning, you will need to provide a way to re-synchronize the user's device.

Service User Session End Webhook

If a User ends on or all of their sessions from a linked Device or the Dashboard or a directory requests all sessions for a user to be ended, the service user session end webhook will be triggered. Getting the service user hash from the service_user_hash attribute of the AuthorizationResponse class allows you to identify the session(s) within your implementation that were initiated by a particular User. Use that value to end the session in your system.

User Contributed

LaunchKey links to user contributed code as a resource to its community. LaunchKey does not in any way guarantee or warrant the quality and security of these code bases. User contributed code is supported by the creators. If you do find a link from the site to user contributed code that is malicious or inappropriate in any way, please report that link to LaunchKey immediately and we will investigate the claim. Submit any issue to LaunchKey support at https://launchkey.com./support. ×