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.

Logout

The OAuth Server supports three complementary logout mechanisms defined by the OpenID Connect specifications. All three can be used together or independently, depending on the Relying Party’s capabilities.

Back-Channel Logout

The server implements OpenID Connect Back-Channel Logout 1.0. When a user’s session is terminated — either by the user navigating to GET /logout or by an internal logout request to POST /slo — the server sends a signed Logout Token JWT via HTTP POST to every registered backchannel_logout_uri for the affected client.

The Logout Token is a JWT signed with the server’s current RSA key (see /.well-known/jwks.json) and contains the following claims:

Claim	Description
`iss`	Issuer (`https://auth.ionos.com/`)
`sub`	User identifier (URN)
`aud`	Client ID of the receiving client
`iat`	Issuance time (seconds since epoch)
`jti`	Unique JWT ID
`sid`	Session identifier (optional, present when `backchannel_logout_session_required` is `true` for the client)
`events`	`{"http://schemas.openid.net/event/` `backchannel-logout": {}}`

Clients must:

Register a backchannel_logout_uri during client registration.
Accept POST requests with Content-Type: application/x-www-form-urlencoded containing the logout_token parameter.
Validate the Logout Token (signature, iss, aud, iat, jti, events claim).
Terminate all sessions for the identified sub, or the specific session identified by sid if present.

Support is advertised in the OpenID Configuration:

{
  "backchannel_logout_supported": true,
  "backchannel_logout_session_supported": true
}

Front-Channel Logout

The server implements OpenID Connect Front-Channel Logout 1.0. When Front-Channel Logout is enabled, the GET /logout response renders a logout page containing hidden <iframe> elements, one per registered client. Each iframe points to the client’s registered frontchannel_logout_uri.

If the client has registered with frontchannel_logout_session_required set to true, the following query parameters are appended to the URI:

iss — the issuer URL
sid — the session identifier (SHA-256 hash of the internal session UUID)

After all iframes have loaded (or a timeout of several seconds has elapsed), the browser is redirected to the post_logout_redirect_uri if one was supplied and is valid, or to the default logout page otherwise.

Support is advertised in the OpenID Configuration when enabled:

{
  "frontchannel_logout_supported": true,
  "frontchannel_logout_session_supported": true
}

Session Management

The server implements OpenID Connect Session Management 1.0. This mechanism allows Relying Parties to detect a session change at the OP without sending a network request to the OP’s token endpoint.

When Session Management is enabled, the following additions apply:

``check_session_iframe`` endpoint (GET /check-session-iframe)

A static HTML page containing a JavaScript listener. Relying Parties embed this URL in a hidden <iframe> and periodically send a postMessage to it. The message must have the format:

client_id + " " + session_state

The iframe responds with one of:

"unchanged" — the session state matches the OP’s current state.
"changed" — the session state has changed; the RP should re-authenticate the user silently or prompt for login.
"error" — the message format was invalid.

``session_state`` in authorization responses

The /authorize endpoint includes a session_state parameter in the redirect response. Its value encodes the current OP browser state and must be stored by the RP for subsequent iframe polling.

OP Browser State cookie (``_opbs``)

The server sets an _opbs cookie that ties the browser session to the computed session_state. This cookie is deleted on logout.

The check_session_iframe URL is advertised in the OpenID Configuration when enabled:

{
  "check_session_iframe": "https://id.ionos.com/check-session-iframe"
}