Info e-teenuse arendajatele

HarID uses OpenID Connect with OAuth 2.0 protocol for authentication and authorization. For security implications of getting the implementation correct, we require you to use OAuth 2.0 libraries when interacting with HarID endpoints. Best practice would be to use well written code provided by others - it will help you protect yourself and your users.
 

E-service registration

Before you can start sending OpenID/OAuth requests, you have to register your e-service.
Please contact with HarID support (harid@hitsa.ee) and provide following information:

1. Your organisation name and registration number.
2. Your E-service return urls where HarID forwards back (you can add multiple urls if needed).

After that we can add you to our test-environment (test.harid.ee) and provide you with our OpenID client credentials.


Quick technical configuration parameters in JSON format

Test environment (GET request): https://test.harid.ee/.well-known/openid-configuration
Live environment (GET request): https://harid.ee/.well-known/openid-configuration

 

OpenID/OAuth technical info

Technical configuration parameters in JSON format:

You can get the latest info for test environment at (GET request) : https://test.harid.ee/.well-known/openid-configuration
You can get the latest info for live environment at (GET request): https://harid.ee/.well-known/openid-configuration

{
    "issuer": "https://harid.ee",
    "authorization_endpoint": "https://harid.ee/et/authorizations/new",
    "jwks_uri": "https://harid.ee/jwks.json",
    "response_types_supported": [
        "code", "token", "id_token", "code token", "code id_token", "id_token token", "code id_token token"
    ],
    "subject_types_supported": [ "public" ],
    "id_token_signing_alg_values_supported": [ "RS256" ],
    "token_endpoint": "https://harid.ee/et/access_tokens",
    "userinfo_endpoint": "https://harid.ee/et/user_info",
    "registration_endpoint": "https://harid.ee/et/connect/client",
    "scopes_supported": [
       "personal_code", "phone", "email", "profile", "openid", "roles", "session_type"
    ], "grant_types_supported": [ "authorization_code", "implicit" ],
    "request_object_signing_alg_values_supported": [ "HS256", "HS384", "HS512" ],
    "token_endpoint_auth_methods_supported": [ "client_secret_basic", "client_secret_post" ],
    "claims_supported": [ "sub", "iss", "name", "email", "phone_number", "personal_code", "roles" ]
}

 

Data attributes

Exchange code for access token and ID token:

access_token

A token that can be sent to HarID.

id_token

Identity information (JWT) about the user that is digitally signed by HarID.

expires_in

The remaining lifetime of the access token.

token_type

Identifies the type of token returned. At this time, this field always has the value 'Bearer'.

 

Obtain user information from the ID token:

Example response in json format:

{
  "sub": "5727bdad-6f71-4b99-8730-6d66170afa41",
  "name": "Example User",
  "given_name": "Example",
  "family_name": "User",
  "email": "user@example.com",
  "email_verified": true,
  "personal_code": "EE:EID:50701124378",
  "personal_code_verified": true,
  "strong_session": false,
  "roles": [
    {
      "marker": "student",
      "active": true,
      "start_date": "2018-01-17",
      "end_date": null,
      "name_et": "Õpilane",
      "name_en": "Student",
      "name_ru": "student",
      "desc_et": null,
      "desc_en": null,
      "desc_ru": null,
      "provider_ehis_id": "293",
      "provider_reg_nr": "75014445",
      "provider_name": "Keila ühisgümnaasium",
      "created_at": "2018-01-17T16:25:50+02:00",
      "updated_at": "2018-01-17T16:27:55+02:00",
      "student_grade": "6",
      "student_parallel": "A"
    },
    {
      "marker": "faculty",
      "active": null,
      "start_date": "2018-10-09",
      "end_date": null,
      "name_et": "faculty",
      "name_en": "Faculty",
      "name_ru": "faculty",
      "desc_et": null,
      "desc_en": null,
      "desc_ru": null,
      "provider_ehis_id": "223",
      "provider_reg_nr": "75012452",
      "provider_name": "Ääsmäe põhikool",
      "created_at": "2018-10-09T13:44:13+03:00",
      "updated_at": "2018-10-09T13:44:13+03:00"
    },
    {
      "marker": "library-walk-in",
      "active": null,
      "start_date": "2018-10-09",
      "end_date": null,
      "name_et": "library-walk-in",
      "name_en": "Library-walk-in",
      "name_ru": "library-walk-in",
      "desc_et": null,
      "desc_en": null,
      "desc_ru": null,
      "provider_ehis_id": null,
      "provider_reg_nr": "75012452",
      "provider_name": "Ääsmäe põhikool",
      "created_at": "2018-10-09T13:44:13+03:00",
      "updated_at": "2018-10-09T13:44:13+03:00"
    },
    {
      "marker": "student",
      "active": true,
      "start_date": "2018-12-13",
      "end_date": null,
      "name_et": "student",
      "name_en": "Student",
      "name_ru": "student",
      "desc_et": null,
      "desc_en": null,
      "desc_ru": null,
      "provider_ehis_id": "214",
      "provider_reg_nr": "75004429",
      "provider_name": "Albu põhikool",
      "created_at": "2018-12-13T14:42:40+02:00",
      "updated_at": "2018-12-14T19:13:54+02:00",
      "student_grade": "5",
      "student_parallel": null
    }
  ],
  "ui_locales": "et",
  "custodies": [
    {
      "name": "Hernes Hernes",
      "given_name": "Hernes",
      "family_name": "Hernes",
      "email": "priit.tark+020@gmail.com",
      "email_verified": true,
      "personal_code": "EE:EID:60005050011",
      "personal_code_verified": false,
      "roles": [
        {
          "marker": "student",
          "active": true,
          "start_date": "2018-12-13",
          "end_date": null,
          "name_et": "Õpilane",
          "name_en": "Student",
          "name_ru": "student",
          "desc_et": null,
          "desc_en": null,
          "desc_ru": null,
          "provider_ehis_id": "214",
          "provider_reg_nr": "75004429",
          "provider_name": "Albu põhikool",
          "created_at": "2018-12-13T14:42:40+02:00",
          "updated_at": "2018-12-14T19:13:54+02:00",
          "student_grade": "5",
          "student_parallel": null
        }
      ]
    },
    {
      "name": "Loos Loos",
      "given_name": "Loos",
      "family_name": "Loos",
      "email": "priit.tark+011@gmail.com",
      "email_verified": true,
      "personal_code": "EE:EID:38612232328",
      "personal_code_verified": false,
      "roles": [

      ]
    }
  ]
}
}


NB! If client does not require scope, HarID does not return scope attributes.

All attributes:

Scope Attribute Description
openid

sub

An identifier for the user, unique for HarID accounts and never reused. HarID account can have multiple emails at different points in time, but the sub value is never changed. Use sub within your e-service as the unique-identifier key for the user.

profile

name

The user's full name.

email

email

The user's email address. This may not be unique and is not suitable for use as a primary key. Provided only if your scope included the string "email".

email

email_verified

True if the user's e-mail address has been verified; otherwise false.

profile

ui_locales

Indicates user preferred user interface locales, example: 'et' for Estonia or 'et en' where Estonia would be preferred over English.
personal_code

personal_code

Mostly Estonia's identity code. Always have prefix with 2 colons. Example EE:EID:11412090004
session_type strong_session

True if user user last authentication into HarID was done by using strong authentication method such as Mobile-ID or ID-card. You can use standard way by ID token where "arm" value is either "pwd" (password auth) or "pop" (mobiil-ID/ID-card auth).

roles roles User roles, user can have multiple roles

roles

roles:marker Uniq identifier of user role.
 
'director' => Provider/school director
'faculty' => Provider/school teacher
'student' => Provider/school student
'secretary' => Provider/school secretary
'sysadmin' => Provider/school sysadmin

Three roles are assigned automatically based on EHIS database with following map:
EHIS role 'õpilane' => HarID role 'student'
EHIS role 'õpetaja' => HarID role 'faculty'
EHIS role 'direktor' => HarID role 'director'
Provider sysadmin/secretary can manage user roles directly in HarID portal without EHIS change.
 

roles

roles:active Defines, if role is valid. Only roles with value "true"  are valid.

roles

roles:start_date Role start date. Start date does not define alone, if role is active. Role must be also active with value "true" and start date must be in past to determine you can rely on it.

roles

roles:end_date Role end date. End date does not define alone, if role is active. Role must be also active with value "true" and end date must missing or in the future.

roles

roles:name_et Role name in Estonian

roles

roles:name_en Role name in English

roles

roles:name_ru Role name in Russian

roles

roles:desc_et Role description in Estonian

roles

roles:desc_en Role description in English

roles

roles:desc_ru Role description in Russian

roles

roles:provider_reg_nr Provider's (institution (school)) registration number

roles

roles:provider_name Provider (example school) name

roles

roles:created_at Role creation time, format: ISO8601

roles

roles:updated_at Role updated time, format: ISO8601

roles

roles:student_grade Only present when user has 'stundet' role, provides grade, example value: '6'

roles

roles:student_parallel

Only present when user has 'stundet' role, provides class parallel info, example: 'A'

custodies name String, full name
custodies given_name First name
custodies family_name Family name
custodies email Email
custodies email_verified Boolean, true or false, Child has verified his/her email
custodies personal_code Child personal code
custodies roles Same attributes as main role attributes.

 

NB! If client does not require scope, HarID does not return scope attributes. 

You can test/play with a demo client at https://kool.gitlab.eu
For example, demo client makes request against test HarID  with all scopes as following: GET request:
https://test.harid.ee/et/authorizations/new?client_id=a6095bd2e837af2ef8c69ee87d7028d8&nonce=0d790445152f8b8bca5a847170e987b5&redirect_uri=https%3A%2F%2Fkool.gitlab.eu%2Fproviders%2F2%2Fopen_id&response_type=code&scope=openid+profile+email+personal_code+roles+session_type+custodies&state=0d790445152f8b8bca5a847170e987b5