Skip to content

Crayonic Gateway™

Documentation

1. Overview

Crayonic Gateway™ (CGW) is a FIDO2 ready open source Identity and Access Management solution based on Red Hat Keycloak. With CGW, it is easy to secure applications and services with little or no coding.

It enables passwordless Single Sign-On and provides such features as:

  • Identity brokering

  • User federation

  • Discoverable FIDO Credentials Management

  • Backup & Recovery of FIDO credentials stored in the Crayonic KeyVault™ (CKV) a.k.a. Enterprise Passkeys

  • Management of Crayonic KeyVault™ settings & security policies

  • Self-service cloud (via FIDO enabled web browser) issuance of X509 certificates for PIV access

Supported are all major authentication protocols like SAML, OpenID Connect, OAuth 2.0, LDAP, and WebAuthn.

Crayonic Gateway has been developed to take advantage of powerful enterprise-level features built in the Crayonic KeyVault™ (CKV) smart authenticator.

The fully-featured solution consists of the CKV, Client/Browser on user’s device, Crayonic Gateway™, and optional external Applications/Systems like Active Directory, Amazon Web Services, Google Apps, Okta, etc.

Single Sign-On: Users authenticate with Crayonic Gateway rather than individual applications - your applications don’t have to deal with login forms, authenticating users, and storing users. Once logged in to CGW, users don’t have to log in again to access a different application.

User Federation: CGW has built-in support to connect to existing LDAP or Active Directory servers. You can also implement your own provider if you have users in other stores, such as a relational database.

With CGW, it’s very easy to secure applications and services. There are adapters available for a number of platforms and programming languages. The system is built on standard protocols so you can use any OpenID Connect Resource Library or SAML 2.0 Service Provider library out there.

Basic deployment of Crayonic Gateway is easy as well - it runs via docker-compose and consists of four docker images. By default, it has its own embedded relational database PostgreSQL that will be used to persist data. It can be replaced with another external database if needed. For deployments that are going to be run in production you’ll have a few more options - standalone or domain mode setup for high availability recommended to be managed via Kubernetes.

2. Account Management Console

The account management console is a highly customizable web-based demo application not only in terms of look and feel but tech stack-wise as well. The template used in CGW is based on the Keycloak version written in React.js (also known as Keycloak account console v2).

The goal of the Account management console is to show-case features of CGW from the end-user perspective. All screens, user flows, forms, integrations, etc. can be modified to meet the company’s requirements.

The account management console is divided into 4 main sections:

  • Personal Info - where users can update some basic information about themselves

    • Account SecuritySigning In - lists all linked Authenticators and enables to set a new one

    • Device Activity - lists last login, browser, location, and other useful data

    • Linked Accounts - users can manage logins through 3rd party accounts (e.g. Okta, AWS, etc.)

    • KeyVaultSettings - users can manage their KeyVault settings via web interface instead of directly on the device

    • Backup and Restore - demo screen for KeyVault backup and restore operations

    • Discoverable Credentials - users can see all Discoverable Credentials (also known as Resident Keys) stored on their KeyVault devices. It’s also possible to remove credentials from the device.

    • Certificates - users can manage and download PIV certificates to be used on their KeyVault devices.

In order to get to the Account Management Console, users can navigate to this link (replace realm-name with your realm):

https://crayonic.io/auth/realms/%5Brealm-name%5D/account/#/

When accessing the default ‘gateway’ demo realm on crayonic.io, the following link is also available:

https://crayonic.io/gateway

You can learn more about the content of the Account Management Console in the Crayonic Gateway features section of this document.

2.1 Personal Info

After successful login, the user is able to see and update personal information.

2.2 Account Security / Signing In

This screen lists all linked security keys (CKV, Yubikey, etc.) and enables users to add a new security key or remove an existing one.

Setting up a new security key

After clicking on the ‘set up security key’ link, we are prompted to register a new device:

2.3 Account Security / Device Activity

This screen displays the last login, browser, OS, location, and session information for the user.

2.4 Account Security / Linked Accounts

This screen allows users to manage logins through 3rd party accounts (e.g. Okta, AWS, etc.) and different login providers, including Google, Facebook, Github, etc. in case this is configured and allowed in admin settings.

2.5 KeyVault / Settings

This screen allows users to manage their KeyVaults via the web interface, which is more convenient than via a built-in display on the device. You can learn more about Settings in section 4.3 KeyVault Settings.

2.6 KeyVault / Backup and Restore

This screen is a demo page for the Backup/Restore functionality of Crayonic Gateway.

The procedures for Backup and Restore are described in section 4.4. KeyVault Backup/Restore.

2.7 KeyVault / Discoverable Credentials

This screen allows users to see and manage Discoverable Credentials (also known as Resident Keys) that reside on Crayonic KeyVault devices.

Credential Management is described in more detail in section 4.5. KeyVault Credential Management.

2.8 KeyVault X509 Certificate management

This screen allows the admin to set up synchronization of X.509 certificates for all users registered in the realm.

Certificates are synchronized in the backend process using SCEP protocol and made available for download to Crayonic KeyVault for secure X.509 certificate use cases over the standard PIV protocol i.e. code signing, document signing, email signing, desktop authentication, VPN authentication, SSL client authentications, etc.

There are three default certificate slots available currently:

  • Authentication

  • Digital Signature

  • Key Management

This is an advanced feature for self-managed issuance and re-issuance of certificates over a standard web browser and requires the usage of the Crayonic PIV Manager tool to push certificates to KeyVault.

2.9 Applications

This screen displays all third-party apps connected and made accessible to users via Crayonic Gateway configuration.

Account Console is shown by default, which is the current Account Management Console we are in. Admin can enable access to more applications in the ‘Clients’ section of the Admin console.

3. Admin Console

3.1 Realms/Tenants

Realms are self-contained, independent, and fully configurable workplaces (tenants). There is a master realm, where top-level configuration is done and regular realms, where the majority of admin configuration work is performed.

Master Realm

Master realm is a root realm accessible by super-admin and where other realms (tenants) are configured. It is accessible in case CGW is installed on-premise at this location (replace SITE with your site) :

https://SITE/auth/admin/master/console/

Example for accessing master realm at crayonic.io: https://crayonic.io/auth/admin/master/console/

Hosted Realms

If we want to access realm hosted at crayonic.io, we navigate to this location (replace REALM-NAME with your realm):

https://crayonic.io/auth/admin/REALM-NAME/console/

The user must log in using an account with admin rights to manage given realm, users, authentication flows, 3rd party apps, etc.

3.2 Basic Realm Settings

-> Realm Settings

Look and Feel settings: Themes

-> Realm Settings -> Themes

Themes are screen definitions, highly configurable via .ftl and .js files that reside in /themes folder of CGW installation. The default setup for CGW is as follows:

  • gateway11 as a login theme since it includes a passwordless login form

  • gateway as an account theme to showcase CGW features from a regular user’s point of view

3.3 Clients

-> Clients

A client in CGW represents a resource that particular users can access, whether for authenticating a user, requesting identity information, or validating an access token.

Here we can configure access to apps connected to CGW like:

  • Amazon Web Services

  • Okta IAM

  • Google Apps

  • Azure AD

  • Other 3rd party Applications

Two authentication protocols are supported:

  • SAML2

  • Open ID Connect (OIDC)

Few basic integrations like Okta, AWS, and Microsoft Azure are pre-configured out of the box, but require additional minor configuration to make sure they work with your access tokens.

3.3 Users

-> Users

Basic management of users where all users registered in the CGW are listed. Here we can create and manage users, update access rights, assign roles, refresh their KeyVault credentials, and much more.

3.4 KeyVault Policy

-> Authentication -> KeyVault Policy

This is one of the major features of CGW. KeyVault Policies are mostly security settings for all Crayonic KeyVault devices enforced on an enterprise level. End-users will be able to change settings on their KeyVault devices only to the extent allowed by the active realm policy. When navigating to KeyVault Settings in Account Management Console or directly on the KeyVault device only those options enabled by Realm Policy will be available.

Admins can configure and enforce the following settings (these are also described in more detail in section 4.3 KeyVault Settings):

  • Time and timeouts

  • User Verification timeout

  • Mass Storage timeout

  • KeyVault unlock timeout

  • Fido and U2F - what type of biometrics is allowed for users to log in

    • U2F OS type

    • Biometrics allowed for U2F User presence

    • Biometrics allowed for FIDO User presence

    • Biometrics allowed for FIDO User verification

    • Client PIN on/off

    • ConnectivityBLE Enabled

    • BLE Private Address

    • SmartCard over NFC

    • FIDO over USB

    • SmartCard over USB

    • NFC Enabled

    • BLE Pairing over NFC

    • FIDO over NFC

  • Developer options

    • Export fingerprints

    • Export handwriting

    • USB logging

Buttons explained:

  • Load defaults: default realm configuration is displayed on the screen

  • Get Policy: Active KeyVault Policy for the currently selected realm is loaded from DB and displayed on the screen

  • Set Policy: Policy configuration is made active and enforced on the realm. End-users will be able to change settings on their KeyVault devices according to the active policy only.

  • Save Policy for realm [realm-name]: Saves all the changes made on the screen to DB

4. Crayonic Gateway™ features

In this chapter we describe features that are specific to CGW:

  • Passwordless Login

  • User Registration - First-time login

  • KeyVault Backup and Restore

  • KeyVault Settings

  • KeyVault Credential Management

All mentioned features are available either at the Crayonic Gateway demo site (crayonic.io/gateway) or on-premise in case CGW is installed and configured locally. This document assumes we have access to the Crayonic Gateway demo site and features are described as they are available on this particular site.

Some technical features like integration with AD, AWS, Okta are out of the scope of this document, but can be looked up in original Keycloak documentation as they are basically the same as in CGW:

4.1 Passwordless Login

Navigate to Account Management Console:

https://crayonic.io/gateway or https://crayonic.io/auth/realms/gateway/account/

Clicking on the ‘Sign In’ button or any link from the navigation box should bring us to the login screen:

There is a basic check whether our platform, browser, and operating system support FIDO2/Webauthn protocol. When all is ok, we get a login screen with two buttons and the status message ‘Crayonic KeyVault is supported’.

If this is our first-time login in the system, we need to provide a Username and hit enter or ‘Login with username’ button. We are then asked to register KeyVault and can continue navigating the site. If we get an ‘invalid username’ error, it means the user is not yet enabled in the admin console (see User registration section for more information)

Registering KeyVault

After clicking on the ‘Register’ button, the user is prompted to register the KeyVault device so that it can be used for all later logins. The user is prompted to authenticate on the device using PIN/Fingerprint or other ways as configured in Realm Policy.

The login page remembers the last logged user in the username field so next time we just need to hit enter on the keyboard or click the ‘Login with username’ button on the page and proceed with authentication on KeyVault.

For any subsequent logins, we can just click the ‘Login with username’ button.

Note: FIDO2/WebAuthn is still a new technology and as such is still not supported on all operating systems, platforms (phones, tablets, notebooks), and browsers. Nevertheless, most widely used systems and browsers fully support WebAuthn. You can learn more about supported systems here:

https://caniuse.com/webauthn

OS-level support for WebAuthn:

  • Windows 10: Chrome, Edge, Firefox, Opera via USB/BLE/NFC

  • macOS Big Sur: Chrome, Edge, Safari via USB only

  • Android: Chrome, Android Browser via BLE/NFC

  • iOS: Chrome, Safari via NFC

4.2 User Registration - First-time login

The main requirement for logging into Account Management Console is that the user must be created in the system - either manually in Admin Console or automatically through User Federation.

Here are the required steps for admin in order to make sure the user is able to log in.

Navigate to Users -> View all users in Admin Console and check whether the user is listed or needs to be created.

When using User federation, click on User Federation -> ‘Federation Provider ID’ -> ‘Synchronize All Users (or Synchronize changed users) button’. This action syncs users between connected systems and assures CGW has the latest information. The usual scenario is one-way (read-only) synchronization from Active Directory to CGW.

Creating new user

  • Navigate to Users in the main navigation bar, Click ‘Add User’

  • Enter Username (all other fields are optional) and hit the Save button. Note ‘Webauthn Register Passwordless’ action is set in the Required User Actions field.

  • Click on the Role Mappings tab

  • Choose ‘account’ in the Client Roles dropdown and select roles you would like to assign to the user. Select manage-account, manage-account-links, view-profile, view-applications as a minimum.

  • Now our newly created user can initiate the first log in and register KeyVault device - see section 4.1. Passwordless Login

Modifying existing user

Follow these steps in case users are federated (synced with AD or another system).

  • Navigate to Users in the main navigation bar, search for a user or click ‘View all users’

  • Click the ‘Edit’ button next to the user’s name or click on the 'user id’ link

  • Click on the Details tab and make sure Webauthn Register Passwordless is selected in the Required User Actions field.

  • Click on the Role Mappings tab

  • Choose ‘account’ in the Client Roles dropdown and select roles you would like to assign to the user. Select manage-account, manage-account-links, view-profile, view-applications as a minimum.

  • Now the user can initiate the first login in CGW and register the KeyVault device - see section 4.1. Passwordless Login

Enrolment of a new KeyVault for the user (and removing the old KeyVault)

  • Navigate to Users in the main navigation bar, search for a user or click ‘View all users’

  • Click the ‘Edit’ button next to the user’s name or click on the 'user id’ link

  • Click on the Credentials tab and check whether the user already has webauthn passwordless authentication device (KeyVault) assigned. If yes, hit Delete which deregisters this authenticator from the user’s account.

  • The user can now log in to Account Management Console, enter the username, and hit the ‘Login with username’ button. This will start the registration process where a new KeyVault is registered for the user - see section 4.1 Passwordless Login

4.3 KeyVault Settings

Location: KeyVault -> Settings

This screen allows users to manage their KeyVaults via the web interface, which is more convenient than via a built-in device LED display.

Most of the settings are enforced by KeyVault Policy which is fully configurable by admin in Admin Console. This includes types of biometrics allowed in the login process (e.g. Fingerprints, PIN code, Handwriting, Voice).

Settings screen consists of these main sections:

  • Timeouts

    • User verification timeout: how long can the authentication process via KeyVault last. Authentication must complete during this time period, otherwise, we get an error. We recommend setting higher times in case users are required to enter or write their PIN.

    • Mass storage timeout: defines how long is built-in USB storage available for the user after it is turned on

    • Unlock timeout: defines for how long is KeyVault kept unlocked after successful authentication. During this time period, no authentication is required - the user can access protected sites/applications without a need to authenticate.

  • Fido and U2F

    • defines how can user authenticate:

      • simple button touch (without user verification)

      • fingerprints

      • entering PIN code

      • writing PIN code

      • entering PIN code using voice recognition

    • available/enforced authentication ways are displayed as red icons

  • Connectivity

    • various settings to enable and configure Bluetooth, NFC, and smartcard communication

Following actions are available for the user apart from tweaking settings:

  • Load default KeyVault settings via the ‘Load defaults’ button

  • Retrieve current settings from KeyVault to screen via the ‘Get Settings’ button

  • Save settings from screen to KeyVault device via the ‘Set Settings’ button

4.4 KeyVault Backup/Restore

Location: KeyVault -> Backup and Restore

This screen is a demo page for Backup/Restore functionality. Visual elements on the page are linked to the Gateway API which handles all the necessary logic on the backend.

The user can backup their KeyVault device as well as restore its content in case it is lost or damaged. The number of backups is not limited and it is recommended to perform backups regularly. It is possible to set up an automatic backup process that runs after each successful login to Account Management Console.

Restore operation retrieves the selected backup and updates KeyVault with this content.

For demonstration purposes, we included the status section (Backup/Restore output) so that the user is able to see the status of backup and restore operations.

4.4.1 Metadata stored in the backup payload

  • KeyVault serial number

  • Date and time of backup

  • Username+Realm for which backup is stored

  • Master seed

  • Authenticator counter

  • Number of discoverable credentials stored on the device

  • Discoverable credentials (resident keys)

  • KeyVault settings

4.4.2 How to perform Backup

  • Make sure KeyVault device is connected to the computer (USB/BLE/NFC)

  • Navigate to Account Management Console -> KeyVault -> Backup and Restore

  • Click the ‘Backup KeyVault’ button

  • The status section displays the result of the operation. Success Result-Code = 9000.

  • In case the operation is successful, KeyVault is now backed up to CGW and can be restored later on

4.4.3 How to perform Restore

Make sure the KeyVault device is connected to the computer (USB/BLE/NFC).

1) If we are restoring the same device

This scenario is covers situations when we would like to revert to older settings or get rid of newly added discoverable credentials.

  • Navigate to Account Management Console -> KeyVault -> Backup and Restore

  • Click the ‘Show Backups’ button

  • Select the backup item you would like to use - note backups from different KeyVaults can be used as well (SN Column)

  • Click the ‘Restore KeyVault’ button

  • The Status section displays the result of the operation. Success Result-Code = 9000.

  • In case the operation is successful, KeyVault is now restored with the selected backup retrieved from Gateway DB

2) If we are restoring a new KeyVault and do NOT have access to CGW

This scenario covers a situation when the original KeyVault was lost or damaged and we would like to restore contents to a new KeyVault. There are a few steps that are required on the admin side.

  • As an admin, log in to Admin Console

  • Navigate to Users in the main navigation bar, search for the user or click ‘View all users’

  • Click the ‘Edit’ button next to the user’s name or click on the 'user id’ link

  • Click on the Credentials tab and double-check whether the user already has webauthn passwordless authentication device (KeyVault) assigned. If yes, hit Delete which deregisters this authenticator from the user’s account.

  • The user can now log in to Account Management Console, enter the username, and hit ‘Login with username’ button. This will start the registration process where a new KeyVault is registered for the user - see section 4.1 Passwordless Login

  • Now the new KeyVault is registered and the user can access CGW but we still need to restore its content

  • As an admin, log in to Admin Console

  • Navigate to Users in the main navigation bar, search for the user or click ‘View all users’

  • Click the ‘Impersonate’ button next to the user’s name in Actions section, Account Management Console should load with the user already signed in.

  • Navigate to KeyVault -> Backup and Restore

  • Click the ‘Show Backups’ button

  • Select the backup item you would like to use - note backups from different KeyVaults can be used as well (SN Column)

  • Click the ‘Restore KeyVault’ button

  • The Status section displays the result of the operation. Success Result-Code = 9000.

  • In case the operation is successful, KeyVault is now restored with the latest backup retrieved from DB

  • Sign Out impersonated user and close the browser window with Account Management Console

  • The user can now log in with a newly restored KeyVault

4.5 KeyVault Credential Management

Location: KeyVault -> Discoverable Credentials

Credential Management is another special feature of CGW and allows users to manage Discoverable Credentials (also known as Resident Keys) that reside on a Crayonic KeyVault device.

Discoverable Credential means that the private key and associated metadata are stored in persistent memory on the KeyVault, instead of encrypted and stored on the relying party server.

This feature is available in two locations:

  • KeyVault -> Backup and Restore

  • KeyVault -> Discoverable Credentials

1. Backup and Restore screen

After hitting the ‘Show Discoverable Credentials’ button, Credential Management API is called which retrieves all Discoverable Credentials from the latest backup.

  • Username/Display Name are handles that are chosen by the server or user when registering KeyVault during WebAuthn operation.

  • Relying Party is a service or server that allows passwordless authentication using KeyVault.

  • User Id is shortened internal user handle

  • User Id Crayonic Gateway is UUID formatted ‘User id’ used to identify the user in Crayonic Gateway

  • Credential Id is a credential identifier shortened to 30 characters.

2. Discoverable Credentials screen

This screen lists all Discoverable Credentials from KeyVault’s latest backup as well as allows the user to remove selected credentials from KeyVault.

Displayed is Username (and Display Name in brackets in case these two names are different) as well as Relying Party - a server host for given Credential.

The user can remove credentials by clicking on a trash bin icon.