Integration guide

Identity and Signature Providers - Sandbox Integration Guide

Concepts for Integrators

Purpose

This section provides an overview of the key concepts that application integrators need to understand before integrating with TRIDENT services.

The objective is not to provide a complete specification of OAuth 2.0, OpenID Connect (OIDC), or digital signature standards, but rather to explain the concepts and terminology that will be referenced throughout the integration guides and API documentation.

Identity and Access Management Overview

TRIDENT acts as an Identity Provider (IdP) and Authorization Server, allowing applications to:

Authenticate users
Obtain authorization to access protected resources
Retrieve identity information
Request digital signature operations
Consume verified data services

The platform is based on industry-standard protocols:

OAuth 2.0
OpenID Connect (OIDC)
JWT (JSON Web Tokens)
PKCE (Proof Key for Code Exchange)

OAuth 2.0 Fundamentals

OAuth 2.0 is an authorization framework that allows an application to obtain limited access to protected resources on behalf of a user.

Instead of sharing usernames and passwords with third-party applications, users authenticate directly with the Identity Provider.

The Identity Provider issues an Access Token that represents the permissions granted to the application.

Main OAuth 2.0 Actors

Resource Owner

The user who owns the data or performs an action. For example, citizens.

Client Application

The application is requesting access.

Examples:

Mobile application
Web portal
Third-party system

Authorization Server

The component responsible for:

Authenticating users
Obtaining consent
Issuing tokens

In TRIDENT, this role is performed by the Identity Provider.

Resource Server

The API that validates tokens and provides access to protected resources.

Examples:

Profile APIs
Signature APIs
Verified Data Gateway APIs

Access Tokens

An Access Token represents the authorization granted to a client application.

The token contains information such as:

User identifier
Client identifier
Authorized scopes
Expiration time

Access Tokens are sent in API requests using the Authorization header:

Authorization: Bearer access_token

The API validates the token before returning any information.

Scopes

Scopes define what an application is allowed to access.

Examples:

Scope	Description
uuid	Access the user's unique identifier
profile.document	Access the user's document identifier
profile.first_name	Access first name
profile.middle_name	Access the user's middle name
profile.family_name	Access the user's first surname
profile.name	Access the user's full display name.
profile.birthdate	Access birth date
contact.email	Access email address
contact.phone	Access the user's phone number
contact.validated_cellphone	Access the user's verified mobile phone number.
ebc.address	Access the user's verified residential address
ebc.age.over.18	Verify whether the user is over 18 years of age. Returns only a boolean result (true/false) without disclosing the exact age or birth date
ebc.age.over.60	Verify whether the user is over 60 years of age. Returns only a boolean result (true/false) without disclosing the exact age or birth date
ebc.masked-name	Access a privacy-preserving version of the user's name, where personal information is partially masked
identity.full_profile	Access complete identity profile
urn:safelayer:eidas:sign:process:document	Request digital signatures
service	Allows the application to use the Cloud Signature Consortium (CSC) service

Applications should only request the scopes that are required for their business purpose.

User Consent

Before an application can access personal information, the user may be required to grant consent.

The consent screen presents:

The application requesting access
The information requested
The purpose of access

Example:

Application requests:

First Name
Last Name
Birth Date

The user can approve or deny access.

OpenID Connect (OIDC)

OpenID Connect is an identity layer built on top of OAuth 2.0.

While OAuth 2.0 answers:

"What can the application access?"

OIDC answers:

"Who is the authenticated user?"

ID Tokens

OIDC introduces the concept of an ID Token.

An ID Token is a signed JWT containing identity information about the authenticated user.

Typical claims include:

Subject Identifier (sub)
Name
Email
Authentication time
Issuer

The ID Token is intended for the client application and should not be used to call APIs.

Authentication Flow

The typical authentication process is:

User accesses the application
Application redirects the user to TRIDENT
User authenticates
User grants consent (if required)
TRIDENT returns an Authorization Code
The application exchanges the code for tokens
Application receives:
- Access Token
- ID Token
Application calls protected APIs

PKCE

Proof Key for Code Exchange (PKCE) is an extension to OAuth 2.0 that protects public applications such as:

Mobile applications
Single Page Applications (SPA)

PKCE prevents authorization code interception attacks.

TRIDENT requires PKCE for public clients.

JWT Tokens

JSON Web Tokens (JWT) are compact, digitally signed tokens used throughout the platform.

A JWT typically contains:

Header
Payload
Signature

The signature allows APIs to verify that the token was issued by a trusted authority and has not been modified.

Signature Provider Concepts

A Signature Provider is a service that performs cryptographic signing operations on behalf of a user.

The private signing key remains protected and never leaves the secure environment.

Digital Signatures

A digital signature provides:

Authentication
Integrity
Non-repudiation

A successful signature proves:

Who signed
What was signed
That the content has not been modified

Signing Certificates

Each signer is associated with a digital certificate.

The certificate contains:

Public key
Subject information
Issuer information
Validity period

The certificate is used by relying parties to verify signatures.

Signature Authorization

Before a signature operation is performed, the user must authorize the action.

The authorization method available is a six-digit PIN

Signature Workflow

A typical signing process is:

Application prepares a document or transaction
Application authenticates with TRIDENT
User authorizes the signing request
Signature Provider performs the cryptographic operation
Signed result is returned
Application stores or distributes the signed content

Remote Signing

In a remote signing model:

Private keys remain in secure servers or HSMs
Keys never leave the secure environment
Applications do not have direct access to private keys

This model improves:

Security
Centralized key management

Typical Integration Journey

A typical TRIDENT integration follows these steps:

Register the application
Configure OAuth 2.0 settings
Define required scopes
Configure redirect URIs
Implement OIDC authentication
Obtain Access Tokens
Consume protected APIs
Implement signature workflows if required
Promote the Integration to the Next Environment

Summary

Integrators should understand the following concepts before beginning an integration:

OAuth 2.0
OpenID Connect
Access Tokens
ID Tokens
Scopes
User Consent
PKCE
JWT
Digital Signatures
Signature Providers
Remote Signing

These concepts form the foundation for integrating with TRIDENT APIs, Verified Data Gateway, and digital signature services.

Session Lifecycle, Single Sign-On (SSO), and Logout

Overview

When integrating an application with TRIDENT IDP, it is important to understand how user sessions, Single Sign-On (SSO), and logout mechanisms operate.

TRIDENT IDP acts as the central Identity Provider responsible for authenticating users and enabling SSO across multiple applications. However, each application remains responsible for creating, managing, and terminating its own user session.

Understanding the relationship between these sessions is essential to design a secure and seamless user experience.

Sessions and SSO Fundamentals

When a user accesses an application, the application creates a security context (session) that allows the user to continue interacting with the application without having to authenticate on every request.

In an SSO environment, users typically maintain multiple independent sessions simultaneously:

A session with TRIDENT IDP.
A session with Application A.
A session with Application B.
Additional sessions with other integrated applications.

Although applications delegate authentication to TRIDENT IDP through OAuth 2.0/OpenID Connect (OIDC), session management remains the responsibility of each application.

The session established with TRIDENT IDP serves as the foundation for SSO across all participating applications.

How Single Sign-On Works

The following example illustrates a typical SSO scenario.

User Accesses Application A

The user accesses Application A.
Application A determines that no local session exists.
Application A redirects the user to TRIDENT IDP using OAuth 2.0 / OpenID Connect.
TRIDENT IDP authenticates the user.
TRIDENT IDP creates an Identity Provider session.
The user is redirected back to Application A.
Application A validates the authentication response and creates its own application session.

At this point, the user has:

One session with TRIDENT IDP.
One session with Application A.

User Accesses Application B

The user opens Application B using the same browser.
Application B redirects the user to TRIDENT IDP.
TRIDENT IDP detects an active Identity Provider session.
TRIDENT IDP applies SSO and does not require the user to enter credentials again.
The user is redirected back to Application B.
Application B creates its own application session.

The user can now access both applications without authenticating again.

User Returns to Application A

When the user returns to Application A:

Application A detects its existing local session.
No interaction with TRIDENT IDP is required.
The user continues working normally.

Browser Dependency

SSO relies on browser sessions and cookies.

For SSO to function correctly:

Applications must be accessed using the same browser.
Different tabs within the same browser share the same SSO session.
Different browsers do not share sessions.
Private or Incognito windows maintain separate sessions.
Deleting cookies may invalidate existing sessions.

Depending on browser configuration, sessions may also be removed when the browser is closed.

Session Independence

Application sessions and Identity Provider sessions are independent from each other.

This means:

Logging out from an application does not automatically terminate the TRIDENT IDP session.
Logging out from TRIDENT IDP does not automatically terminate sessions already established with applications.
Each application manages its own session lifecycle independently.

This separation allows users to continue benefiting from SSO across multiple applications.

Session Expiration

TRIDENT IDP Session

The Identity Provider session typically ends when:

The user explicitly logs out from TRIDENT IDP.
The session expires due to inactivity.
Browser cookies are removed.
The browser session is closed.
An application explicitly requests logout from TRIDENT IDP.

The default inactivity timeout should be verified according to the deployed TRIDENT configuration.

Application Session

Application sessions are managed entirely by the application.

Typical termination conditions include:

User logout.
Session inactivity timeout.
Browser cookie expiration or removal.
Application-specific security policies.

Applications may define timeouts that differ from those configured in TRIDENT IDP.

Reauthentication During an Existing Session

An application may require the user to reauthenticate even when an active session already exists.

Common scenarios include:

Accessing sensitive information.
Performing high-value transactions.
Increasing the authentication assurance level.
Requesting additional permissions or scopes.
Step-up authentication requirements.

In these situations, the application redirects the user to TRIDENT IDP to perform additional authentication before granting access to the requested functionality.

Logout Integration

Default Behavior

By default, when a user logs out from an application:

The application session is terminated.
The TRIDENT IDP session remains active.

This behavior preserves the SSO experience and allows users to access other integrated applications without authenticating again.

Coordinated Logout

In some deployments, it may be desirable to terminate both the application session and the Identity Provider session simultaneously.

To achieve this, the application's logout functionality should redirect the user to the TRIDENT IDP logout endpoint:

https://<trident-host>/trustedx-authserver/<idp>/logout

Optionally, a redirect URI can be specified:

https://<trident-host>/trustedx-authserver/<idp>/logout?redirect_uri=
https://application.example.com/logout

The logout flow then becomes:

The user clicks Logout in the application.
The application redirects the browser to the TRIDENT IDP logout endpoint.
TRIDENT IDP terminates the Identity Provider session.
TRIDENT IDP redirects the browser back to the configured redirect URI.
The application terminates its own local session.
The user is fully signed out from both systems.

Applications should clearly inform users when this option signs them out from both the application and the Identity Provider.

Integration Recommendations

When integrating with TRIDENT IDP, consider the following best practices:

Manage application sessions independently from the Identity Provider session.
Do not assume that an active TRIDENT IDP session implies an active application session.
Preserve the Identity Provider session during application logout unless a full sign-out experience is explicitly required.
Implement coordinated logout only when mandated by security or business requirements.
Define session timeout values according to the application's security profile.
Consider step-up authentication requirements for sensitive operations.

Summary

TRIDENT IDP enables Single Sign-On by maintaining a centralized Identity Provider session that can be reused across multiple applications. Each application remains responsible for managing its own local session. Understanding the independence of these sessions, their lifecycle, and the available logout options is essential for implementing secure and user-friendly integrations with TRIDENT IDP.