Keycloak Error Responses Guide

Purpose:

The purpose of this document is to explain the Object structure returned by Keycloak Adapter in case of an error and list of responses received on different type of Errors.

Error Object Structure:

When we are dealing with the Process of Authentication and Authorization of users via Keycloak, we make request to Keycloak for the given tasks using Keycloak Adapter. In case there are some issues with User Request i.e. Wrong Hostname, Wrong Credentials, Invalid Request Data etc., keycloak returns an Error Object to User containing information about specific error and its error code that provides useful info to User to correct the request. The returned User Object Structure is as follows:

Keycloak Error Object Strcture

JS

{
   error_message: User_Written_Error_Message,
   error_detail: {
        status: Error_Code,
        reason: Error_Message_Returned_By_Keycloak_API
   }
}

In the above Error Object we receive 2 main Attributes i.e error_message and error_detail.

Attribute

Value

error_message

String encapsulating a message that precisely identifies the moment in the Keycloak Adapter Process when the error occurred.

Example: Error Occurred While Fetching User Details During Login Process

error_detail

Object containing the information regarding actual Error. This object has 2 attributes

status: The code of the occurred error. Three-digit numbers that are returned by a server in response to a client's request made to a web page or resource.
It provide information about the status of the request and help us identify the type of error.

reason: A brief message regarding the Actual Error
example: No User exists against provided Username: ${user_name}

Commonly Occuring Error in Keycloak Adapter and Its Responses:

Below is the table containing commonly occuring errors in Keycloak and their responses.

Error	Reason	error_message	status (error_detail)	reason (error_detail)
Wrong Hostname	The Hostname/URL of provided Keycloak Instance in Keycloak Adapter Config is incorrect. Property in Keycloak Config File: auth-server-url	Error Occurred While Generating User Access Token	404	Hostname Not Found, Keycloak server unaccessable against Keycloak URL. Unable to resolve Hostname, This maybe due to wrong Host URL or DNS server issue
Wrong Realm Name	Either the provided Realm Name is incorrect/has typo or the Realm doesn't exist in Keycloak Instance. Property in Keycloak Config File: realm	Error Occurred While Generating User Access Token	404	Realm is not valid in Keycloak Config, please provide a valid Keycloak Realm
Wrong Client Name	Either the provided Client Name is incorrect/has typo or the Client doesn't exist in Keycloak Instance. Property in Keycloak Config File: resource, CLIENT_ID	Error Occurred While Generating User Access Token	400	CLIENT_ID value is not valid in Keycloak Config, please provide a valid CLIENT_ID
Wrong Client Secret	Provided Client Secret is Incorrect. Property in Keycloak Config File: credentials.secret, CLIENT_DB_ID	Error Occurred While Generating User Access Token	401	CLIENT_SECRET (credentials.secret in Keycloak Config) value is not valid in Keycloak Config, please provide a valid CLIENT_SECRET
Reference Error	Error Occurs due to the wrong Programming logic, missing functions or variables or due to type in code.	Error Occurred While Generating User Access Token	ReferenceError	Some variable or function either hasn't been declared or is out of scope
RPT Token Issue	This Error Occurs when the initial Access token is fetched during Login process but introspect token call is unsuccessful.	Error while fetching RPT token, Please make sure all required Roles,Permissions & Groups are assigned to User. e.g: Agent user must be assigned agent role, agents_permission group & all required permissions are created Every user must be assigned one team, if user is not part of any Team then assign default team to User	401	Not Authorized.

Above Provided Errors are the most Complex errors that occur during Keycloak login process. There are many more errors that occur during Keycloak Adpater functionality process but those are simple errors and could be understood and resolved easily using Keycloak Admin Console.