DENIC ID Implementation Guide

DENIC ID is part of a Single Sign-On solution based on the ID4me-Standard. Within the ID4me ecosystem, the DENIC ID service assumes the role of an ID authority.

This implementation guide contains information on key business processes and integrations for prospective ID agents. It will address the following topics:

  1. Introduction to the ID4me ecosystem
  2. Agent-Authority integration using the Agent Identity Management (AIM) API
  3. Agent claims provider endpoints
  4. Relying Party implementation

Introduction to the ID4me ecosystem

ID4me standard

The ID4me standard defines a federated platform for online digital identity services. The standard is based on OpenID Connect and performs two main functions:

  1. Authenticate users to access websites supporting ID4me-based logins (Single Sign-On)
  2. Share a user’s personal data with the party who is requesting authentication in a privacy-compliant way, offering a user granular control about which data is being shared

ID4me adds two main components to the existing OpenID Connect standard:

  1. Introduce a separation of roles for entities storing a user’s personal data and those managing user authentication, thus allowing a user to maintain their digital identity even if they decide to switch their identity agent.
  2. Link ID4me-based identities to domain names and the DNS, offering users a persistent identity handle based on a domain name, and using specific TXT resource records in the DNS to allow for discovery who is managing a specific identity. In contrast to so-called social media logins, which are typically based on a single identity provider within a closed system, this DNS-based discovery mechanism opens up ID4me to be interoperable between many ID agents and even ID authorities.

It is important to understand that the identity is the unique representation of a user with an ID authority (typically a unique id), whereas an identifier is a memorable handle, based on a human-readable domain name, that is linked to an identity. Users provide their identifier when logging in, while all user-related information should be stored under their identity. The assignment of an identifier to an identity may change (for example, if a user changes their domain name), while the underlying identity and all connected accounts remain the same.

We strongly recommend to review the ID4me Technical Overview document for a detailed technical discussion of the ID4me standard. In this guide, we will focus only on the most relevant aspects necessary to understand the agent implementation while communicating with DENIC as the ID authority.

Roles and Responsibilities

The federated nature of the ID4me ecosystem includes the following roles:

Role Responsibilities Example
User Any user of the internet requesting authorized access to a service. May be an individual, an organization or an machine/IoT instance marc.denic.de
Relying Party / Login partner A online service provider who accepts ID4me-based logins for users to sign up and/or get access, and who may retrieve a user’s personal data from the user’s identity agent Login partner
Identity Authority Allows agents to create ID4me identities on behalf of their customers, manages user authentication and consent to data sharing DENIC ID
Identity Agent Owns the digital identity customer relationship, creates ID4me identities with the ID authority, manages personal user data and shares consented data with relying parties You

The following chart outlines relationships between those roles:

Roles and actors

The ID Agent Role

Within the DENIC ID implementation of the ID4me framework, the ID agent has a strong relationship with DENIC ID authority, based on a legal agreement between the parties and a dedicated API integration.

The ID agent has the following responsibilities:

Customer relationship

When we think of a federated digital identity based on the ID4me standard, it is the agent that packages the different components of this identity into a product or service, and offers this service to a customer. In the context of DENIC ID, the agent owns the customer relationship, and would typically need to have the following in place:

Identity registration and management at authority

Agents interact with the DENIC ID authority to register an identity for their users, and manage this identity through its lifecycle. The AIM API supports all identity management processes between agent and authority (see below for details).

DNS setup and ACME challenge

During registration of an identity, the ID authority will verify that the owner of the domain name has authorized its use as an identifier using an ACME DNS challenge. The AIM API supports all agent-authority interaction related to the ACME challenge process (see below for details).

Refer users to ID authority for initial credentials setup

Once an identity has been created, the agent needs to refer the user to the ID authority to complete the credentials (e.g. password) setup process. Agents do not manage authentication information themselves, and the user will interact directly with the ID authority to set up their authentication information.

Collect and store personal user data

A key responsibility of ID agents is to manage the personal profile data for ID users, in the following referred to as claims. DENIC ID requires agents to support a standard set of claims, which users should have the opportunity to provide their personal information for. The agent is considered to be the safekeeper for this information.

Provide claim information to relying parties based on access tokens

As a core element of the ID4me ecosystem, ID agents share claim information for identities that they manage with login partners (the ID4me standard refers to those as relying parties). Which claim information may be shared is based on user consent. In order to obtain claim information, relying parties provide an access token to the ID agent that includes the claim elements the user has consented to share, and it is signed by the ID authority. The ID agent needs to provide a discoverable endpoint for relying parties to post access tokens, and return the user-consented claim information to relying parties.

Receive login notifications from ID authority (optional)

In order to allow users to keep track of who requested a login authorization and/or claim information using their identifier, the ID authority will provide a notification callback to the ID agent for each login transaction. The ID agent may provide this information to the user.

Support DENIC ID based logins as relying parties (optional)

Customers who obtained an identity from an agent may want to be able to use it to also get access to their account with the ID agent. In order to support that, ID agents may consider to also implement the relying party component of the ID4me ecosystem, which enables identity authentication with the ID authority.

Agent-Authority integration using the Agent Identity Management (AIM) API

DENIC provides an API for Agent Identity Management, or AIM, that supports all business processes required to manage identities between ID agent and DENIC as ID authority.

Those who are more familiar with OpenID Connect or the ID4me standard may notice that some of the functions provided by the AIM API are also available through calls directly based on the standard. The DENIC ID authority implementation expands on the standard by establishing a persistent relationship between agent and authority, and introducing some additional parameters and capabilities. The AIM API intends to provide all of this functionality in a single framework.

API framework

The API follows RESTful API concepts where possible (and sensible).

The interface description language used is the Swagger Specification version 2.0 (also known as OpenAPI) : http://swagger.io/

Integration of OpenAPI and JWS for authentication/non-repudiation has been inspired by the Open Banking Specification: https://openbanking.atlassian.net/wiki/spaces/DZ/overview

Swagger documentation of individual API commands is available here.

Business processes in the identity lifecycle

  1. Agent creation
  2. ID registration
  3. ACME challenge and DNS setup
  4. Initial password setup
  5. Password reset via agent
  6. ID deletion

Agent creation

As a new ID agent, you begin your integration with DENIC ID authority by creating your agent account. In parallel, DENIC requires ID agents to sign and return the DENIC ID agent agreement. Once the account has been created, and the agreement has been received and validated, your agent account will be activated.

Please see the chart below for a visual representation of this process.

agent creation process

To create an agent account, use the POST /agents command.

To query the status of an existing agent account, use the GET /agents/{agentId} command.

ID registration

Once the agent account set up has been completed, you can proceed to register an identity with DENIC ID.

The ID registration process works as follows:

  1. Typically the user selects an identifier for the identity (e.g. marc.denic.de)
  2. You submit a request for the creation of an identity to the ID authority using the POST /authz command. This generates and returns an authorization object that, when approved, will create the identity at the authority, and therefore needs to include all parameters for this identity.
  3. The ID authority returns an ACME token within said authorization object in pending status.
  4. This unique one-time token will be needed to generate an authorization key that has to be inserted into the DNS resource record for the domain or host which the identifier is based on (for details on the ACME challenge process see below)
  5. Once DNS has been updated and the aforementioned record is globally visible, use the POST /authz/{authzId} command to notify the ID authority.
  6. The authority will synchronously try to finalize the authorization (this involves DNS resolution and cryptographic operations) and answer accordingly with the updated authorization object (status changed to valid or invalid)

Please see the chart below for a visual representation of this process.

identity registration process

ACME Challenge and DNS setup

DENIC IDs are using identifiers that are based on domain names. During the identity setup process, the sponsoring agent of an identity needs to ensure that the user has control over the corresponding domain, and has set up its DNS record with the required ID4me discovery parameters.

To verify domain control, the ID4me standard requires the ID authority to complete an ACME DNS challenge, otherwise known from automated digital certificate setup processes, before activating a corresponding identifier for an identity. To facilitate this challenge, the ID authority is providing the agent with a token, and the agent will use this token to generate and add an ACME resource record to the domain’s zone file, or provide the user with the information on how to set up their DNS.

For an identifier marc.denic.de, for instance, a DNS record with the following information is required to complete the ACME challenge:

domain: denic.de

_acme-challenge | marc | TXT | abce1234lkjsdf

The string that needs to be inserted into the acme-challenge resource record is a hash of the the acme token provided by the authority concatenated with the fingerprint of the agent’s account key. The result is then base64 encoded before it is inserted into the resource record. We are not explaining the details of this process here, as you would typically use an existing ACME client library to generate this string. Please refer to the ACME specification for details on how to solve the DNS challenge with the server provided token.

This ACME resource record can be removed from the zone as soon as the corresponding authorization has been finalized.

To allow for authority and agent discovery for an identifier, the ID4me standard requires an additional resource record to be added to the corresponding domain. This record is a TXT type record for the identifier prefixed (or rather, scoped) with the label _openid, and it allows to resolve the ID authority (issuer or iss in OpenID Connect terminology) and the ID agent (claims provider or clp) managing a specific identity.

The ID4me discovery resource record includes three parameters, each separated by a semicolon:

Parameters Meaning Example
v OpenID Version OID1
iss Issuer / ID authority id.denic.de
clp Claims provider / ID agent identityagent.de

For an identifier marc.denic.de, for instance, the following record is required:

domain: denic.de

marc | _openid | TXT | v=OID1;iss=id.denic.de;clp=identityagent.de

The discovery record is required to remain in the DNS for that domain throughout the lifetime of an identifier.

DENIC ID does not honor the “clp” value found in the DNS record and relies for that purpose on its internal mapping to the agent that currently manages the identifier.

Initial password setup

Once the identity has been created and the ACME challenge has been completed successfully, it is time for the user to set up authorization credentials for their identity with DENIC ID. This process is completed in a direct interaction between ID authority and user. The agent is only involved in the beginning of this process, by forwarding a unique URL provided by the ID authority to the user.

As soon as the authorization has successfully been finalized (valid status), the identity is being created by the ID authority and the agent can use the GET /identities/{id4me} command to query identity details. These details include the URL for the user to set up initial credentials. This link can only be used once and has to be visited by the user within N hours before it expires.

Please see the chart below for a visual representation of the password setup process.

password setup process

Password reset via agent

ID authority stores the sponsoring agent for an identity, which is an expansion of the ID4me standard which in itself has no concept of a persistent authority-agent relationship for a specific identity. One reason for the DENIC ID service to store a persistent agent relationship is to facilitate a password reset process that allows the agent to better support their customers.

In order to trigger a password reset, the agent needs to validate that whoever is requesting this reset is in fact authorized to make requests on behalf of this identity, and then use the POST /identities/credentialsReset command to request a password reset URL from the ID authority. The authority response will include such URL, and the agent needs to provide this URL to the user, so that they can reset their password directly with the authority.

Please see the chart below for a visual representation of a password reset via the agent.

password reset via agent

When setting up their credentials with DENIC ID, users do have the option to opt-out of the password reset via agent process if password recovery information is present for their ID. If a user choses to opt-out, they still have the option to reset their credentials directly with the ID authority (without any agent involvement). Please see chart AIM#4b for details on this process.

ID deletion

In case a user cancels their identity service with an ID agent, the agent can use the DELETE /identities/{identifier}/{identity} command to delete an identity. Prior to the deletion, the agent needs to ensure that ID4me discovery resource records have been removed from the DNS for all identifiers that are used with this ID.

When the ID authority processes the deletion, all ID tokens issued for this identity that have not yet expired will be invalidated. At this time, a deletion of an ID request is final, and there is no restore process available yet.

Please see the chart below for a visual representation of this process.

identity deletion process

There are currently no processes in place yet to add or remove an identifier from an existing identity, or to transfer an identity between agents. These functionalities may be added as additional features in the future.

Agent claims provider endpoint

As discussed previously in this document, ID agents also provide claim information to relying parties based on access tokens. The process for an ID agent to receive an access token and return claim information follows the standards described in OpenID Connect and OAuth 2.0, and ID4me has not applied any changes or extensions to this process.

To give those who are not familiar with OpenID Connect a better understanding of the context in which ID agents need to provide a claims provider endpoint, the following describes the most important steps of a user authentication flow in the ID4me framework (this process is described in more detail when we discuss the relying party implementation).

  1. A user requests access to a relying party service and submits their identifier.
  2. The relying party uses the ID4me DNS-based discovery mechanism to determine the sponsoring ID authority and ID agent for this identifier.
  3. The relying party requests authorization for the identifier and, optionally, access to a set of claims at the sponsoring ID authority.
  4. The relying party redirects the user to an authentication URL provided by the ID authority.
  5. The user inserts their authentication information at the ID authority.
  6. If a relying party has requested access to claim information, the ID authority allows the user to consent or decline access to their information.
  7. Upon successful authentication and consent completion, the ID authority provides a code to the relying party.
  8. The relying party will submit this code to the ID authority userinfo endpoint.
  9. The ID authority validates the code and returns an ID token and an access token to the relying party. The ID token validates that the user has been authenticated, and the access token is needed to retrieve claims information. Both tokens are signed by the ID authority.
  10. The relying party then submits this access token to the ID agent userinfo endpoint.
  11. The ID agent validates the access token based on its signature, and returns claim information to the relying party.

For this process to work, ID agents need to implement a UserInfo endpoint as described in the Open ID Connect Core definition.

For valid access tokens sent via a HTTP Get or HTTP Post request to this endpoint, the ID agent needs to return claim information as a JSON object. The standard set of claims to be supported by ID agents is part of the DENIC ID agent agreement, and follows the OpenID Connect standard claim set.

Relying Party implementation

ID agents who have completed the agent part of the implementation may also consider allowing identity customers to use their identity product for authentication with the ID agent itself.

In this document, we will point only to the most important steps of the relying party implementation, as this process is well documented elsewhere. Please review the Relying Party Implementation Guide, as well as the Relying Party API source library.

DNS lookup

The user login flow begins with the user entering their identifier in a ID login input field. As this identifier may have been registered with any ID authority within the ID4me ecosystem, the relying party will first need to resolve the sponsoring ID authority for this identifier via a DNS lookup. This can be done with any DNS lookup mechanism or library.

If no other option is available, DENIC offers a DNS lookup service at https://lookup.freedom-id.de/lookup/marc.denic.de with marc.denic.de being the user’s identifier. The response will be a JSON object that includes a few parameters, two of which are needed for subsequent processing:

    "identityAuthorityURI": "https://id.denic.de",
	"dnssecValidated": "true"

The identityAuthorityURI parameter indicates the sponsoring ID authority, and dnssecValidated indicates if the underlying DNS zone has been signed with DNSSEC. If you implementing ID logins for production use, we strongly recommend to require the dnssecValidated parameter to be true, or otherwise abort the login request.

ID authority endpoints

Based on the DNS lookup response, you will be able to discover the ID authority endpoints. To do so, use the ID authority URI as discovered in DNS and append .well-known/openid-configuration. In case of DENIC, this URL would look like this: https://id.denic.de/.well-known/openid-configuration

The response again will be a JSON object that returns several parameters, three of which are important for the subsequent workflow:

    "jwks_uri": "https://id.denic.de/jwks.json",
	"authorization_endpoint": "https://id.denic.de/login",
	"token_endpoint": "https://id.denic.de/token",
	"registration_endpoint": ""https://id.denic.de/clients"

Client registration

If a relying party has discovered an ID authority that they have never interacted with before, they first need to register with this authority using the OpenID Connect Dynamic Client Registration process.

The registration process will result in a clientId and a password, which are required for subsequent login requests. Also, the relying party will need to specify a redirect_uri, which is used as a callback address to which the ID authority will redirect a user after they have completed the login process. While this parameter is also part of each login request, it is required during the registration process as well. The redirect_uri used during registration must match the redirect_uri provided in each login request for a request to be valid.

Authentication workflow

Once a relying party is registered with an ID authority, they will be able to submit user authentication requests. The login workflow is described in detail at https://openid.net/specs/openid-connect-core-1_0.html#CodeFlowSteps. Many OpenID Connect code libraries have implemented this flow, please see this list of certified libraries.

The authentication request is being sent as a GET request to the authorization_endpoint (e.g. “https://id.denic.de/login") and will include the following parameters:

Once the user has inserted their correct authentication credentials and the authentication workflow has been completed successfully, the ID authority will return a code to the relying party:

HTTP/1.1 302 Found
  Location: https://client.example.org/cb?
    code=SplxlOBeZQQYbYS6WxSbIA
    &state=af0ifjsldkj

This code needs to be submitted to the token_endpoint (see above), and will return an ID token and an access token, as well as the URL of the sponsoring agent’s *userinfo endpoint**, which is required in a later step.

ID token

The ID token is a JWS which is base64 coded. After it has been decoded, the payload will be similar to the below:

{
  "sub": 
"4AOKNFYHf55AXmbmr9VLuoQ2+x0AtXsKe6m3m5Vxlei+1gh6tJLeXnt76MAGfcXd",
  "aud": "freedom-shop",
  "id4me.identifier": "marc.denic.de",
  "amr": [
    "pwd"
  ],
  "iss": "https://id.denic.de",
  "exp": 1551434145,
  "iat": 1551433245
}

This token needs to be validated according to https://openid.net/specs/openid-connect-core-1_0.html#IDTokenValidation.

During validation, please ensure the following:

  1. The token signature needs to be valid and may not be expired. To validate, obtain the authorities public key from jwks_uri (see above, e.g. “https://id.denic.de/jwks.json"). There will be several keys at this location, please use the key with the kid that matches the one from the JWS header.
  2. “iss” is https://id.denic.de (in case you only wish to accept authentications from DENIC ID authority)
  3. “aud” matches the relying party’s client ID
  4. “id4me.identifier” matches the identifier that the relying party intended to authenticate
  5. The current time is between “iat” and “exp”

Once validation has been completed, the relying party can consider the user to be authenticated and proceed with obtaining claim information using the access token.

Retrieving claims using the access token

During the authentication workflow, the ID authority has requested user consent for all claims that were requested by the login partner as part of their authentication request. Based on the user’s actual consent choice, the access token that has been returned by the ID authority will include information about which claims a relying party is eligible to retrieve.

The access token is a signed JSON Web Token and specifies which claims the relying party may access based on the user’s consent. Please see the following JSON payload example:

{
    "client_id": "abc-relyingparty",
    "clm": [
        "id4me.extended_claim",
        "zoneinfo",
        "birthdate",
        "email_verified",
        "updated_at",
        "given_name",
    ],
    "exp": 1550754669,
    "iat": 1550754069,
    "id4me.identifier": "marc.denic.de",
    "iss": "https://id.denic.de",
    "jti": "nyVAE2tujJs",
    "scope": [
        "openid"
    ],
    "sub": "4AOKNFYHf55AXmbmr9VLuoQ2+x0AtXsKe6m3m5Vxlei+1gh6tVLeXnt76MAGfcXd"
    }

In this token, parameters have the following meaning: * client_id, sub, scope are used according to the OpenID Connect standard * exp, iat, jti, iss are used according to RFC 7519 * “clm” is a JSON array that includes the list of user-consented claims. ID4me specific claims have a id4me.* prefix. * “id4me.identifier” ist a proprietary claim that includes the ID4me identifier.

In order to retrieve claim information, the relying party needs to present this access token to the ID agent userinfo endpoint. The URL of this endpoint is provided to the relying party along with the access token (see above). The authority uses locally stored information for this URL, and does not rely on the clp parameter in the _openid DNS resource record.

The ID agent then validates the access token based on its signature, and returns information for those claims which the user has consented to and that the ID agent has on file to the relying party.

With the receipt of the claims information from the ID agent, the relying party completes the user authentication process.