Directory Client

Device Management

The Directory Client will interact with Directories for managing Directory Services and Directory Users’ Devices as well as managing the Service Sessions for its Directory Users. The Directory Client can be obtained from the appropriate factories.

Get Linked Devices

The Get Linked Devices method generates a list containing each Device linked to a Directory User. The method takes a Directory User ID as the single argument. The example below provides a loop in order to print all linked devices and their current attributes.

var identifier = "my-permanent-unique-user-identifier";
var devices = directoryClient.GetLinkedDevices(identifier);
for (var device in devices)
{
    Console.WriteLine("  " + device.Id + ":");
    Console.WriteLine("    Name:    " + device.Name);
    Console.WriteLine("    Type:    " + device.Type);
    Console.WriteLine("    Status:  " + device.Status);
    Console.WriteLine("    Created: " + device.Created);
    Console.WriteLine("    Updated: " + device.Updated);
}
String identifier = "my-permanent-unique-user-identifier";
List<Device> devices = directoryClient.getLinkedDevices(identifier);
for (Device device : devices) {
    System.out.println("  " + device.getId() + ":");
    System.out.println("    Name:    " + device.getName());
    System.out.println("    Type:    " + device.getType());
    System.out.println("    Status:  " + device.getStatus());
    System.out.println("    Created: " + device.getCreated());
    System.out.println("    Updated: " + device.getUpdated());
}
identifier = "my-permanent-unique-user-identifier"
devices = directory_client.get_linked_devices(identifier)
for device in devices:
    print("  " + device.id + ":");
    print("    Name:    " + device.name)
    print("    Type:    " + device.type)
    print("    Status:  " + device.status)

Session Management

Get Service Sessions for a User

The Get All Service Sessions method retrieves the Service Sessions for a Directory User. The method takes a Directory User ID as the single argument.

var identifier = "my-permanent-unique-user-identifier"
var sessions = directoryClient.GetAllServiceSessions(identifier)
for (var session in sessions)
{
    Console.WriteLine("  " + session.ServiceId + ":")
    Console.WriteLine("    Name:     " + session.ServiceName)
    Console.WriteLine("    Icon:     " + session.ServiceIcon)
    Console.WriteLine("    Auth Req: " + session.AuthRequest)
    Console.WriteLine("    Created:  " + session.Created)
}
String identifier = "my-permanent-unique-user-identifier";
List<Session> sessions = directoryClient.getAllServiceSessions(identifier);

for (Session session : sessions) {
    System.out.println("  " + session.getServiceId() + ":");
    System.out.println("    Name:     " + session.getServiceName());
    System.out.println("    Icon:     " + session.getServiceIcon());
    System.out.println("    Auth Req: " + session.getAuthRequest());
    System.out.println("    Created:  " + session.getCreated());
}
identifier = "my-permanent-unique-user-identifier"
var sessions = directory_client.get_all_service_sessions(identifier)
for session in sessions:
    print("  " + session.service_id + ":")
    print("    Name:     " + session.service_name)
    print("    Icon:     " + session.service_icon)
    print("    Auth Req: " + session.auth_request)
    print("    Created:  " + session.created)

Ending All Service Sessions for a User

The End All Service Sessions method ends all Service Sessions for a Directory User. The method takes a Directory User ID as the single argument.

Note

To end an individual session, use the Service Client.

var identifier = "my-permanent-unique-user-identifier";
directoryClient.EndAllServiceSessions(identifier);
String identifier = "my-permanent-unique-user-identifier";
directoryClient.endAllServiceSessions(identifier);
identifier = "my-permanent-unique-user-identifier"
directory_client.end_all_service_sessions(identifier)

Service Management

Creating a Service

The Create Service method creates a Service Profile. The method takes five arguments: 1) the Service name, 2) a description, 3) an icon image URL, 4) a webhook callback URL, and 5) the active flag for the Service. The method returns a UUID as the Service ID for all further interactions regarding the Service created.

Example:

var serviceId = client.CreateService(
    "My Unique Service Name",
    "My Service Description",
    URI.create("https://my.com/icon.png"),
    URI.create("https://my.com/launchkey-callback"),
    true
);
UUID serviceId = client.createService(
    "My Unique Service Name",
    "My Service Description",
    URI.create("https://my.com/icon.png"),
    URI.create("https://my.com/launchkey-callback"),
    true
);
service_id = client.create_service(
    "My Unique Service Name",
    description="My Service Description",
    icon="https://my.com/icon.png",
    callback_url="https://my.com/launchkey-callback",
    active=True
)

Get a Service

The Get Service method retrieves a single Service Profile. The method takes the Service ID as the single argument.

Example:

var service = client.GetService(serviceId);
Console.WriteLine("  " + service.Id + ":");
Console.WriteLine("    Name:    " + service.Name);
Console.WriteLine("    Desc:    " + service.Description);
Console.WriteLine("    Icon:    " + service.Icon);
Console.WriteLine("    Created: " + service.CallbackURL);
Console.WriteLine("    Active:  " + service.Active);
Service service = client.getService(serviceId);
System.out.println("  " + service.getId() + ":");
System.out.println("    Name:    " + service.getName());
System.out.println("    Desc:    " + service.getDescription());
System.out.println("    Icon:    " + service.getIcon());
System.out.println("    Created: " + service.getCallbackURL());
System.out.println("    Active:  " + service.isActive());
service = client.get_service(service_id)
print("  " + service.id + ":")
print("    Name:    " + service.name)
print("    Desc:    " + service.description)
print("    Icon:    " + service.icon)
print("    Created: " + service.callback_url)
print("    Active:  " + service.active)

Get All Services

The Get All Services method retrieves a list of all Service Profile items. The method does not takes any arguments.

Example:

var services = client.GetAllServices();
for (var service in services)
{
    Console.WriteLine("  " + service.Id + ":");
    Console.WriteLine("    Name:    " + service.Name);
    Console.WriteLine("    Desc:    " + service.Description);
    Console.WriteLine("    Icon:    " + service.Icon);
    Console.WriteLine("    Created: " + service.CallbackURL);
    Console.WriteLine("    Active:  " + service.Active);
}
List<Service> services = client.getAllServices();
for (Service service : services) {
    System.out.println("  " + service.getId() + ":");
    System.out.println("    Name:    " + service.getName());
    System.out.println("    Desc:    " + service.getDescription());
    System.out.println("    Icon:    " + service.getIcon());
    System.out.println("    Created: " + service.getCallbackURL());
    System.out.println("    Active:  " + service.isActive());
}
services = client.get_all_services()
for service in services:
    print("  " + service.id + ":")
    print("    Name:    " + service.name)
    print("    Desc:    " + service.description)
    print("    Icon:    " + service.icon)
    print("    Created: " + service.callback_url)
    print("    Active:  " + service.active)

Get a List of Services

The Get Services method retrieves a list of specific Service Profile items. The method takes a list of Service IDs the single argument. The example below provides a loop in order to print all items and their current attributes.

Example:

var services = client.GetServices(serviceIds);
for (var service in services)
{
    Console.WriteLine("  " + service.Id + ":");
    Console.WriteLine("    Name:    " + service.Name);
    Console.WriteLine("    Desc:    " + service.Description);
    Console.WriteLine("    Icon:    " + service.Icon);
    Console.WriteLine("    Created: " + service.CallbackURL);
    Console.WriteLine("    Active:  " + service.Active);
}
List<Service> services = client.getServices(serviceIds);
for (Service service : services) {
    System.out.println("  " + service.getId() + ":");
    System.out.println("    Name:    " + service.getName());
    System.out.println("    Desc:    " + service.getDescription());
    System.out.println("    Icon:    " + service.getIcon());
    System.out.println("    Created: " + service.getCallbackURL());
    System.out.println("    Active:  " + service.isActive());
}
services = client.get_services(service_ids)
for service in services:
    print("  " + service.id + ":")
    print("    Name:    " + service.name)
    print("    Desc:    " + service.description)
    print("    Icon:    " + service.icon)
    print("    Created: " + service.callback_url)
    print("    Active:  " + service.active)

Updating a Service

The Update Service Method updates a Service Profile item. The method takes five arguments: 1) the Service ID, 2) the Service name, 3) a description of the Service, 4) an icon image URL, 5) a webhook callback URL, and 6) the active flag for the Service. It does not return a value.

Example:

client.UpdateService(
    serviceId,
    "My Unique Service Name",
    "My Service Description",
    URI.create("https://my.com/icon.png"),
    URI.create("https://my.com/launchkey-callback"),
    true
);
client.updateService(
    serviceId,
    "My Unique Service Name",
    "My Service Description",
    URI.create("https://my.com/icon.png"),
    URI.create("https://my.com/launchkey-callback"),
    true
);
client.update_service(
    service_id,
    name="My Unique Service Name",
    description="My Service Description",
    icon="https://my.com/icon.png",
    callback_url="https://my.com/launchkey-callback",
    active=True
)

Removing a Service

A Service cannot be removed via the LaunchKey API. However, the Service can be set to inactive via the LaunchKey API. The only way to remove a Service is via the Admin Center.

Public Key Management

Add a Public Key

The Add Public Key Method adds a Public Key to a Service Profile. The method takes four arguments: 1) the Service ID, 2) the Public Key, 3) the active flag for the Service, and 4) the date in which the public key will expire. It returns a Key ID tied to all further interactions regarding the Public Key created.

Note

Supplying a null value for the expiration date will prevent the Public Key from expiring.

Example:

var keyId = client.AddServicePublicKey(serviceId, publicKey, false, null);
String keyId = client.addServicePublicKey(serviceId, publicKey, false, null);
key_id = client.add_service_public_key(service_id, public_key, None, False)

Update a Public Key

The Update Service Public Key method updates a Public Key for a Service Profile. The method takes four arguments: 1) the Service ID, 2) the Key ID, 3) the active flag for the Service, and 4) the date in which the public key will expire. It does not return a value.

Example:

client.UpdateServicePublicKey(serviceId, keyId, false, null);
client.updateServicePublicKey(serviceId, keyId, false, null);
client.update_service_public_key(service_id, key_id, expires=None, active=False)

Remove a Public Key

The Remove Service Public Key method removes a Public Key from a Service Profile. The method takes two arguments: 1) the Service ID and 2) the Key ID. It does not return a value.

Note

Every entity must have at least one Public Key. As such, you cannot remove the last Public Key for an entity. However, you can deactivate any Public Key by setting the active flag to false.

Example:

client.RemoveServicePublicKey(serviceId, keyId);
client.removeServicePublicKey(serviceId, KeyId);
client.remove_service_public_key(service_id, key_id)

Policy Management

Creating a Policy Object

A Policy can be based on a number of authorization factors or by requiring individual types of authorization factors. Examples of various scenarios follow.

Require a Number of Authorization Factors:

var policy = new ServicePolicy(2);
ServicePolicy policy = new ServicePolicy(2, false);
from launchkey.entities.service import ServiceSecurityPolicy

policy = ServiceSecurityPolicy(any=2)

Require Specific Authorization Factors (Knowledge and Inherence) and JailBreak protection:

var policy = new ServicePolicy(
        requireKnowledgeFactor: true,
        requireInherenceFactor: true,
        requirePossessionFactor: false,
        jailbreakDetection: true);
boolean requireKnowledgeFactor = true;
boolean requireInherenceFactor = true;
boolean requirePossessionFactor = false;
boolean JailBreakProtectionEnabled = true;
ServicePolicy Policy = new ServicePolicy(
        requireKnowledgeFactor,
        requireInherenceFactor,
        requirePossessionFactor,
        JailBreakProtectionEnabled);
from launchkey.entities.service import ServiceSecurityPolicy

policy = ServiceSecurityPolicy(knowledge=True, inherence=True, possession=False, jailbreak_protection=True);

Add locations to the policy:

var locations = new List<Location> {
    new Location("Portland", 1000.0, 45.522187, -122.676291),
    new Location("Las Vegas", 500.0, 36.120779,  -115.156437)
};
ServicePolicy policy = new ServicePolicy(locations=locations);
ServicePolicy policy = new ServicePolicy();
policy.addLocations(Arrays.asList(
    new ServicePolicy.Location("Portland", 1000.0, 45.522187, -122.676291),
    new ServicePolicy.Location("Las Vegas", 500.0, 36.120779,  -115.156437)
));
from launchkey.entities.service import ServiceSecurityPolicy

policy = ServiceSecurityPolicy();
policy.add_geofence(1000.0, 45.522187, -122.676291, "Portland")
policy.add_geofence(500.0, 36.120779, -115.156437, "Las Vegas")

Add time fences to the policy:

var timeFences = new List<TimeFence> {
    new TimeFence(
        "Weekdays 9-5",
        new List<DayOfWeek> {DayOfWeek.Monday, DayOfWeek.Tuesday, DayOfWeek.Wednesday, DayOfWeek.Thursday, DayOfWeek.Friday},
        9, 0, 17, 0, "America/Los_Angeles"),
    new TimeFence(
        "Weekends 12-4", new List<DayOfWeek> {DayOfWeek.Saturday, DayOfWeek.Sunday},
        12, 0, 16, 0,"America/Los_Angeles")
};
ServicePolicy policy = new ServicePolicy(timeFences=timeFences);
ServicePolicy policy = new ServicePolicy(2, null);
policy.addTimeFences(Arrays.asList(
    new ServicePolicy.TimeFence(
        "Weekdays 9-5",
        Arrays.asList(DAY.MONDAY, DAY.TUESDAY, DAY.WEDNESDAY, DAY.THURSDAY, DAY.FRIDAY),
        9, 0, 17, 0, TimeZone.getTimeZone("America/Los_Angeles")),
    new ServicePolicy.TimeFence(
        "Weekends 12-4", Arrays.asList(DAY.SATURDAY, DAY.SUNDAY),
        12, 0, 16, 0, TimeZone.getTimeZone("America/Los_Angeles")),
));
from datetime import time
from pytz import timezone
from launchkey.entities.service import ServiceSecurityPolicy

policy = ServiceSecurityPolicy();
policy.add_timefence(
        "Weekdays 9-5", time(hour=9), time(hour=17),
        monday=True, tuesday=True, wednesday=True, thursday=True, friday=True,
        tzinfo=timezone("US/Eastern")
policy.add_timefence(
        "Weekends 12-4", time(hour=12), time(hour=16)),
        saturday=True, sunday=True)

Set the Policy

The Set Service Policy method sets the Policy for a Service. The method takes two arguments: 1) the Service ID and 2) the Policy. It does not return a value.

Example:

client.SetServicePolicy(serviceId, policy);
client.setServicePolicy(serviceId, policy);
client.set_service_policy(service_id, policy)

Get the Policy

The Get Service Policy method retrieves the Policy for a Service. The method takes the Service ID as the single argument. It returns the Policy or null (if no Policy exists).

Example:

var policy = client.GetServicePolicy(serviceId);
Console.WriteLine("Required Factors:     " + policy.RequiredFactors);
Console.WriteLine("Inherence Required:   " + policy.RequireInherenceFactor);
Console.WriteLine("Knowledge Required:   " + policy.RequireKnowledgeFactor);
Console.WriteLine("Possession Required:  " + policy.RequirePossessionFactor);
Console.WriteLine("Jailbreak Protection: " + policy.JailbreakDetection);
Console.WriteLine("Geofence Locations:");
for (var location in policy.Locations) {
    Console.WriteLine("  " + location.Name + ":");
    Console.WriteLine("    Latitude:  " + location.Latitude);
    Console.WriteLine("    Longitude: " + location.Longitude);
    Console.WriteLine("    Radius:    " + location.Radius);
}
Console.WriteLine("Time Fences:");
for (var timeFence in policy.TimeFences)
{
    Console.WriteLine("  " + timeFence.Name + ":");
    Console.WriteLine("    Days:  " + timeFence.Days);
    Console.WriteLine("    Start: " + timeFence.StartHour + ":" + timeFence.StartMinute);
    Console.WriteLine("    End:   " + timeFence.EndHour + ":" + timeFence.EndMinute);
    Console.WriteLine("    TZ:    " + timeFence.TimeZone);
}
ServicePolicy policy = client.getServicePolicy(serviceId);
System.out.println("Required Factors:     " + policy.getRequiredFactors());
System.out.println("Inherence Required:   " + policy.isInherenceFactorRequired());
System.out.println("Knowledge Required:   " + policy.isKnowledgeFactorRequired());
System.out.println("Possession Required:  " + policy.isPossessionFactorRequired());
System.out.println("Jailbreak Protection: " + policy.isJailBreakProtectionEnabled());
System.out.println("Geofence Locations:");
for (ServicePolicy.Location location : policy.getLocations()) {
    System.out.println("  " + location.getName() + ":");
    System.out.println("    Latitude:  " + location.getLatitude());
    System.out.println("    Longitude: " + location.getLongitude());
    System.out.println("    Radius:    " + location.getRadius());
}
System.out.println("Time Fences:");
for (ServicePolicy.TimeFence timeFence : policy.getTimeFences()) {
    System.out.println("  " + timeFence.getName() + ":");
    System.out.println("    Days:  " + timeFence.getDays());
    System.out.println("    Start: " + timeFence.getStartHour() + ":" + timeFence.getStartMinute());
    System.out.println("    End:   " + timeFence.getEndHour() + ":" + timeFence.getEndMinute());
    System.out.println("    TZ:    " + timeFence.getTimeZone());
}
policy = client.get_service_policy(service_id)
print("Required Factors:     " + policy.minimum_amount)
print("Inherence Required:   " + ("inherence" in policy.minumum_requirements)
print("Knowledge Required:   " + ("knowledge" in policy.minumum_requirements)
print("Possession Required:  " + ("possession" in policy.minumum_requirements)
print("Jailbreak Protection: " + policy.jailbreak_protection)

print("Geofence Locations:")
for location in policy.geofences:
    print("  " + location.name + ":")
    print("    Latitude:  " + location.latitude)
    print("    Longitude: " + location.longitude)
    print("    Radius:    " + location.radius)

print("Time Fences:")
for timeFence in policy.TimeFences:
    print("  " + timeFence.name + ":")
    print("    Days:  " + timeFence.days)
    print("    Start: " + timeFence.start_time)
    print("    End:   " + timeFence.end_time)
    print("    TZ:    " + timeFence.timezone)

Remove the Policy

The Remove Service Policy method removes the Policy for a Service. The method takes the Service ID as the single argument. It does not return a value.

Example:

client.RemoveServicePolicy(serviceId);
client.removeServicePolicy(serviceId);
client.remove_service_policy(service_id)

Process Webhooks

Webhooks allow a service to reduce its load by not performing polling against an external API. An endpoint must be created to receive the webhook HTTP request and update the Directory 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, the implementation must collect the request headers as a map or dictionary (with the key being a string and the value being a list of strings) and pass it with the request body as a string to the Handle Webhook method.

var context = listener.GetContext();
using (var reader = new StreamReader(context.Request.InputStream, Encoding.UTF8))
{
    var body = reader.ReadToEnd();
    var headers = new Dictionary<string, List<string>>();
    foreach (var headerName in context.Request.Headers.AllKeys)
    {
        headers.Add(headerName, new List<string>());
        foreach (var headerValue in context.Request.Headers.GetValues(headerName))
        {
            headers[headerName].Add(headerValue);
        }
    }
    Var webhookPackage = directoryClient.HandleWebhook(
            headers, body, context.Request.HttpMethod, context.Request.Url.AbsolutePath);
    if (webhookPackage is DirectoryUserDeviceLinkCompletionWebhookPackage)
    {
        // Handle Device link completion webhook
    }
}
// Spring Web Example
@RequestMapping(value = "/webhook/directory", method = RequestMethod.POST)
@ResponseStatus(value = HttpStatus.OK)
public void webhook (WebRequest request, @RequestBody String body) throws BaseException {
    Map<String, List<String>> headers = new HashMap<>();
    Iterator<String> headerNames = request.getHeaderNames();
    while (headerNames.hasNext()) {
        String headerName = headerNames.next();
        headers.put(headerName, Arrays.asList(request.getHeaderValues(headerName)));
    }
    WebhookPackage webhookPackage = directoryClient.handleWebhook(headers, body, "POST", "/webhook");
    if (webhookPackage instanceof DirectoryUserDeviceLinkCompletionWebhookPackage) {
        // Handle Device link completion webhook
    }
}
# Flask example
from flask import Flask, request
from launchkey.entities.directory import DeviceLinkCompletionResponse

app = Flask(__name__)

# Path defined in your Directory Webhook URL value
@app.route('/webhook/directory', methods = ['POST'])
def launchkey_directory_webhook():
    package = directory_client.handle_webhook(request.data, request.headers, request.method, request.path)
    if isinstance(package, DeviceLinkCompletionResponse):
        device_id = package.device_id
        device_public_key = package.device_public_key
        device_public_key_id = package.device_public_key_id
        # Notify app / frontend that the user has finished linking

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. ×