Skip to main content
Skip table of contents

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.

Other Not Supported OIDC Functions

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.