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 getAuthorizationResponse or asynchronously via a webhook with handleWebhook.

Basic Authorize Example:

String authorizationRequestId = null;
String username = "myuser";
try {
    authorizationRequestId = serviceClient.authorize(username);
} catch(BaseException e) {
    //error handling
}

Adding Context

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

Context Example:

String context = "Access to rear door requested";
String authorizationRequestId = null;
try {
    authorizationRequestId = serviceClient.authorize(username, context);
} catch(BaseException e) {
    //error handling
}

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 as the second argument of the method call.

Factor Quantity Example:

String context = "Two factor policy request";
AuthPolicy authPolicy = new AuthPolicy(2);
String authorizationRequestId = null;
try {
    authorizationRequestId = serviceClient.authorize(username, context, authPolicy);
} catch(BaseException e) {
    //error handling
}

Factor Type Example:

String context = "Knowledge and Inherence factors required policy request";
boolean requireKnowledgeFactor = true;
boolean requireInherenceFactor = true;
boolean requirePossessionFactor = false;
AuthPolicy authPolicy = new AuthPolicy(requireKnowledgeFactor, requireInherenceFactor, requirePossessionFactor);
String authorizationRequestId = null;
try {
    authorizationRequestId = serviceClient.authorize(username, context, authPolicy);
} catch(BaseException e) {
    //error handling
}

Geofence Type Example:

String context = "Taj Mahal Geofence policy request";
List<AuthPolicy.Location> locations = new ArrayList<AuthPolicy.Location>;
double radiusMeters = 175 + 20; // 1/3 the longest side of the building + 20m for GPS error.
double latitudeDegrees = 27.1750;
double longitudeDegrees = 78.0422;
locations.add(new AuthPolicy.Location(radiusMeters, latitudeDegrees, longitudeDegrees);
AuthPolicy authPolicy = new AuthPolicy(locations);
String authorizationRequestId = null;
try {
    authorizationRequestId = serviceClient.authorize(username, context, authPolicy);
} catch(BaseException e) {
    //error handling
}

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 authorization request, you will use the getAuthorizationResponse method and pass the authorization request identifier returned by with the authorize call.

Example:

String authorizationRequestId = null;
String username = "myuser";
AuthResponse authResponse = null;
try {
    authorizationRequestId = serviceClient.authorize(username);
    while (authResponse == null) {
        Thread.sleep(1000L);
        authResponse = serviceClient.getAuthResponse(authorizationRequestId);
        if (authResponse != null) {
            boolean authorized = authResponse.isAuthorized();
            // handle authorization result
        }
    }
} catch(BaseException e) {
    //error handling
}

Starting a User Session

To start the Session, execute the sessionStart method with a username and an optional authorization request ID. An End User Session will show up in the User's Authenticator to allow the user to know they have an existing session. This will allow the User to end the session remotely. Example:

String authorizationRequestId = "b1d05c28-0b18-41e4-94a0-853758eeefc8";
String username = "myuser";
AuthResponse authResponse = null;
try {
    authRequest = serviceClient.sessionStart(username, authorizationRequestId);
} catch(BaseException e) {
   //error handling
}

Ending a User Session

To end the Session, execute the sessionEnd method with a username. This method should be called whenever your Service ends the End User's session. This will be reflected in the End User's Authenticator.

Example:

String username = "myuser";
AuthResponse authResponse = null;
try {
    authRequest = serviceClient.sessionEnd(username);
} catch(BaseException e) {
   //error handling
}

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 Map<String, List<String>> object and pass it with the request body as a string to the handleWebhook method.

Spring Web Request Example:

@RequestMapping(value = "/callback", method = RequestMethod.POST)
@ResponseStatus(value = HttpStatus.OK)
public void callback(WebRequest request, @RequestBody String body) throws Exception {
    logger.info("Callback received");
    Map<String, List<String>> headers = new HashMap<String, List<String>>();
    Iterator<String> headerNames = request.getHeaderNames();
    while (headerNames.hasNext()) {
        String headerName = headerNames.next();
        headers.put(headerName, Arrays.asList(request.getHeaderValues(headerName)));
    }
    try {
        WebhookPackage webhookPackage = serviceClient.handleWebhook(headers, body);
        if (webhookPackage instanceof AuthorizationResponseWebhookPackage) {
            // Start session in your application
            serviceClient.sessionStart(sessionUsernameMap.get(sessionId));
        } else if (webhookPackage instanceof ServiceUserSessionEndWebhookPackage) {
            // End session in your application
        }
    } catch(BaseException e) {
        throw new Exception("Error handling callback", apiException);
    }
}

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.

The getAuthorizationResponse method of the AuthorizationResponseServerSentEventPackage will return the same AuthorizationResponse value as returned by the getAuthResponse 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:

The isAuthorized method of the AuthorizationResponse returns a boolean value representing the response generated by the User.

Service User Hash:

The getServiceUserHash method of the AuthorizationResponse returns a value unique to the Service and User combination. This value will be the identifying value sent in the service user session end webhook should a user session be ended remotely. If isAuthorized returns true and you wish to support remote logout, you will need to associate this value with the session created by the response. It may also be used to ensure that you have not been sent a response for and authorization request from another Service for the same user.

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 one 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 getServiceUserHash method of the ServiceUserSessionWebhook 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. ×