Overview

Keyp’s core technology is an authentication infrastructure: an identity platform combining decentralized architecture with a market place approach to ensure data sovereignty (users) & market efficiency (companies) leading to an agile and secure authentication ecosystem while providing a convenient one-click user experience.

The infrastructure connects three main players: (1) companies providing a service that is secured by (2) authentication apps which are used by (3) users on their Keyp Wallet.

Service Provider

Service providers install an existing Keyp Connector or use Keyp’s SDK to develop one for their dedicated services. Then they configure an authentication workflow for their service by chaining authentication apps available on the marketplace with Keyp’s Workflow Manager. The resulting workflow configuration is then published to the Keyp connector.

Identity Provider (Keyplet)

Keyplets gather information (identity attributes) through widgets running on the Keyp Wallet which sends it to the Keyplet server where the attributes are verified and signed. The resulting identity factors are sent back to the wallet where they are stored.

Keyp Wallet

When a user wants to log into the service they use the Keyp Wallet Android/iOS app to consume an authentication trigger, e.g. scan a QR code or NFC token. The wallet app downloads the workflow configuration from the service and displays all included Keyplets. After all required identity factors are available they are sent to the service where the Keyp Connector validates the correctness of all factors and in case the validation is successful authenticates the user for the service.

Example

Simplified Keyp infrastructure
Figure 1. Keyp infrastructure overview

Transaction with a workflow containing two simple Keyplets: verified email and GPS location.

  1. User scans QR code

  2. Wallet requests the workflow configuration from the service

  3. Service returns configuration

  4. Wallet request Keyplet widget based on configuration

  5. Keyplet returns widget

  6. Wallet requests identity attribute (e.g. email or location) from user through widget

  7. User enters information / widget records it from sensors

  8. Wallet sends attribute to Keyplet server

  9. Keyplet server applies business logic, verifies attribute and returns identity factor

  10. Wallets stores and sends all requested factors to service / connector

  11. Connector validates factors, authenticates user and displays secured content to user

Whenever an identity attribute and the according identity factor already exist steps 3 - 6 may be skipped and users do not need to interact anymore

Simplified transaction

The following sequence diagram visualizes a simplified authentication and all the involved entities. It should be helpful - especially for (future) Keyplet and Keyp Connector developers - when trying to get an idea of the requirements for Keyplets or Connectors.

full transaction
Figure 2. Interaction diagram

Develop a Keyplet - become an identity provider

Implementing your authentication solution as a Keyplet includes two parts: server and client. The server is called Keyplet server while the client is referred to as Keyplet widget.

The first part is setting up the Keyplet server. The Keyplet SDK helps you spin up the main server which handles all necessary requests and takes care of the included cryptography. You may easily extend this server with your own code in order to reflect your business logic.

The second part is the Keyplet widget which is rendered and displayed by the Keyp Wallet. The Keyplet SDK provides tools for developing widgets, too. It simplifies the interaction between wallet and widget and comes bundled with a set of UI/UX best practices which help you to develop a neat user experience.

Connect your product/service with Keyp

In order to connect your service or product to the Keyp infrastructure you either install one of the existing Keyp connectors or you develop a connector yourself.

The main tasks of a connector are

  • responding with a (customized) workflow configuration whenever a wallet asks for it

  • validating the identity factors received from a wallet at the end of a transaction

  • and passing the identity attributes included in the received factors on to the connected service

Glossary

Identity Factor Federation

Keyp offers federated Identity Factors that are created and stored decentrally. Identity Factors are Identity Attributes verified by Keyplets (identity provider) like e.g. an email address, a driver’s license or a company position. Identity Factors may be reused with all [Service Provider]s being part of the federation thus enabling an SSO experience for Identity Owners. Keyp’s Identity Factor Federation platform differs from existing identity federations in a way that Identity Factors

This means [Service Provider]s participating in the Identity Factor Federation gain flexible access to trust-worthy identities while respecting users' privacy.

Identity Attribute

Claim, identity information

Characteristic or property of an Identity Owner. This may be something like an address, a phone number, a membership card, etc. Attributes always have a name, are usually typed and may have a value. In general, they are used to describe the state of an Identity Owner. Identity Attributes are defined by Keyplets and [Keyplet Widget]s are used to fill in the values. Those are send to the related [Keyplet Server]s, validated, verified and finally returned in the form of Identity Factors to the Identity Owner's Wallet.

Identity Factor

Badge, assertion

Identity Attribute verified, i.e. signed, by an Keyplet. After receiving the Identity Attributes formed by the [Keyplet Widget] the [Keyplet Server] validates and if the validation is successful signs the attribute with the Keyplet's private key. Thus, [Service Provider]s can easily check whether an Identity Factor was generated by the correct Keyplet. As long as their validity period is not exceeded Identity Factors may be reused in multiple Workflows. If this is the case, Identity Owners have a real SSO experience as no more interaction is necessary for logging into different services as long as the Identity Attributes required by the different Workflows match.

Identity Owner

User, device

Owner of Identity Attributes. Keep Identity Factors in their Wallets. Whenever Identity Owners access a service through a Workflow they can either use existing Identity Factors given that they are still valid and fit the required factors from the Workflow. Or they simply create new Identity Factors through the Keyplets specified in the Workflow by entering the defined Identity Attributes. Identity Owners benefit from the implicit SSO feature offered by Keyp which enables one-click logins while keeping data stored decentrally on terminals.

Keyplet

Authentication App, Identity Provider

Software that validates and signs Identity Attributes and generates Identity Factors. Keyplets may be developed by anyone. Just like apps on the PlayStore or the AppStore. After they are submitted to the Keyp Marketplace they are reviewed, licensed and certified in order to assert basic trust. In case the review process succeeds the apps are published and available to all [Service Provider]s which may from then on include them in their Workflows. All Keyplets provide a frontend called [Keyplet Widget] which submits Identity Attributes to a backend called [Keyplet Server]. There the verification of the attributes takes place and the Identity Factors are generated. While [Keyplet Server]s may run on practically any machine with an internet connection [Keyplet Widget]s are always executed inside a Wallet where Identity Owners can access them. Each Keyplet defines configurable options in the [Keyplet Manifest]. The [Login Manager] uses those definitions to display standardized input elements.

Wallet

Android/iOS App, Browser extension, …​

Connecting piece between [Service Provider]s and Keyplets. When Identity Owners start a login process on a Service the Wallet downloads the Workflow specified for the Service and checks for each included Keyplet if the required Identity Factor already exists. Else the [Keyplet Widget] is loaded and rendered. As soon as Identity Factors for all Keyplets defined in the Workflow are available the Identity Factors are submitted to the Service. There the Keyp Connector takes care of the validation of the received Identity Factors and passes the Identity Attributes on to the Service. The Wallet also provides the possibility to manage existing Identity Attributes like editing and deleting. It is also possible to synchronize Wallets so that the same Identity Attributes and Identity Factors are available on multiple devices. A Wallet may also be backed up. Thus, Identity Attributes may be quickly restored in case a mobile phone is lost or irrevocable broken. In order to provide maximum security for the Identity Owner's data, Wallets should only run on platforms using hardware encryption. Wallets should at least enforce strong user credentials like fingerprints or alpha-numeric passwords.

Service

  • Website

  • Web-App or –service

  • Intranet

  • Door

  • …​

Service Provider, SP

Resource, Relying Party

Company running a service

Keyp Connector

Integration Plugin

Connection between a service and the Keyp Protocol, e.g. a Wordpress Plugin. General purpose connectors offered by Keyp support the following services / standards:

  • AD / LDAP

  • SAML

  • OpenID Connect

Workflow

Describes which Keyplets are used during a login process in order to authenticate / identify an Identity Owner. In general, Workflows define chains of Keyplets. Such sequences form sub-workflows with at least one Keyplet. Sub-workflows may themselves be sub-divided into sub-sub-workflows. All Workflows (no matter at which level) define the order of included Keyplets / sub-workflows and list potential alternatives. A Workflow may also include optional Keyplets / sub-workflows. Conditional Keyplets / sub-workflows are supported, too. Workflows are created using Keyp’s Login Manager which provides an intuitive drag & drop interface that allows easy adding, deleting, re-ordering and configuring of Keyplets. The configurations of all Keyplets included in a Workflow together form the [Workflow Configuration].