Info e-teenuse arendajatele

HarID uses OpenID Connect with OAuth 2.0 protocol for authentication and authorization. First, obtain OpenID Connect/OAuth client credentials from HarID administrators.

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 system administrator 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).

OpenID/OAuth technical info

Technical configuration parameters in JSON format:

You can get the latest info for test environment at: https://test.harid.ee/.well-known/openid-configuration
{
    "issuer": "https://test.harid.ee",
    "authorization_endpoint": "https://test.harid.ee/et/authorizations/new",
    "jwks_uri": "https://test.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://test.harid.ee/et/access_tokens",
    "userinfo_endpoint": "https://test.harid.ee/et/user_info",
    "registration_endpoint": "https://test.harid.ee/et/connect/client",
    "scopes_supported": [
       "personal_code", "phone", "address", "email", "profile", "openid", "roles"
    ], "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" ]
}

Live environment: https://harid.ee/.well-known/openid-configuration (not operational yet)

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": "e22defaf-d118-4c55-bb29-059e4c8e21e3",
  "name": "MARY ÄNN O’CONNEŽ-ŠUSLIK",
  "email": "example@example.com",
  "email_verified": true,
  "locale": "et_EE",
  "personal_code": "EE:EID:11412090004",
  "personal_code_verified": true,
  "roles": [
    {
      "marker": "student",
      "active": true,
      "start_date": "2018-01-10",
      "end_date": null,
      "name_et": "student",
      "name_en": "Student",
      "name_ru": "student",
      "desc_et": "",
      "desc_en": "",
      "desc_ru": "",
      "provider_reg_nr": "75014445",
      "provider_name": "Keila ühisgümnaasium",
      "created_at": "2018-01-10T16:43:34+02:00",
      "updated_at": "2018-01-10T18:12:24+02:00",
      "student_grade": "6",
      "student_parallel": "A"
    }
  ]
}

Attributes:

`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.
`name`	The user's full name.
`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_verified`	True if the user's e-mail address has been verified; otherwise false.
`ui_locales`	Indicates user preferred user interface locales, example: 'et' for Estonia or 'et en' where Estonia would be preferred over English.
`personal_code`	Mostly Estonia's identity code. Always have prefix with 2 colons. Example EE:EID:11412090004
`personal_code_verified`	User has logged into HarID using strong authentication method such as Mobile-ID or ID-card.
`roles`	User roles, user can have multiple roles
`roles:marker`	Uniq identifier, example 'student'
`roles:active`	Defines, if role is valid. Only roles with value "true" are valid.
`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: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:name_et`	Role name in Estonian
`roles:name_en`	Role name in English
`roles:name_ru`	Role name in Russian
`roles:desc_et`	Role description in Estonian
`roles:desc_en`	Role description in English
`roles:desc_ru`	Role description in Russian
`roles:provider_reg_nr`	Provider's (institution (school)) registration number
`roles:provider_name`	Provider (example school) name
`roles:created_at`	Role creation time, format: ISO8601
`roles:updated_at`	Role updated time, format: ISO8601
`roles:student_grade`	Only present when user has 'stundet' role, provides grade, example value: '6'
`roles:student_parallel`	Only present when user has 'stundet' role, provides class parallel info, example: 'A'