OpenID Connect

Most OpenID Connect configuration values can be retrieved in JSON format by

  GET /.well-known/openid-configuration

Public keys for JWT signature validation can be retrieved in JWKS format by

  GET /.well-known/jwks.json

See RFC 7517 – JSON Web Key for the format specification.

The JWKS may contain one or multiple keys. Key rollover may take place at any time. The currently used key can be identified by the JWT “kid” header field. Whenever a JWT header contains a kid which doesn’t match the public key in your application cache, the list of public keys must be refreshed.

Determine a User’s identity

The User’s identity can easily be determined by following the OpenID Connect standard implemented by the OAuth Server. Simply pass “openid” as one of the scope parameter values during auth request (see above). The access token response will then contain a serialized and signed JSON Web Token (JWT) containing the following claims:

Claim name	Type	Description
iss	String	Issuer of the response (”https://auth.ionos.com/”)
sub	String	Unique user identifier
aud	String	Client id of the requesting Client
nonce	String	Used to associate a Client session with an ID token, passed through from auth request (if given)
exp	Long	Expiration time in seconds since epoch UTC on or after which the ID token must not be accepted for processing
iat	Long	Time at which the JWT was issued in seconds since epoch UTC
amr	String	Authentication methods references (currently only “pwd”)
auth_time	Long	Time when User authentication occurred in seconds since epoch UTC
sid	String	Identifier for the Session.
market	String	One of DE, FR, IT, GB, ES, US, CA, MX.
locale	String	User’s language (if known), e.g. de-DE.
account_refs	List	Account references from IDAPI

If other scopes like “address” or “email” have been requested, the JWT will also contain the respective user data (see below).

Access User resources

To retrieve User data the following endpoint can be queried:

  GET /userinfo

The call must be secured by use of a valid access token. An “Authorization” HTTP header must be passed, e.g. Authorization: Bearer 2YotnFZFEjr1zCsicMWpAA.

Depending on the given scopes within the auth request a set of User details (claims) will be returned:

Scope	Claims	Description
openid	sub, market, locale account_refs, masterdata_id	Unique user identifier, market (e.g. DE or GB), language (e.g. de-DE), account_refs (e.g. [{TRINITYID 12345}]
email	email	User’s main contact email address
phone	phone_number	User’s main contact phone number
address	address	User’s postal address
profile	name, given_name, family_name, organization, birthdate, gender	User’s profile

“sub” is a URN containing the userID as last component, for example: “ionos:iam:hosting::users/127d43ca-aee2-410c-9168-04bda0ee9fbc-maileu”

Please note that the quality of the data depends on the availability and reliability of underlying backend services. Some entities like birthdate, gender or even phone_number might not always be present.