Authentication and Authorization error callbacks

Version: 1.0 updated 6/9/2022

Overview of error codes - their meaning and use

Error codeUseHTTP Status code
invalid_requestIdP 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_clientIf 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_deniedReturns 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_typeReturns if the requested response_type is not supported or is not registered in the dynamic registration for the given client_id.400
invalid_scopeReturns 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_errorReturns in the event of an unforeseen server error. Error state without redirect.500
temporarily_unavailableReturns if the server is temporarily too busy to return a response to the request. Error state without redirect.503
interaction_requiredIt 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_requiredIt 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_requiredIt 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_requiredIt 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_uriThe 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 invalid302
invalid_request_objectThe submitted request_uri is correctly registered and available, but contains an invalid value.302
request_uri_not_supportedOccurs 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_supportedThis 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_existThis 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 requirements302

Callbacks identical across IdPs

Error codeError messageUsage
access_deniedUser declined the authenticationThe IdP returns this error if the user refused to log in at the federated login screen.
access_deniedUser declined consentThe IdP returns this error if the user refused to give consent to access data by a third party.
eid_doesnt_existUser not eligibleThe IdP returns this error if the user is not eligible to have Bank iD.
eid_doesnt_existUser disabled authenticationThe 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_eligibleUser authentication method insufficientThe IdP returns this error if the user can't use authentication method with sufficient security level for QSIGN service (eg. SMS).
user_not_eligibleInsufficient user data or age restrictionThe 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 codeUseIdP
not_foundThe IdP returns this error if a client_id that is not registered with the bank is used in the request.MMB
not_foundThe 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.

ParameterMay cause an errorHTTP Status codeError code specification
request_uriinvalid_request_uri302
invalid_request_object302
request_uri_not_supported302
invalid_request302Missing request_uri in /authorize request
redirect_uriinvalid_request400In case of missing parameter
invalid_request302In case of an invalid parameter value in relation to client_id
client_idinvalid_request400In case of missing parameter
unauthorized_client302In case of invalid value client_id (unknown client_id)
response_typeinvalid_request400In case of missing parameter
unsupported_response_type400
id_token_hintlogin_required302In combination with prompt=none, or prompt=consent
interaction_required302
account_selection_required302
consent_required302
nonceinvalid_request302In case of missing parameter in Bank iD solution
stateinvalid_request302In case of missing parameter in Bank iD solution
scopeinvalid_request302In case of missing parameter
invalid_scope302
displayinvalid_request302In case of missing parameter
invalid_request302In case of an invalid value, eg outside the supported types specified in the oidc
promptinvalid_request302In case of missing parameter
invalid_request302In case of an invalid value, eg outside the supported types specified in the oidc
acr_values ​​invalid_request302In case of an invalid value, eg outside the supported types specified in the oidc
max_ageinvalid_request302In case of incorrect format or out of range
response_modeinvalid_request302In case of an invalid value, eg outside the supported types listed in the documentation.
ui_localesinvalid_request302In case of invalid value
claimsinvalid_request302In 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"
}