4.2.6. Performing Authentication (XRDS and realm)

When a user comes to the mojeID endpoint with an identity authentication request from your application, they see a login page where the login takes place.

../../../_images/mojeid-login.png

A dialog for inputting mojeID identifier on mojeID website.

This authentication is performed by the mojeID servers. Within this authentication, we will try to perform as many tasks specified by the parameters in the identity authentication request as possible. The whole process takes place within the mojeID systems and requires no activity from your side.

A part of this process is verification of your return address; the user is informed of its outcome. Another part of this auhentication is the YADIS protocol getting more data about you and verifying them against your data in the message. The correct response to a query from the YADIS protocol returns either an XRDS, or an HTML document in which the XRDS document’s position is disclosed.

4.2.6.1. XRDS Document and its Format

The XRDS document’s position is disclosed by the following META tag in site’s header that you place at the address of your realmat OpenID:

<meta http-equiv="x-xrds-location" content="http://www.example.com/xrds.xml"/>

An example of a custom XRDS document for login into mojeID:

<?xml version="1.0" encoding="UTF-8"?>
<xrds:XRDS xmlns:xrds="xri://$xrds" xmlns="xri://$xrd*($v*2.0)">
  <XRD>
    <Service>
      <Type>http://specs.openid.net/auth/2.0/return_to</Type>
      <URI>http://www.provider-example.com/MojeID-Return.html</URI>
    </Service>
  </XRD>
</xrds:XRDS>

An example of an XRDS document for registration into mojeID:

<?xml version="1.0" encoding="UTF-8"?>
<xrds:XRDS xmlns:xrds="xri://$xrds" xmlns="xri://$xrd*($v*2.0)">
  <XRD>
    <Service>
      <Type>http://specs.openid.net/auth/2.0/assert_url</Type>
      <URI>URL rozhraní</URI>
    </Service>
  </XRD>
</xrds:XRDS>

where the URI tag must include your application’s return address from the identity authentication request. During the whole process of getting the document, your server must not return any redirection (HTTP code 3xx), otherwise the document is considered invalid/forged.

4.2.6.2. Choosing a Suitable Realm

Realm is a unique identifier of the service you provide within the mojeID system, so its correct selection makes orientation for users easier. According to the OpenID specification, the realm should correspond to the part of the URL-space for which the request is valid. In case of login, the realm should not be smaller than the part of URL-space covered by consequently created session.

We therefore recommend to use exactly one realm for one second level-domain. Because two URLs that differ even only by schema are different according to specifications, we strongly recommend using exclusively an HTTPS schema if it is available. This also prevents users’ data interception as they are sent to your application.

If you use only one second-level domain, we recommend choosing a realm in form of https://example.com/ or https://www.example.com/.

Important

The return address must have the same domain as the realm, otherwise the OpenID query is invalid.

If you use third or lower level subdomains, we recommend using substitute symbol * and choose the realm in form of https://*.example.com/. Such realm allows using return addresses with any subdomain, e.g.: https://www.example.com/, https://sub.example.com/return/address/, https://sub.do.main.example.com/, but not with the domain itself (in this case https://example.com/).

The XRDS document will be searched for at the URL where the * symbol is replaced by “www”, i.e. at https://www.example.cz/. All the used forms must be in HTTPS protocol.

Important

The realm must not include an IP address, always use a domain name.