Principles & Overview
Welcome to the Trinity Documentation for Developers
This documentation is aimed at developers who intend to use the Trinity Digital Identity Wallet (aka Trinity IDP) provided by comuny.
The Trinity Digital Identity Wallet (Trinity IDP)
With the Trinity Identity Wallet product, software developers receive a technical framework for developing secure and self-determined mobile identification solutions. Trinity Identity Wallet is a collection of software components for a data operator. Developers can integrate this into their mobile applications. The architecture is based on a client-server principle: the mobile Trinity SDK as a client and the Trinity backend as a server.
With Trinity, a developer can create an identity provider (abbreviated IdP or IDP), a system entity that creates, maintains, and manages identity information for principals and provides authentication services to relying applications within a federation or distributed network.[1][2]
Identity providers offer user authentication as a service. Relying-party applications, such as web applications, outsource the user authentication step to a trusted identity provider. Such a relying party application is said to be federated, meaning it consumes a federated identity.
An identity provider is “a trusted provider that lets you use single sign-on (SSO) to access other websites.”[3] SSO enhances usability by reducing password fatigue. It also provides better security by decreasing the potential attack surface.
Identity providers can facilitate connections between cloud computing resources and users, thus decreasing the need for users to re-authenticate when using mobile and roaming applications.[4][1]
Trinity: Overview
The Trinity product has two main components: the Trinity Backend Service and the Trinity SDK. They enable the implementation of an OpenID connect service provider while respecting Self-sovereign identity principles in a novel (patent pending) privacy and user consent preserving process while limiting the profiling possibilities of the operator and catapulting user data protection to a whole new level. It can be used to build modern single-sign on applications to initiate data verification, authentication and trust in the user on the highest level.
The protocol behind the product integrates modern cryptographic techniques to guarantee data integrity and encryption between the user and client applications end-to-end.
Trinity is a Software Toolset and is installed on your premise. The Backend Service is available for primarily Amazon AWS, Google Cloud as well as Microsoft Azure. While the SDK can be integrated into your iOS or Android Application.
How to install the Backend on your premise you find here: Trinity Backend Service
How to integrate the SDK into your iOS and Android App you find here: Trinity SDK |
How does it work
A client initiates an OIDC authorize request against the Trinity Backend Service
This request also specifies the data to be verified and the authentication factors to be executed (see Claims)
In the case of a web application frontend client, the Trinity Backend Service presents a QR-code to the user
The QR-code contains a session identifier which the SDK then translates to all necessary information to resolve the authorize request
The user opens the authenticator app which includes the integrated Trinity SDK
Along with that, the user authenticates at the device using a PIN
The app scans the QR-code and passes the result to the SDK
QR code scanning is not part of the SDK so that you can choose the library and integration which is most suitable for your app. There are various components with different (also free) licensing models available, so you can take the most suitable. The result of the QR code has to be passed AS-IS to the SDK. All additional handling is done by the SDK.
The SDK now starts the verification and authentication processes involving the required and selected issuers (IDNow, Authada, Twilio, etc. or even custom ones)
Along this process, there are multiple points with interactions with the user which are not displayed in the diagram. These interaction points can be tailored to fit the layout of your application.
The interaction points are:
Initial consent to start the process
Executing the actual verification or authentication
Final consent to send the requested information and proceed with the process
On successful response, the Trinity Backend Service will perform the redirect to the
redirect_urlalong with information according to the requested response type.
To summarize, your client should use standard OIDC following the Authorization Code Flow with PKCE, while on the mobile side (your authenticator app), you need to interact with the SDK.
Key technical features
No upfront configuration: all information required for data verification and authentication is part of the initial request
End-to-End encryption: all data is encrypted with the client keys before transferring. We provide options for verifying key integrity and key rotation.
Full OIDC compliance: our functionality matches the OIDC standard and can therefore be easily used with many off-the-shelf products
Native SDKs: our Android and iOS SDKs can be natively integrated into your app
Getting Started
When you're getting started with the Trinity software components, you are probably going to be in either of the following three positions:
You want to enable your app developers to integrate the Trinity functionalities by providing the matching backend → Backend Hosting
You want to extend your existing app to an Authenticator App with the Trinity functionalities → SDK Integration
You want to build a client which uses the Trinity Backend as an OpenID Provider (Authorization and Ressource Server) → Client Development & Client Registration
(If we've missed any of your interests, kindly let us know ☻)
To be capable to tryout the Trinity ecosystem in a fully fledged and logical manner, we recommend the following implementation order:
(If not already, get familiar with OAuth/OIDC)
Setup the Trinity Backend Service
Integrate the Trinity SDK into your app
Build a client and play through your login flow end-to-end
If you're not interested in setting up your own Trinity Backend Service, we're happy to provide you with a testing environment upon request at support@comuny.de.