Skip to main content

Attributes reference

itsme® allows you to verify the identity of your end-users and obtain relevant personal details. On this page, you find information about what end-user attributes are available for a given authentication protocol.

Note

The use of the Belgian RRN (national identity number) is subject to specific legislation, which might require that you obtain specific authorisation by FOD/SPF IBZ. For more details, refer to the applicable laws (for example, this one or other updated, applicable laws).

Available attributes​

Attributes (known as scopes in OIDC) allow your application to specify the desired set of user data to request and verify for each identity verification process. The attributes you request depend on the user information you need to fulfil the scope of your application. The scope is linked to the itsme® service you want to use.

After the end-user consents to sharing the requested attributes and completes an identity verification process, you can retrieve their personal details.

itsme® services​

itsme® services are a way to group attributes together to address different scenarios for digital identity. The three possible services you can choose are:

  • Authentication
  • Identification
  • Signing

The attributes you specify in an authorization request determine which itsme® service to use in an end-user authentication. The tables on this page show the attributes to use to trigger a service.

Detailed information about user data

For details about the itsme® services offered by Signicat and the user data available, visit the User data section in the About itsme® documentation.

Subject ID for logins​

The subject ID (returned in the sub attribute) uniquely identifies a given user account. It is a critical attributes for correctly identifying users who have already registered with your digital service.

Key characteristics of the subject ID are:

  • Uniqueness: No two users will ever have the same sub value.
  • Persistence: The sub for a user account does not change over time. This holds true even if other user attributes, such as their email address or phone number, are updated.

Your application server must use the subject ID to recognise and log in end-users returning to your application.

Learn more about the subject field in Concepts > Subject.

OIDC scopes and claims​

In OIDC, you specify scopes in the authorization request that triggers an identity verification flow.

After the end-user verifies themselves and the flow is complete, you can retrieve the claims in the ID Token or through the UserInfo endpoint.

OIDC Authentication service​

Use any combination of the following OIDC scopes in your request to perform an itsme® Authentication service:

Important

Mixing scopes for Authentication and Identification in your request defaults the process to an Identification service.


For example, a request with name, date-of-birth and nin leads to an Identification service.

OIDC Identification service​

Use any combination of the following OIDC scopes in your request to perform an itsme® Identification service:

Data in the response

Note that itsme® may not return values for some of the claims. When a claim is not returned, the corresponding data is omitted from the JSON object of the response.

Country coverage

itsme® returns a subset of claims data for documents issued in countries other than Belgium. For details, visit the official documentation of claims at https://belgianmobileid.github.io/doc/claims/.

OIDC response example​

ID token:

{
  "iss": "https://<YOUR_SIGNICAT_DOMAIN>/auth/open",
  "nbf": 1712237928,
  "iat": 1712237928,
  "exp": 1712238528,
  "aud": "<OIDC_CLIENT_ID>",
  "amr": [
    "external"
  ],
  "at_hash": "0zAbHkX...IeNDhkFoWlhKg",
  "sid": "8930E9EC6FAF...874DF7BA6FC907383",
  "sub": "tXOq9614vLHkXBkE...ZGQO02Fc98IPaHq6iRwK-ytA=",
  "auth_time": 1712237927,
  "idp": "itsme",
  "email": "test@itsme.be",
  "phone_number": "+32 453519681",
  "name": "Maxence Legrand",
  "family_name": "Legrand",
  "given_name": "Maxence",
  "gender": "female",
  "birthdate": "1981-04-24",
  "address": {
    "formatted": "Rue Royale 82 1000 Bruxelles"
  },
  "nationality": "BEL",
  "idp_issuer": "https://idp.e2e.itsme.services/v2",
  "transaction_id": "355f42c4-a1ec-a...-87af-1eaad9a89435",
  "sandbox": true
}

UserInfo:

{
  "idp_id": "rpx5rrbsn4ktvh...q4uh2iepsdat34i9vf",
  "name": "Maxence Legrand",
  "family_name": "Legrand",
  "given_name": "Maxence",
  "gender": "female",
  "birthdate": "1981-04-24",
  "email": "test@itsme.be",
  "address": {
    "formatted": "Rue Royale 82 1000 Bruxelles",
    "street_address": "Rue Royale 82",
    "locality": "Bruxelles",
    "postal_code": "1000"
  },
  "phone_number": "+32 453519681",
  "nin": "81042419835",
  "nin_type": "PERSON",
  "nationality": "BEL",
  "sub": "tXOq9614vLHkXBkE...ZGQO02Fc98IPaHq6iRwK-ytA=",
  "idp_issuer": "https://idp.e2e.itsme.services/v2"
}

Signicat Authentication REST API attributes​

The Signicat Authentication REST API supports the following request attributes for itsme®.

REST API Authentication service​

Use any combination of the following attributes in your request to perform an itsme® Authentication service:

Important

Mixing attributes for Authentication and Identification in your request defaults the process to an Identification service.


For example, a request with name, dateOfBirth and nin leads to an Identification service.

REST API Identification service​

Use any combination of the following attributes in your request to perform an itsme® Identification service:

Data in response

Note that itsme® may not return values for some of the attributes. When an attribute is not returned, the corresponding data is omitted from the JSON object of the response.

Country coverage

itsme® returns a subset of the data for documents issued in countries other than Belgium. For details, visit the official documentation of claims at https://belgianmobileid.github.io/doc/claims/.

Authentication API response example​

Here is a section of the response showing the user information attributes:

{
    ...
    "subject": {
        "id": "tXOq9614vLHkXBkENWcZGQO02Fc98IPaHq6iRwK-ytA=",
        "idpId": "rpx5rrbsn4ktvhm3m0q4uh2iepsdat34i9vf",
        "name": "Maxence Legrand",
        "firstName": "Maxence",
        "lastName": "Legrand",
        "dateOfBirth": "1981-04-24",
        "nin": {
            "value": "81042419835",
            "issuingCountry": "BE",
            "type": "PERSON"
        },
        "address": "Rue Royale 82 1000 Bruxelles",
        "placeOfBirth": "Bruxelles",
        "nationality": "BEL",
    },
    ...
}
Subject ID and login

The subject ID (subject.id field in the JSON response) uniquely identifies a given user account. The subject ID does not change over time, even if other user attributes (for example email or phone number) associated with a user account might change.


Your application should use the subject ID (id field in the JSON of the response) to log in end-users returning to your application. You do this by matching the incoming subject ID with the subject ID you received in previous authentications.


Learn more about the subject field in Concepts > Subject.

SAML 2.0 attributes​

SAML Authentication service​

Use any combination of the following attributes in your request to perform an itsme® Authentication service:

Important

Mixing attributes for Authentication and Identification in your request defaults the process to an Identification service.


For example, a request with name, dateOfBirth and nin leads to an Identification service.

SAML Identification service​

Any combination of the following attributes start the itsme® Identification service:

Data in response

Note that itsme® may not return values for some of the attributes. When an attribute is not returned, the corresponding data is omitted from the JSON object of the response.

Country coverage

itsme® returns a subset of the data for documents issued in countries other than Belgium. For details, visit the official documentation of claims at https://belgianmobileid.github.io/doc/claims/.

SAML 2.0 response example​

The following SAML response contains the outcome of an Identification service with attributes nin, name, email, nationality, idpId:

<?xml version="1.0" encoding="UTF-8"?>
<saml2p:Response xmlns:saml2p="urn:oasis:names:tc:SAML:2.0:protocol" Destination="https://*SP_CLIENT_DOMAIN*/saml/acs" ID="_79c74fabd7a896ee879729c92ca6c231" InResponseTo="_064f5303e14c84a59d7eaa24b6cd3558" IssueInstant="2024-04-04T11:56:12.648Z" Version="2.0" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <saml2:Issuer xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion">
        https://*YOUR_SIGNICAT_DOMAIN*/auth/saml
    </saml2:Issuer>
    <ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
        ...
    </ds:Signature>
    <saml2p:Status>
        <saml2p:StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:Success"/>
    </saml2p:Status>
    <saml2:Assertion xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion" ID="_d9da2112740b886681bf7da6185d986f" IssueInstant="2024-04-04T11:56:12.657Z" Version="2.0" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
        <saml2:Issuer>
            https://*YOUR_SIGNICAT_DOMAIN*/auth/saml
        </saml2:Issuer>
        <ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
        XML_SIGNATURE
        </ds:Signature>
        <saml2:Subject>
            <saml2:NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified" NameQualifier="https://idp.e2e.itsme.services/v2">
                tXOq9614vLHkXBkENW...QO02Fc98IPaHq6iRwK-ytA=
            </saml2:NameID>
            <saml2:SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer">
                <saml2:SubjectConfirmationData InResponseTo="_064f5303e14c84a59d7eaa24b6cd3558" NotOnOrAfter="2024-04-04T11:58:12.657Z" Recipient="https://*SP_CLIENT_DOMAIN*/saml/acs"/>
            </saml2:SubjectConfirmation>
        </saml2:Subject>
        <saml2:Conditions NotBefore="2024-04-04T11:56:07.657Z" NotOnOrAfter="2024-04-04T11:58:12.657Z">
            <saml2:AudienceRestriction>
                <saml2:Audience>ENTITY_ID</saml2:Audience>
            </saml2:AudienceRestriction>
        </saml2:Conditions>
        <saml2:AttributeStatement>
            <saml2:Attribute Name="name">
                <saml2:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xsd:string">
                    Maxence Legrand
                </saml2:AttributeValue>
            </saml2:Attribute>
            <saml2:Attribute Name="nin">
                <saml2:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xsd:string">
                    81042419835
                </saml2:AttributeValue>
            </saml2:Attribute>
            <saml2:Attribute Name="nin.type">
                <saml2:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xsd:string">
                    PERSON
                </saml2:AttributeValue>
            </saml2:Attribute>
            <saml2:Attribute Name="email">
                <saml2:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xsd:string">
                    test@itsme.be
                </saml2:AttributeValue>
            </saml2:Attribute>
            <saml2:Attribute Name="idpId">
                <saml2:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xsd:string">
                    rpx5rrbsn4ktvhm3m0...uh2iepsdat34i9vf
                </saml2:AttributeValue>
            </saml2:Attribute>
            <saml2:Attribute Name="nationality">
            <saml2:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xsd:string">
                    BEL
                </saml2:AttributeValue>
            </saml2:Attribute>
        </saml2:AttributeStatement>
        <saml2:AuthnStatement AuthnInstant="2024-04-04T11:56:12.657Z" SessionIndex="fbd7098e-f7bd-4291-820a-70c9c2c0dff0">
            <saml2:AuthnContext>
                <saml2:AuthnContextClassRef>
                    urn:oasis:names:tc:SAML:2.0:ac:classes:SmartcardPKI
                </saml2:AuthnContextClassRef>
                <saml2:AuthenticatingAuthority>
                    https://idp.e2e.itsme.services/v2
                </saml2:AuthenticatingAuthority>
            </saml2:AuthnContext>
        </saml2:AuthnStatement>
    </saml2:Assertion>
</saml2p:Response>
On this page