Introduction

The Connector is used to provide an easy way to integrate the Keyp ecosystem into services or applications. Connectors provide custom integration using JWT tokens or bridge to existing protocols like SAML or OpenID Connect or technologies like SSO infrastructures or other IAM products.

User Experience Flow

The following figure illustrates a common user flow of the Keyp process with a browser (to access the service on service provider side) and the Keyp Wallet app (to fetch the identity factors from the identity provider side). The light blue color references the flow on identity provider side. The darker blue color shows the flow on service provider side.

UX Flow
Figure 1. Example user experience flow with browser and Wallet app
  1. Browser starts authentication process by presenting the QR code

  2. QR code is scanned by the Wallet app

  3. QR code will be exchanged by process indicator

  4. Wallet app shows confirmation screen

  5. Confirmation by user

  6. User is authenticated

Architecture

The Keyp ecosystems knows different roles: Identity providers who will provide user related data, the Wallet app which is managed by the user and service providers which consumes these data in a secure way. The following figure illustrates the Keyp ecosystem with all the technical components, which are required to provide the Keyp features. The connector is one of these components and connects to the application services of the service provider.

Components
Figure 2. Keyp ecosystem with components

The connector enables services and applications to leverage the Keyp ecosystem in an easy way and consists of three components:

  1. Core Service

  2. TriggerJS JavaScript library

  3. Optional adapters

The following figure illustrates the deployment architecture, when an application service is using TriggerJS and Core Serives directly

Connector
Figure 3. Connector architecture

The following figure illustrates the deployment architecture, when an application service is using an Adapter. In this case the Keyp ecosystem is completely transparent (hidden) for the application service

Connector with Adapter
Figure 4. Connector architecture with adapter

The core service is responsible to handle the Keyp protocol and workflow transaction. The TriggerJS library provides easy integration into web applications. Besides the direct integration using JWT data tokens, adapters can bridge the gap between the Core Service and the application service by using standard protocols like SAML, OpenID Connect, etc. or an integration into an existing access management solution.

Components

This chapter describes the components of the connector.

TriggerJS

The TriggerJS is a JavaScript Library which can be integrated into application services to start a Keyp transaction. The TriggerJS provides different trigger types for different use cases:

  1. QR Code Trigger (default)

  2. Push Notification Trigger

  3. Mobile Button (for websites on mobile devices)

Code Example

The TriggerJS will be integrated and configured with the following code. TriggerJS will show the QR Code trigger direct on the website and monitor the current state of the transaction. TriggerJS will notify When data is available for the application service.

Integrate TriggerJS into Website
<html>
  <head>
    <script src='/js/triggerjs/keyp.js'></script>
    <link rel="stylesheet" href='/js/triggerjs/keyp.css'></link>
  </head>
  <body>
    <div id="trigger">
      <keyp-trigger
          company-button-label="DEMO APP"
          company-banner-label="VIA KEYP"
          button-color-hex="#000000"
          display="inline"
          polling-interval="500"
          server-domain="https://connector.keyp.io/v1"
          client-id="YOUR_CLIENT_ID"
        >
      </keyp-trigger>
    </div>

    ...

    <script>

    (function () {
      var keypButton = document.querySelector('keyp-trigger');
      keypButton.addEventListener('onReadyToFetchData', function (response) {
        // data is now available
        // notify backend to fetch data from core service
        // ...
      })
    })

    </script>
  </body>
</html>

Core Service

The Core Service manages the transaction workflow and translates the data from the Keyp ecosystem into an application friendly JWT data token.

API Documentation

The API documentation is available here (Swagger UI)

Code Example

If data is ready to consume, TriggerJS will notify the application service. The data can then be fetched by the application service in the backend (server to server communication).

Exampe Request
POST /v1/data
Host: connector.keyp.io
Authorization: Basic Y2xpZW50X2lkOmNsaWVudF9zZWNyZXQ=
Content-Type: application/x-www-form-urlencoded

type=session&session=Dd230y1s8QdBlV6MfagSQaKcGIOCXQWJ
Example Response
eyJ0eXAiOiJKV1QiLCJhbGciOiJFUzI1NiIsIng1dSI6Imh0dHBzOi8vY29ubmVjdG9yLmtleXAuaW8vdjEvY2VydCJ9.eyJpYXQiOjE1MzIyODQ2ODUsImV4cCI6MTUzMjI4NDc0NSwiZGF0YSI6eyJjb20uZXhhbXBsZS5rZXlwbGV0Lm1haWwiOnsiZW1haWwiOiJqYW5lLmRvZUBleGFtcGxlLmNvbSJ9LCJjb20uZXhhbXBsZS5rZXlwbGV0Lm5hbWVzIjp7ImdpdmVuTmFtZSI6IkphbmUiLCJzdXJOYW1lIjoiRG9lIiwiY24iOiJKYW5lIERvZSJ9fX0.N1dsa6M_Fc7HatAUHq6Ql6BcuH__O_IUyLEETLXYBrCEv6eOGwzy0WETu9S_rFewTI2ZayRMSBcC0mSvSb3RBA

This JWT data token can be easily validated and contains the user data from the Keyp workflow as claims in the JWT payload.

Decoded JWT payload
{
  "iat": 1532284685,
  "exp": 1532284745,
  "data": {
    "com.example.keyplet.mail": {
      "email": "jane.doe@example.com"
    },
    "com.example.keyplet.names": {
      "givenName": "Jane",
      "surName": "Doe",
      "cn": "Jane Doe"
    }
  }
}

More information about the JWT flow including a sequence diagram is available here

Adapters

Adapters provide an easy way to integrate the Keyp ecosystem into existing services without coding.

Federation Adapters:

Service Adapters:

  • AWS Adapter

  • Box Adapter

  • Dropbox Adapter

  • Evernote Adapter

  • Google Adapter

  • Office365 Adapter

  • Salesforce Adapter

  • Slack Adapter

  • WebEx Adapter

  • Zendesk Adapter

WAM Adapters:

  • OpenAM Adapter

  • PingFederate Adapter (→ read more)

  • SiteMinder Adapter

Custom Adapters:

  • Age Verification Adapter

Example Flow

Connector authentication flow

UX Flow

  1. Create transaction

  2. Get trigger (load QR code)

  3. Read workflow configuration

  4. Read transaction state

  5. Provide access token (signed identity factors)

  6. Read transaction state

  7. Fetch data

Connector authentication flow with adapter

Dynamic view

  1. Authentication request is send to the adapter (from where and how depends on the integration scenario)

  2. Adapter creates a new transaction at the Keyp Core Module, initiates a trigger (e.g. QR code) and start polling the transaction state (e.g. every second)

  3. Adapter shows the QR code to the user (e.g. in the browser)

  4. User scans QR code with Keyp Wallet app on this smartphone

  5. Wallet app loads workflow configuration and shows required authentication apps to the user

  6. Adapter receives a new transaction state (pending)

  7. Adapter replaces the QR code with process indicator image (e.g. spinner)

  8. User authenticates to receive identity factors and store them in the Wallet app

  9. After user confirms the transaction, the wallet sends signed identity factors to the Keyp Core Module

  10. Keyp Core Module validates signed identity factors

  11. Adapter receives a new transaction state (done) and fetches the identity factors

  12. Adapter authenticates user by using the provided identity factors

Getting started

Core Service

The Core Service is available as a docker container. It requires a SQL database for storing transaction data. Detailed information about installation and configuration is available in the Core Service operation manual.

TriggerJS

The TriggerJS library can be installed in an application service using npm.

Adapters

The Adapters are available as docker containers. Detailed information about installation and configuration is available in the corresponding adapter operation manual.