Welcome to the official documentation for Authentigate, a platform designed to enable e-services (Relying Parties) to request verified information about users in an automatic, secure, and GDPR-compliant manner. Authentigate is a robust identity verification platform that allows Relying Parties to securely request and receive verified personal information about users. This process is streamlined through the OpenID Connect (OIDC) protocol, ensuring seamless integration with various e-services.
This documentation will guide you through the integration, configuration, and use of Authentigate service. Whether you're a developer, a relying party, or simply interested in learning more, this documentation is your gateway to harnessing the power of our service. Let's get started on this journey to better authentication and data security.
- Attribute - Any piece of information related to a person that can be optionally shared during an OIDC authentication transaction, providing additional user details.
- Authentigate - A service developed by SK to offer attribute storage, calculation and sharing functionalities, allowing for the secure and controlled exchange of user information during authentication.
- RP (Relying Party) - An organization or service that utilizes the SK authentication gateway service to authenticate its users and verify their age.
- OIDC (OpenID Connect) - A protocol used for central authentication, facilitating secure user verification and attribute sharing.
- Fast and Secure Information Sharing: Relying Parties can quickly receive verified user data, while users retain full transparency over which information is being shared.
- Easy Integration: Connecting to the OIDC portal is simplified through a single integration based on the OpenID Connect protocol. The unified API supports various authentication methods, such as Smart-ID, Mobile-ID and another.
- GDPR Compliance: Relying Parties can request only the information they need, helping them remain GDPR-compliant.
Authentigate currently supports multiple eID authentication methods in different regions:
- Latvia: Smart-ID
- Lithuania: Smart-ID and Mobile-ID
- Estonia: Smart-ID, Mobile-ID, and ID-Card
Authentigate is also planning to expand its range of supported eID solutions in the future to enhance coverage and accessibility across more regions and use cases. Using the acr_value parameter, a relying party can specify which countries and authentication methods (e.g., Smart-ID, Mobile-ID, ID-Card) should be offered to the end user during the authentication process.
Authentigate allows Relying Parties to request various verification attributes such as:
- User Identification: personal code, given name, family name, full name, birthdate.
- Age Verification: age, age over, age under.
Important
To initiate the registration process, we kindly request you to get in touch with our Sales team. You can find their contact information on our Contact Us page.
Each client has to be registered with the following required info:
| Parameter | Required | Description | Info | Example | Default |
|---|---|---|---|---|---|
| name | Yes | Client full name, shown in frontend. | Sample RP | ||
| ip-patterns[] | Yes | A list of allowed IP patterns allowed for this client to access /token and /par endpoints. | 192.168.12.*, 192.168.* |
||
| redirect-uri[] | Yes | A list of allowed callback URIs whitelisted for this client. | 1 or many URIs | https://sample-rp.ee/callback | |
| sector-identifier-uri | No | HTTPS URL that points to a JSON file containing an array of the client's redirect_uri values. |
Required if multiple redirect_uris are registered |
https://sample-rp.ee/redirecti_uris.json | |
| logo | No | Logo encoded in base64, preferably svg for removing issues with different user screen resolutions. | base64 string | ||
| background-color | No | Frontend background color, in hex format. | #ff0000 |
||
| scope | No | A list of allowed scopes for this client. | If not specified, then all scopes are allowed | openid, age_under |
|
| allowed-countries[] | No | A list of allowed countries this client. | EE, LV, LT |
||
| jwks[] | No | A list of JWK public keys to be used for validation in case 'private_key_jwt' authentication method is chosen. |
The Authentigate service supports two endpoints for initiating authentication:
- Authorization endpoint (/authorize), using POST or GET request after which the user is redirected to login service at OIDC_SERVICE/login.
- Pushed Authentication Request, PAR (/par) where Authentigate service validates the POST request and responds with a URI for starting authentication.
OIDC requests are initiated via PAR (pushed authentication request). For this, a POST request with
content type application/x-www-form-urlencoded is sent to OIDC_SERVICE/par with the request body.
Example 1: Request person's full name and a verification that the person is over 18 years old:
{
"response_type": "code",
"client_id": "CLIENT_ID",
"redirect_uri": "REDIRECT_URI",
"state": "STATE",
"nonce": "NONCE",
"scope": "openid name age_over",
"acr_values": "mid mid_ee mid_lt sid sid_ee sid_lv sid_lt idcard idcard_ee",
"age_comparator": "18",
"code_challenge": "CODE_CHALLENGE",
"code_challenge_method": "S256",
"sid_confirmation_message": "FREETEXT",
"mid_confirmation_message": "FREETEXT",
"mid_confirmation_message_format": "GSM-7"
}Example 2: Request person's given name, family name, and age:
{
"response_type": "code",
"client_id": "CLIENT_ID",
"redirect_uri": "REDIRECT_URI",
"state": "STATE",
"nonce": "NONCE",
"scope": "openid given_name family_name age",
"acr_values": "mid mid_ee mid_lt sid sid_ee sid_lv sid_lt idcard idcard_ee",
"code_challenge": "CODE_CHALLENGE",
"code_challenge_method": "S256",
"sid_confirmation_message": "FREETEXT",
"mid_confirmation_message": "FREETEXT",
"mid_confirmation_message_format": "GSM-7"
}| Parameter | Required | Value | Description |
|---|---|---|---|
| scope | Yes | Must contain 'openid'. Other possible scopes can be retrieved from /.well-known/openid-configuration | Static value required by OIDC core protocol and additional user information relying party needs. Separated by spaces |
| age_comparator | No (Yes, when scope includes age_over or age_under) |
Integer | Specifies against which age should comparison be made |
| response_type | Yes | Must be 'code' | The authorization code flow is used |
| client_id | Yes | Relying-party ID | A pre-registered relying-party identifier |
| redirect_uri | Yes | Relying-party callback URL | A pre-registered relying party callback URL |
| state | Yes | Unique random string | RP generated opaque value used to maintain state between the request and the callback. Can be used to mitigate replay and CSRF attacks |
| nonce | Yes | Unique random string | RP generated unique string. If provided, will be returned as a nonce claim in the id_token. Can be used to mitigate replay attacks |
| ui_locales | No | Must be one of et, en, lv, lt (or multiple in order of importance, separated by spaces) | End-User's preferred language for authentication. Determines the language used on the login page. The first found match with supported values will be set as the app language. If not set (or none are supported), app tries to determine the UI language from browser data etc. and defaults to 'en', if detection fails. |
| code_challenge | No (Yes, in case of basic authentication) |
Base64 encoded hash of a unique challenge. | Base64 encoded hash of a unique challenge. The code-challenge is created by SHA256 hashing the code_verifier and base64 URL encoding the resulting hash Base64UrlEncode(SHA256Hash(code_verifier)). You can view an example from https://tonyxu-io.github.io/pkce-generator/. NB! Must be present if not using JWT authentication. |
| code_challenge_method | No (Yes, in case of basic authentication) |
Must be 'S256'. | The algorithm by which the challenge shall be verified on the server side. Must be present if client 'code-challenge-required' is true or if not using JWT authentication. |
| sid_confirmation_message | No | String with information for users for the SID authentication app | Free text (max length 200 characters) value shown to Smart-ID users in the app during code choice. This can be the name of your service or provide more detailed info about the current interaction (like users name or order number etc). |
| mid_confirmation_message | No | String with information for users for the MID authentication app | Free text (max length 40 characters for 'GSM-7', 20 characters for 'UCS-2') value shown to Mobile-ID users before asking authentication PIN. |
| mid_confirmation_message_format | No | Must be one of GSM-7, UCS-2 | Specifies which characters and how many can be used in 'mid_confirmation_message'. GSM-7 allows 'mid_confirmation_message' to contain up to 40 characters from standard GSM 7-bit alpabet including up to 5 characters from extension table ( €[]^|{}\ ) . UCS-2 allows up to 20 characters from UCS-2 alpabet (this has all Cyrillic characters, ÕŠŽ šžõ and ĄČĘĖĮŠŲŪŽ ąčęėįšųūž). |
| acr_values | No | Space separated string containing one or more of the following values: 'mid', 'mid_ee', 'mid_lt', 'sid', 'sid_ee', 'sid_lv', 'sid_lt', 'idcard', 'idcard_ee' | Optional value specifying authentication methods to be usable by the end-user. Order of provided values affects the presentation of authentication options to the end-user. Acr values that appear earlier will be prioritized. Example order: 'mid_lt mid_ee sid_lv sid_lt sid_ee' - LT (MID, SID), EE (SID, MID), LV (SID) |
The oidc-service shall validate the authentication request and respond with a URI that the public client can use to start authentication:
HTTP/1.1 201 Created
Cache-Control: no-cache, no-store
Content-Type: application/json
{
"request_uri": "urn:ietf:params:oauth:request_uri:8Tw6nn6BAvoHBS5VM7M1UvndAAHdM5",
"expires_in": 90
}
Please pay attention that client id and client secret should be passed in Authorization header of /par request in a format that OAuth 2.0 foresees for client secret authorization method.
According to OAuth 2.0 framework, Authorization header must be in the Authorization: Basic encodedString format, where the encodedString is a result of Base64 encoding of OAuth client’s clientID:clientSecret.
Using the returned link, the app can open end-user's browser with the corresponding url.
The app should open the link with an external user agent as recommended by current OAuth2 for native clients best practices:
GET /authorize?client_id=EinLKYAAMqPr2Tw &request_uri=urn:ietf:params:oauth:request_uri:8Tw6nn6BAvoHBS5VM7M1UvndAAHdM5
After this, the user is redirected to the login service (located at OIDC_SERVICE/login)
OIDC requests are initiated via authorization endpoint. For this POST or GET request can be used.
POST request with content type application/x-www-form-urlencoded with the request body:
{
"response_type": "code",
"client_id": "CLIENT_ID",
"redirect_uri": "REDIRECT_URI",
"state": "STATE",
"nonce": "NONCE",
"scope": "openid",
"acr_values": "mid mid_ee mid_lt sid sid_ee sid_lv sid_lt idcard idcard_ee"
"code_challenge": "CODE_CHALLENGE",
"code_challenge_method": "S256",
"sid_confirmation_message": "FREETEXT",
"mid_confirmation_message": "FREETEXT",
"mid_confirmation_message_format": "GSM-7"
}GET request with Query string
OIDC_SERVICE/authorize?scope=openid&response_type=code&redirect_uri=REDIRECT_URI&state=STATE&nonce=NONCE&code_challenge=CODE_CHALLENGE&code_challenge_method=S256
| Parameter | Required | Value | Description |
|---|---|---|---|
| scope | Yes | Must contain 'openid'. Other possible scopes can be retrieved from /.well-known/openid-configuration | Static value required by OIDC core protocol and additional user information relying party needs. Separated by spaces |
| age_comparator | No (Yes, when scope includes age_over or age_under) |
Integer | Specifies against which age should comparison be made |
| response_type | Yes | Must be 'code' | The authorization code flow is used |
| client_id | Yes | Relying-party ID | A pre-registered relying-party identifier |
| redirect_uri | Yes | Relying-party callback URL | A pre-registered relying party callback URL |
| state | Yes | Unique random string | RP generated opaque value used to maintain state between the request and the callback. Can be used to mitigate replay and CSRF attacks |
| nonce | Yes | Unique random string | RP generated unique string. If provided, will be returned as a nonce claim in the id_token. Can be used to mitigate replay attacks |
| ui_locales | No | Must be one of et, en, lv, lt (or multiple in order of importance, separated by spaces) | End-User's preferred language for authentication. Determines the language used on the login page. The first found match with supported values will be set as the app language. If not set (or none are supported), app tries to determine the UI language from browser data etc. and defaults to 'en', if detection fails. |
| code_challenge | No (Yes, in case of basic authentication) |
Base64 encoded hash of a unique challenge. | Base64 encoded hash of a unique challenge. The code-challenge is created by SHA256 hashing the code_verifier and base64 URL encoding the resulting hash Base64UrlEncode(SHA256Hash(code_verifier)). You can view an example from https://tonyxu-io.github.io/pkce-generator/. NB! Must be present if not using JWT authentication. |
| code_challenge_method | No (Yes, in case of basic authentication) |
Must be 'S256'. | The algorithm by which the challenge shall be verified on the server side. Must be present if client 'code-challenge-required' is true or if not using JWT authentication. |
| sid_confirmation_message | No | String with information for users for the SID authentication app | Free text (max length 200 characters) value shown to Smart-ID users in the app during code choice. This can be the name of your service or provide more detailed info about the current interaction (like users name or order number etc). |
| mid_confirmation_message | No | String with information for users for the MID authentication app | Free text (max length 40 characters for 'GSM-7', 20 characters for 'UCS-2') value shown to Mobile-ID users before asking authentication PIN. |
| mid_confirmation_message_format | No | Must be one of GSM-7, UCS-2 | Specifies which characters and how many can be used in 'mid_confirmation_message'. GSM-7 allows 'mid_confirmation_message' to contain up to 40 characters from standard GSM 7-bit alpabet including up to 5 characters from extension table ( €[]^|{}\ ) . UCS-2 allows up to 20 characters from UCS-2 alpabet (this has all Cyrillic characters, ÕŠŽ šžõ and ĄČĘĖĮŠŲŪŽ ąčęėįšųūž). |
| acr_values | No | Space separated string containing one or more of the following values: 'mid', 'mid_ee', 'mid_lt', 'sid', 'sid_ee', 'sid_lv', 'sid_lt', 'idcard', 'idcard_ee' | Optional value specifying authentication methods to be usable by the end-user. Order of provided values affects the presentation of authentication options to the end-user. Acr values that appear earlier will be prioritized. Example order: 'mid_lt mid_ee sid_lv sid_lt sid_ee' - LT (MID, SID), EE (SID, MID), LV (SID) |
After this, the user is redirected to the login service (located at OIDC_SERVICE/login) |
A standard HTTP 302 authentication response redirect is returned to the end-user if a successful authentication session exists. The redirect points user's browser back to RP's registered redirect_uri where the RP shall verify the value of the state parameter.
HTTP/1.1 302 Found Location: https://client.example.org/callback?code=GaqukjWp4vvzEWHnLW7phLlwkpB0 &state=WDm4nExm1ADHzIEwoPxQ0KjBwnnk6NIrq178fU4rBDU
| Parameter | Required | Value | Description |
|---|---|---|---|
| code | Yes | unique random string | A single-use, client-bound, short-lived authorization code, that can be used at OIDC token endpoint to redeem the id-token. |
| state | Yes | unique random string | RP's state parameter value specified in the Authorization Request |
| redirect_uri | Yes | URL | RP's redirect_uri specified in the Authorization Request |
Upon receiving the authorization code from the successful authentication response and having performed all checks required by OIDC core specification (state, csrf), the RP backend service posts a backchannel request to the oidc-service token endpoint.
- Using
client_secret_basicauthentication:
POST /token HTTP/1.1
Host: oidc.demo.sk.ee
Content-Type: application/x-www-form-urlencoded
Authorization: Basic c2FtcGxlX2NsaWVudF8xOjNkc8OEMDIrMSwubTExMmxrMjPDtmxrw7ZsazMyMw
grant_type=authorization_code
&code=GaqukjWp4vvzEWHnLW7phLlwkpB0
&code_verifier=yJhbGciOiJSUzI1NiIsImtpZ
&redirect_uri=https%3A%2F%2Fclient.example.org%2Fcallback
or
- Using
private_key_jwtauthentication:
POST /token HTTP/1.1
Host: oidc.demo.sk.ee
Content-Type: application/x-www-form-urlencoded
grant_type=authorization_code
&code=GaqukjWp4vvzEWHnLW7phLlwkpB0
&code_verifier=yJhbGciOiJSUzI1NiIsImtpZ
&client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer
&client_assertion=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.ewogICJqdGkiOiAiY2ZiMDM5NGEtY2JlOS00MGE4LWEyNDQtZmNlM2Y0MTljNmRhIiwKICAic3ViIjogImJhbmsxMjMiLAogICJpc3MiOiAiYmFuazEyMyIsCiAgImF1ZCI6ICJodHRwczovL2F1dGguc2suZWUvdG9rZW4iLAogICJleHAiOiAxNzE0OTM3NjEwLAogICJpYXQiOiAxNzE0MDM3NjEwCn0=.zK6oUoDcxm-9w7hYpI8-IYlJr55k-S0LY0XvKDdBsuz8AJnZ6JEFS3GS_04SNVP02dqHq44ZGUbpRxkkAOJ8Su2zn7iJGaqr_MLchxddQiYYpHdOiKYqIQ-Yn3oleTlHed0ci84Kh7-BEQB_u7nv2-76wOe339OrHZuNeqejmGeQtMG7vzX5PMDF4wLjvrAxTIptTBKBWLGO02RusEI4uAC-4FrMjjbM4Ygc8U_i8BtZ-Is2FptJlpIAqjMTvGQZdEfenNZWzmVTYn9qKJ3ArXPZg5R07vqsx2YpMenXjbBc5TRS2FTVskwWvfTZn9_ygVvwR1wAzfNNfp7XPcQuUg
&redirect_uri=https%3A%2F%2Fclient.example.org%2Fcallback
| Parameter | Required | Value | Description |
|---|---|---|---|
| grant_type | Yes | Must be authorization_code |
Static value required by the OIDC core protocol. |
| code | Yes | Unique random string | Authorization code value returned from the OIDC-service |
| code_verifier | No | Unique random string | High-entropy cryptographic random string. Related to code-challenge given in par request. Must be present if client 'code-challenge-required' is true or if not using JWT authentication. |
| client_assertion_type | No | If present, must be 'urn:ietf:params:oauth:client-assertion-type:jwt-bearer' | Static value required by the OIDC core protocol. Must be present only if 'client_assertion' field is also present. |
| client_assertion | No | Valid signed JWT | Must contain a single valid JSON Web Token. Must be present only if 'client_assertion_type' field is also present. |
| redirect_uri | Yes | URL | Must be identical to the parameter value that was included in the initial Authorization Request |
Authorization: basic auth with client-id and client-secret; only required in case of client_secret_basic authentication method. Header must not be
present in case of private_key_jwt authentication method.
The JSON response contains a signed JWT in the field id_token that contains claims about the authenticated end-user:
HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache
{
"access_token": "SlAV32hkKG",
"token_type": "Bearer",
"refresh_token": null,
"expires_in": 3600,
"id_token": "eyJhbGciOiJSUzI1NiIsImtpZ...LrLl0nx7RkKU8NXNHq-rvKMzqg"
}
| Parameter | Value | Description |
|---|---|---|
| access_token | Unique random string | An opaque random string |
| token_type | Bearer |
Access token type. Will be Bearer |
| scope | openid age_under | Requested scopes |
| id_token | JWT | A serialized and signed JWT with end-user claims |
The RP must validate the id_token signature and claims as specified in the OIDC core specification.
| Claim | Description |
|---|---|
| sub | Pairwise subject unique identifier |
| given_name, family_name, ... etc | Standard claims that describe the end-user |
| jti | A unique identifier for the token, which can be used to prevent reuse of the token. |
| iss | Issuer URL. Issuer identifier for the issuer of the response. |
| aud | Audience that this ID Token is intended for. Contains the Relying Party ID as an audience value. |
| iat | Time at which the JWT was issued. |
| exp | Expiration time on or after which the ID Token MUST NOT be accepted for processing. |
| nonce | String value. Used to associate a Client session with an ID Token, and to mitigate replay attacks. |
| amr | Authentication Methods References. |
| acr | Authentication Context Class Reference. |
| age_comparator | Age value used in age_over/age_under attribute comparison. |
| attributes.* | List of requested attributes and their values. |
| HTTP status code | Error code | Description | Parameter causing the error |
|---|---|---|---|
| 400 | invalid_request | Missing scope parameter | scope |
| 400 | invalid_request | The scope must include an openid value | scope |
| 400 | invalid_request | Missing response_type parameter | response_type |
| 400 | invalid_request | Unsupported response_type parameter: Unsupported OpenID Connect response type value: invalid_type | response_type |
| 400 | invalid_request | Missing client_id parameter | client_id |
| 400 | invalid_request | Missing redirect_uri parameter | redirect_uri |
| 400 | invalid_request | Missing state parameter | state |
| 400 | invalid_request | Missing nonce parameter | nonce |
| 400 | invalid_request | Invalid acr values: . Supported values are: " | acr_values |
| 400 | invalid_request | Invalid acr_values provided. Client: <client_id> is not allowed to use acr [] | acr_values |
| 400 | invalid_request | Missing code_challenge parameter | code_challenge |
| 400 | invalid_request | Missing code_challenge_method parameter | code_challenge_method |
| 400 | invalid_request | Parameter value for code_challenge_method is not supported. Supported values are: S256 | code_challenge_method |
| 400 | invalid_request | SID confirmation message too long | sid_confirmation_message |
| 400 | invalid_request | MID confirmation message too long | mid_confirmation_message |
| 400 | invalid_request | Missing mid_confirmation_message_format parameter | mid_confirmation_message_format |
| 400 | invalid_request | mid_confirmation_message_format must be one of: GSM-7, UCS-2 | mid_confirmation_message_format |
| 400 | invalid_request | Missing age_comparator parameter when using age_over or age_under scope | age_comparator |
| 400 | invalid_scope | The requested scope is invalid. Client: [<client_id>] is not allowed to request scope value(s): [] | scope |
| 400 | unsupported_response_type | The authorization server does not support obtaining an authorization code using this method | response_type |
| 401 | invalid_client | Client authentication failed (e.g., unknown client, no client authentication included, or unsupported authentication method) | client_id |
| HTTP status code | Error code | Description |
|---|---|---|
| 405 | invalid_request | Method [{0}] not allowed for URI [/par]. Allowed methods: [POST] |
| 413 | invalid_request | The content length [{0}] exceeds the maximum allowed content length [{1}] |
| 415 | invalid_request | Content Type [{0}] not allowed. Allowed types: [application/x-www-form-urlencoded] |
| 429 | too_many_requests | Too many pending PAR requests |
| 500 | server_error | The authorization server encountered an unexpected condition that prevented it from fulfilling the request |
| HTTP status code | Error code | Description |
|---|---|---|
| 400 | invalid_request | Request_uri invalid or expired |
| 400 | user_cancel | User canceled authentication |