adapter_error_handling.xml

<!--
  ~ Copyright 2016 Red Hat, Inc. and/or its affiliates
  ~ and other contributors as indicated by the @author tags.
  ~
  ~ Licensed under the Apache License, Version 2.0 (the "License");
  ~ you may not use this file except in compliance with the License.
  ~ You may obtain a copy of the License at
  ~
  ~ http://www.apache.org/licenses/LICENSE-2.0
  ~
  ~ Unless required by applicable law or agreed to in writing, software
  ~ distributed under the License is distributed on an "AS IS" BASIS,
  ~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  ~ See the License for the specific language governing permissions and
  ~ limitations under the License.
  -->

<chapter id="adapter_error_handling">
    <title>Error Handling</title>
    <para>
        Keycloak has some error handling facilities for servlet based client adapters.  When an error is encountered in
        authentication, keycloak will call <literal>HttpServletResponse.sendError()</literal>.  You can set up an error-page
        within your <literal>web.xml</literal> file to handle the error however you want.  Keycloak may throw
        400, 401, 403, and 500 errors.
    </para>
    <para>
<programlisting>
<![CDATA[
<error-page>
    <error-code>404</error-code>
    <location>/ErrorHandler</location>
</error-page>]]>
</programlisting>
    </para>
    <para>
        Keycloak also sets an <literal>HttpServletRequest</literal> attribute that you can retrieve.  The attribute name
        is <literal>org.keycloak.adapters.spi.AuthenticationError</literal>.  Typecast this object to:
        <literal>org.keycloak.adapters.saml.SamlAuthenticationError</literal>.  This class can tell you exactly what happened.
        If this attribute is not set, then the adapter was not responsible for the error code.
    </para>
    <para>
<programlisting>
public class SamlAuthenticationError implements AuthenticationError {
    public static enum Reason {
        EXTRACTION_FAILURE,
        INVALID_SIGNATURE,
        ERROR_STATUS
    }

    public Reason getReason() {
        return reason;
    }
    public StatusResponseType getStatus() {
        return status;
    }
}
</programlisting>
    </para>
</chapter>