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 strongly encourage 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. Please review OpenID Connect libraries for additional information.

Technical configuration parameters in JSON format:

Test environment: https://test.harid.ee/.well-known/openid-configuration
Live environment: https://harid.ee/.well-known/openid-configuration

 

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.

OpenID/OAuth technical info

Technical configuration parameters in JSON format:

You can get the latest info for live environment at: 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": [

      ]
    }
  ]
}

}

Attributes:

NB! If client does not require scope, HarID does not return scope 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
personal_code	personal_code_verified	User has at least once in history logged into HarID using strong authentication method such as Mobile-ID or ID-card.
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	User roles, user can have multiple roles
roles	roles:marker	Uniq identifier, example 'student'
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	personal_code_verified	Child user has either verified at least once his/her account with strong authetication or personal code comes form Rahvastikuregister
custodies	roles	Same attributes as main role attributes.