Trinity OIDC Functions

This page outlines the most important OIDC aspects relevant to Trinity.

In the following description, you will find which OIDC functions and parameters are supported by Trinity.

Trinity supports what our customers need in order to build their anticipated use cases in a lean manner. If we lack a parameter or function that you require, let us know, and we will put it on our roadmap.

OpenID Connect 1.0 is a simple identity layer on top of the OAuth 2.0 protocol. It enables Clients to verify the identity of the End-User based on the authentication performed by an Authorization Server, as well as to obtain basic profile information about the End-User in an interoperable and REST-like manner.

You can find the full specification here: https://openid.net/specs/openid-connect-core-1_0.html

Trinity supports the authorization code flow with PKCE, the most advanced OIDC flow. It is also the most flexible and allows both mobile and web clients to obtain tokens securely and gain access to web APIs. The authorization flow runs in the browser, where the client redirects to the OAuth server, and the OAuth server redirects back when done. The token flow is a back-channel call from the client to the token endpoint of the OAuth server.

Trinity Version

This page reflects what is supported by Trinity Version 1.7

Discovery Document (.well-known)

Please find an overview of all available functions in our .well-known Discovery Document.

OIDC Standard Scopes

Scopes are defined (yet hardcoded) within the Trinity Backend Service and map on OIDC claims, which are defined in so-called “Issuer Modules” integrated in the SDK. Please refer to the respective documentation of your platform to create claims in the SDK. (iOS Custom Modules, Android Custom Modules)

Without a “custom module” providing the claim to the SDK, the resolving of the request will fail.

Scope	Necessity	Description
`openid`	required	Informs the Authorization Server that the Client is making an OpenID Connect request. If the `openid` scope value is not present, the behavior is entirely unspecified. This scope is required in order to obtain an ID Token alongside the Access Token when making a request to the Access Token endpoint.
`email`	optional - requires a custom module to provide claims	This scope value requests access to the `email` and `email_verified` Claims.
`profile`	optional - requires a custom module to provide claims	This scope value requests access to the End-User's default profile Claims. Using this scope in conjunction with the scope `openid` will result in getting an ID Token which will include the additional claims: `name`, `family_name`, `given_name`, `birthdate`, on top of the claims provided when only using the scope `openid`. For now it doesn’t include these claims: `middle_name`, `nickname`, `preferred_username`, `picture`, `website`, `gender`, `zone_info`, `locale`, and `updated_at`
address	not yet supported -requires a custom module to provide claims	This scope value requests access to the `address` Claim.
phone	not yet supported -requires a custom module to provide claims	This scope value requests access to the `phone_number` and `phone_number_verified` Claims.
offline_access	not supported	This scope value requests that an OAuth 2.0 Refresh Token be issued that can be used to obtain an Access Token that grants access to the End-User's UserInfo Endpoint even when the End-User is not present (not logged in). Due to the design and purpose of Trinity, we decided not to support the Refresh Token for now.

Trinity Specific Scopes

Scope	Necessity	Description
`insured`	optional	This scope simulates the requirement of insurance services similar to how it’s designed in the German T.I. asking for the OIDC-standard claims `family_name`, `given_name` and a custom scope `demo.ver.healthinsurance.l0.api.demo` (which returns a users health insurance member number)
`insured_pkv`	optional	This scope simulates the requirement of insurance services similar to how it’s designed in the German T.I. within the scope of a PKV project.

OIDC ID Token Claims

Claim	Necessity	Description
`iss`	required	Issuer identifier for the issuer of the ID Token. This will be set to the domain that your OP is reachable at, i.e. `https://oidc.cls.comuny.de/oidc/v1`.
`sub`	required	Subject Identifier. A locally unique and never reassigned identifier within the Issuer for the End-User, which is intended to be consumed by the Client The subject is set by the Trinity SDK and can be defined freely by the app developer, see: https://android.doc.cls.comuny.de/interaction/#authorization https://ios.doc.cls.comuny.de/documentation/trinityidwallet/trinityauthorizationconfiguration/init(authurl:subject:)
`aud`	required	Audience(s) that this ID Token is intended for – will be set to the OIDC Relying Party requesting the ID Token.
`exp`	required	Expiration time on or after which the ID Token MUST NOT be accepted by the RP when performing authentication with the OP. Expiration time is currently set to 24 hours and is not (yet) configureable.
`iat`	required	Time at which the JWT was issued.
`auth_time`	optional	Time when the End-User authentication occurred.
`nonce`	optional	String value used to associate a Client session with an ID Token, and to mitigate replay attacks.
`at_hash`	optional	Access Token hash value. Its value is the base64url encoding of the left-most half of the hash of the octets of the ASCII representation of the `access_token` value, where the hash algorithm used is the hash algorithm used in the `alg` Header Parameter of the ID Token's JOSE Header.
acr	optional / not supported	n/a
amr	optional / not supported	n/a
azp	optional / not supported	n/a

OIDC IDToken Encryptions

Trinity is built with privacy in mind. The architecture prevents that whoever is operating the Trinity Backend Service must not be able to read the users data (content of IDToken & User Info). This can only be achieved if the Relying Party is using Signing and Encryption as described here: https://openid.net/specs/openid-connect-core-1_0.html#SigEnc

Depending on the transport through which the messages are sent, the integrity of the message might not be guaranteed and the originator of the message might not be authenticated. To mitigate these risks, ID Token, UserInfo Response, Request Object, and Client Authentication JWT values can utilize JSON Web Signature (JWS) [JWS] to sign their contents. To achieve message confidentiality, these values can also use JSON Web Encryption (JWE) [JWE] to encrypt their contents.

For now Trinity supports the following Encryption Algorithms for the IDToken

CODE

  ],
  "id_token_encryption_alg_values_supported": [
    "RSA1_5",
    "RSA-OAEP",
    "RSA-OAEP-256",
    "ECDH-ES",
    "ECDH-ES+A128KW",
    "ECDH-ES+A192KW",
    "ECDH-ES+A256KW",
    "PBES2-HS256+A128KW",
    "PBES2-HS384+A192KW",
    "PBES2-HS512+A256KW"
  ],
  "id_token_encryption_enc_values_supported": [
    "A128CBC-HS256",
    "A192CBC-HS384",
    "A256CBC-HS512"

and the same for the UserInfo

CODE

  "userinfo_encryption_alg_values_supported": [
    "RSA1_5",
    "RSA-OAEP",
    "RSA-OAEP-256",
    "ECDH-ES",
    "ECDH-ES+A128KW",
    "ECDH-ES+A192KW",
    "ECDH-ES+A256KW",
    "PBES2-HS256+A128KW",
    "PBES2-HS384+A192KW",
    "PBES2-HS512+A256KW"
  ],
  "userinfo_encryption_enc_values_supported": [
    "A128CBC-HS256",
    "A192CBC-HS384",
    "A256CBC-HS512"

Individual Claims Requests

The userinfo and id_token members of the claims request both are JSON objects with the names of the individual Claims being requested as the member names. The member values MUST be one of the following:

Claim Request Value	Necessity	Description
null	optional / not supported	Indicates that this Claim is being requested in the default manner.
JSON Object		This specification defines the following members:
essential	optional / not supported	n/a
`value`	optional	Requests that the Claim be returned with a particular value
values	optional / not supported	n/a
Claim Types
`Normal Claims`	optional	Claims that are directly asserted by the OpenID Provider.
Aggregated Claims	optional / not supported	n/a
Distributed Claims	optional / not supported	n/a

OIDC Standard Claims & Custom Claims

With Trinity, claims are defined and created by you; the app developer. Nevertheless, comuny provides different example and showcase modules in our Demo Apps that are used to define Standard Claims or Custom Claims:

Authada uses NFC eID scanning to import verified German “Elektronischer Personalausweis (eID)” or “Aufenthaltstitel” data
IDnow uses image detection from IDs scanning to import verified German ID data
Twilio verifies E-Mail addresses using the Sendgrid API
OIDC Sample module creates example/test content for default OIDC claims

If you have our Demo App you can test different claim/scope requests here:https://oidc.cls.comuny.de/oidcdemo/login

See OIDC Standard Claims: https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims

Claim	Trinity Example Modules
sub	optional/Is set during SDK initialization https://android.doc.cls.comuny.de/interaction/#authorization https://ios.doc.cls.comuny.de/documentation/trinityidwallet/trinityauthorizationconfiguration/init(authurl:subject:)
claims_locales	not supported OIDC standard claim
name	Authada, IDnow, Sample - OIDC standard claim
given_name	Authada, IDnow, Sample - OIDC standard claim
family_name	Authada, IDnow, Sample - OIDC standard claim
middle_name	not supported OIDC standard claim
nickname	not supported OIDC standard claim
preferred_username	not supported OIDC standard claim
profile	not supported OIDC standard claim
picture	not supported OIDC standard claim
website	not supported OIDC standard claim
email	Twilio - OIDC standard claim
email_verified	Twilio - OIDC standard claim
gender	not supported OIDC standard claim
birthdate	Authada, IDnow, Sample - OIDC standard claim
zoneinfo	not supported OIDC standard claim
locale	not supported OIDC standard claim
phone_number	not supported OIDC standard claim
phone_number_verified	not supported OIDC standard claim
address	not supported OIDC standard claim
updated_at	not supported OIDC standard claim
demo.ver.healthinsurance.l0.api.demo	Sample / custom claim defined by Trinity representing a health insurance member number

Supported OIDC Request Parameters

https://openid.net/specs/openid-connect-basic-1_0.html#RequestParameters

Parameter	Necessity / Supported?	Description
response_type	Required	This value MUST be `code`. This requests that both an Access Token and an ID Token be returned from the Token Endpoint in exchange for the `code` value returned from the Authorization Endpoint.
client_id	Required	OAuth 2.0 Client Identifier valid at the Authorization Server.
Scope	Required	OpenID Connect requests MUST contain the `openid` scope value. OPTIONAL scope values of `profile`, `email`, `address`, `phone`, and `offline_access` are also defined. See Section 2.4 for more about the scope values defined by this specification.
redirect_uri	Required	Redirection URI to which the response will be sent. This URI MUST exactly match one of the Redirection URI values for the Client pre-registered at the OpenID Provider, with the matching performed as described in Section 6.2.1 of [RFC3986]
state	Recomended	Opaque value used to maintain state between the request and the callback. Typically, Cross-Site Request Forgery (CSRF, XSRF) mitigation is done by cryptographically binding the value of this parameter with a browser cookie
nonce	Optional	String value used to associate a Client session with an ID Token, and to mitigate replay attacks.
display	Optional / not supported	ASCII [RFC20] string value that specifies how the Authorization Server displays the authentication and consent user interface pages to the End-User.
prompt	Optional	Space-delimited, case-sensitive list of ASCII string values that specifies whether the Authorization Server prompts the End-User for reauthentication and consent. The defined values are: none The Authorization Server MUST NOT display any authentication or consent user interface pages. An error is returned if an End-User is not already authenticated or the Client does not have pre-configured consent for the requested Claims or does not fulfill other conditions for processing the request. The error code will typically be `login_required`, `interaction_required`. This can be used as a method to check for existing authentication and/or consent. login The Authorization Server SHOULD prompt the End-User for reauthentication. If it cannot reauthenticate the End-User, it MUST return an error, typically `login_required`. consent The Authorization Server SHOULD prompt the End-User for consent before returning information to the Client. If it cannot obtain consent, it MUST return an error, typically `consent_required`. select_account -> not supported by Trinity
max_age	Optional	Maximum Authentication Age. Specifies the allowable elapsed time in seconds since the last time the End-User was actively authenticated by the OP. If the elapsed time is greater than this value, the OP MUST attempt to actively re-authenticate the End-User. When `max_age` is used, the ID Token returned MUST include an `auth_time` Claim Value. Note that `max_age=0` is equivalent to `prompt=login`.
ui_locales	Optional / not supported
claims_locales	Optional / not supported
id_token_hint	Optional / not supported
login_hint	Optional / not supported
acr_values	Optional / not supported

Trinity Configurable IDP Backend properties

The Trinity Backend Service provides features to configure the IDP's OIDC functions, which are listed and described in this section.

comuny.stage.include-scopes-in-user-info

This configuration property determines the delivery method for scopes to the relying party. When the value is set to true, scopes will be embedded in UserInfo; otherwise, they will be included in the ID-Token. By default, scopes are included as part of ID-Token.

Define this property in the trinity-config-map.yaml file.

Configure supported claims and scopes

At this point, claims and scopes are hardcoded in the backend. Trinity supports all standard OIDC Scopes and Claims. If you need specific Scopes and Claims, please contact us.

ID-Token & UserInfo Signing Algorithms for communication with Relying Party

We offer the following IDToken & UserInfo signing algorithms, which can be set in the IDP.

RSA256
ECC (on the roadmap for 2024)

We are working on adding more to cover the most common and secure algorithms. Please let us know if you have a specific requirement for the signing algorithm.