Authentication and Authorization error callbacks
Version: 1.0 updated 6/9/2022
Overview of error codes - their meaning and use
| Error code | Use | HTTP Status code |
|---|---|---|
| invalid_request | IdP returns this error if one of the required parameters is missing in the request (eg nonce, state,…). It is also returned if the value of the parameter is invalid and the request cannot be executed except for exceptions specified by its own error code. See the following error codes. The error can be used even if an unsupported authentication or authorization method is required (for example, a POST and IdP request only supports GET). For status 400, this is an error state without redirect. | 302, 400, see individual elements |
| unauthorized_client | If it is not possible to issue an authentication result for the given client and used grant variant. For code_grant flow without session management, eg in case of using invalid client_id. Error state without redirect. | 400 |
| access_denied | Returns when authentication or authorization has not been completed based on a user action. Individual cases: authentication incomplete by the end user or consent page rejected by the end user or authorization incomplete by the end user. | 302 |
| unsupported_response_type | Returns if the requested response_type is not supported or is not registered in the dynamic registration for the given client_id. | 400 |
| invalid_scope | Returns if an unsupported scope is requested or if any of the required scopes are not registered for the client_id used. Also returned in case of missing mandatory scope "openid" | 302 |
| server_error | Returns in the event of an unforeseen server error. Error state without redirect. | 500 |
| temporarily_unavailable | Returns if the server is temporarily too busy to return a response to the request. Error state without redirect. | 503 |
| interaction_required | It is returned if an authentication or authorization request with the parameter prompt=none was requested and it could not be completed without the end user interaction. This can be, for example, a request to enter a payment account at the payment authorization, or another type of entry. It is returned if it is an interaction request other than a login or confirmation of consent. | 302 |
| login_required | It is returned if an authentication or authorization request with the parameter prompt = none was requested and it could not be completed without the end user interaction. This can happen, for example, when a user session expires on an IdP. | 302 |
| account_selection_required | It is returned if an authentication or authorization request with the parameter prompt=none was requested and it could not be completed without the end user interaction. This can happen if the user has a valid session with the IdP, but more than one login account (eg with a different scopes range) and the end user is required to make a selection. | 302 |
| consent_required | It is returned if an authentication or authorization request with the parameter prompt=none was requested and it could not be completed without the end user interaction. This can happen if there is a valid session, the user can log in, but confirmation of consent to the scopes is required. | 302 |
| invalid_request_uri | The error indicates that an invalid request_uri was used in the authentication or authorization request: request_uri is not registered in the IdP (eg via ros endpoint or dynamic registration), request_uri cannot be retrieved or its content is invalid | 302 |
| invalid_request_object | The submitted request_uri is correctly registered and available, but contains an invalid value. | 302 |
| request_uri_not_supported | Occurs when an authentication or authorization request containing request_uri has been sent to the server, but the server does not support this type of request. The idP must have it in /openid-configuration that it does not support request_uri. | 302 |
| registration_not_supported | This error is returned by IdP if the optional parameter registration was used in the authentication flow and IdP does not support this form of dynamic registration. | 302 |
| eid_doesnt_exist | This error is returned by the IdP if the end user does not have an identity corresponding to the required Bank iD parameters. Eg: if the used Bank Identity is not registered with the NIA (National Identity Authority) or if the Bank Identity that does not meet the requirements | 302 |
Callbacks identical across IdPs
| Error code | Error message | Usage |
|---|---|---|
| access_denied | User declined the authentication | The IdP returns this error if the user refused to log in at the federated login screen. |
| access_denied | User declined consent | The IdP returns this error if the user refused to give consent to access data by a third party. |
| eid_doesnt_exist | User not eligible | The IdP returns this error if the user is not eligible to have Bank iD. |
| eid_doesnt_exist | User disabled authentication | The IdP returns this error if the user can't use his Bank iD due to different reasons, for example, has it turned off. |
| user_not_eligible | User authentication method insufficient | The IdP returns this error if the user can't use authentication method with sufficient security level for QSIGN service (eg. SMS). |
| user_not_eligible | Insufficient user data or age restriction | The IdP returns this error if the user is not eligible to use service QSIGN due to age restriction or missing required data (eg. e-mail, phone). |
Overview of undocumented error codes - their meaning and use
We've encountered some undocumented error codes from some IdPs.
| Error code | Use | IdP |
|---|---|---|
| not_found | The IdP returns this error if a client_id that is not registered with the bank is used in the request. | MMB |
| not_found | The IdP returns this error if a a request for /userinfo endpoint has scopes which is not in line with documentation. | RB |
The /auth or /authorize request parameters and their effect on errors
Description of individual parameters from the auth request with error variants that can be called for these parameters.
| Parameter | May cause an error | HTTP Status code | Error code specification |
|---|---|---|---|
| request_uri | invalid_request_uri | 302 | |
| invalid_request_object | 302 | ||
| request_uri_not_supported | 302 | ||
| invalid_request | 302 | Missing request_uri in /authorize request | |
| redirect_uri | invalid_request | 400 | In case of missing parameter |
| invalid_request | 302 | In case of an invalid parameter value in relation to client_id | |
| client_id | invalid_request | 400 | In case of missing parameter |
| unauthorized_client | 302 | In case of invalid value client_id (unknown client_id) | |
| response_type | invalid_request | 400 | In case of missing parameter |
| unsupported_response_type | 400 | ||
| id_token_hint | login_required | 302 | In combination with prompt=none, or prompt=consent |
| interaction_required | 302 | ||
| account_selection_required | 302 | ||
| consent_required | 302 | ||
| nonce | invalid_request | 302 | In case of missing parameter in Bank iD solution |
| state | invalid_request | 302 | In case of missing parameter in Bank iD solution |
| scope | invalid_request | 302 | In case of missing parameter |
| invalid_scope | 302 | ||
| display | invalid_request | 302 | In case of missing parameter |
| invalid_request | 302 | In case of an invalid value, eg outside the supported types specified in the oidc | |
| prompt | invalid_request | 302 | In case of missing parameter |
| invalid_request | 302 | In case of an invalid value, eg outside the supported types specified in the oidc | |
| acr_values | invalid_request | 302 | In case of an invalid value, eg outside the supported types specified in the oidc |
| max_age | invalid_request | 302 | In case of incorrect format or out of range |
| response_mode | invalid_request | 302 | In case of an invalid value, eg outside the supported types listed in the documentation. |
| ui_locales | invalid_request | 302 | In case of invalid value |
| claims | invalid_request | 302 | In case of invalid value or invalid format. |
Examples of error requests and responses
Incorrectly specified scope
Request
GET https://oidc.bankid.cz/auth?redirect_uri=https%3A%2F%2Fsomeadr.com%2Fcallback%2Fconsent&scope=profile.phonenumber%20profile.birthnumber%20profile.gender%20profile.titles%20profile.birthplaceNationality%20profile.name%20profile.idcards%20profile.locale%20profile.maritalstatus%20profile.verification%20profile.legalstatus%20profile.email%20offline_access%20profile.addresses%20profile.birthdate&response_type=code&state=some%20state&nonce=26b6&prompt=login&display=page&acr_values=loa3 HTTP/1.1
Response
HTTP/1.1 302 Found
Location: http://someadr.com/callback?error=invalid_scope&error_description=Mandatory%20scope%20openid%20is%20missing&state=some%20state
Missing client_id
Request
GET https://oidc.bankid.cz/auth?client_id=4c7d5457&redirect_uri=https%3A%2F%2Fsomeadr.com%2Fcallback%2Fconsent&scope=profile.phonenumber%20profile.birthnumber%20profile.gender%20profile.titles%20profile.birthplaceNationality%20profile.name%20profile.idcards%20profile.locale%20profile.maritalstatus%20profile.verification%20profile.legalstatus%20profile.email%20offline_access%20profile.addresses%20profile.birthdate&response_type=code&state=some%20state&nonce=26b6&prompt=login&display=page&acr_values=loa3 HTTP/1.1
Response
HTTP/1.1 302 Found
Location: http://someadr.com/callback?error=invalid_request&error_description=Mandatory%20parameter%20client_id%20is%20missing&state=some%20state
Invalid client_id
Request
GET https://oidc.bankid.cz/auth?client_id=4c7d5457&redirect_uri=https%3A%2F%2Fsomeadr.com%2Fcallback%2Fconsent&scope=profile.phonenumber%20profile.birthnumber%20profile.gender%20profile.titles%20profile.birthplaceNationality%20profile.name%20profile.idcards%20profile.locale%20profile.maritalstatus%20profile.verification%20profile.legalstatus%20profile.email%20offline_access%20profile.addresses%20profile.birthdate&response_type=code&state=some%20state&nonce=26b6&prompt=login&display=page&acr_values=loa3 HTTP/1.1
Response (without redirect)
HTTP/1.1 400 Bad Request
ContentType: application/json
{
"error": "unauthorized_client",
"error_description": "This client_id cannot be used"
}