Custom claims

The OAuth client registration allows the configuration of claims that are gained by an external claim provider service. When issuing an IDToken and such a claim is required because it is configured to a client of the type internal, the corresponding claim provider service is called.

Request

The following URL-encoded data is sent to the configured URI of a Claims Provider via http POST request

sub: The URN of the actor (userID)
claims: A space separated list of claims that are configured for the token requesting client and that belong to the same Claims Provider URI

Example

POST /claim_source HTTP/1.1
Host: server.example.com
Content-Type: application/x-www-form-urlencoded

sub=ionos%3Aiam%3Ahosting%3A%3Ausers%2F127d43ca-aee2-410c-9168-04bda0ee9fbc-maileu& claims=https%3A%2F%2Fexample.com%2Fclaims%2Fcontext%20https%3A%2F%2Fexample.com%2Fclaims%2Fuser%20https%3A%2F%2Fexample.com%2Fclaims%2Ftype

Response

A signed JSON Web Token (JWT): header.payload.signature

Example

Content-Type: application/jwt

eyJraWQiOiIyMDE4LTExLTI3IiwiYWxnIjoiUlM1MTIifQ.eyJodHRwczovL2lkLmlvbm9zLmNvbS9jbGFpbXMvdGVzdC9iYXIiOiJ7XCJiYXpcIjo3N30ifQ.DopiEWVTscIhCYj2mY73Q8IxpA-3_0wni4AtZl4DW36omGup98HO01XL98dOmhQkf5pJje5MtfyEhFHnpxtq0UA7qhWEIGYkvnPmTebxUZPSa4Zl_o_T37tY

Example for payload:

{
  "https://example.com/claims/somestring": "123",
  "https://example.com/claims/somenumber": 99,
  "https://example.com/claims/someobject": {
    "type": "basic"
  }
}

JWK

The service must also provide a JSON Web Key (JWK) endpoint to share the public key(s).

The JWKS can contain one or multiple keys. Key rollover can take place at any time. The currently used key has to be identified by passing the JWT “kid” header field.

Health

The service must provide an endpoint which should run on the same node/pod as the claim provider endpoint. This endpoint will be called periodically by our monitoring system to ensure the heartbeat of all connected systems.

The health endpoint must accept GET requests and return status code 204 No Content, provided it is in a healthy state. All other status codes or exceptions will be treated as failure and eventually cause alarms in our monitoring.

Aggregated Claims

Requested claims, that are typically provided by a Claims Provider, are represented by using special _claim_names and _claim_sources members of the JSON object containing the Claims (see https://openid.net/specs/openid-connect-core-1_0.html#AggregatedDistributedClaims).

Normal Claims

In special use cases it might happen that the JWT of the aggregated claims cannot be read by the client. Therefore a claim provider can be configured to write the claims directly to the ID token. Since this does not comply with the OIDC specification, this variant is only allowed in well justified individual cases.

Example

{
  "sub": "ionos:iam:hosting::users/127d43ca-aee2-410c-9168-04bda0ee9fbc-maileu",
  "iss": "https://id.ionos.com",
  …
  "https://example.com/claims/somestring": "123",
  "https://example.com/claims/somenumber": 99,
  "https://example.com/claims/someobject": {
    "type": "basic"
  }
}