KEYCLOAK-853 Documentation for login modules

docbook/reference/en/en-US/master.xml

@@ -18,6 +18,7 @@
                 <!ENTITY InstalledApplications SYSTEM "modules/installed-applications.xml">
                 <!ENTITY Logout SYSTEM "modules/logout.xml">
                 <!ENTITY SAML SYSTEM "modules/saml.xml">
+                <!ENTITY JAAS SYSTEM "modules/jaas.xml">
                 <!ENTITY SocialConfig SYSTEM "modules/social-config.xml">
                 <!ENTITY SocialFacebook SYSTEM "modules/social-facebook.xml">
                 <!ENTITY SocialGitHub SYSTEM "modules/social-github.xml">
@@ -97,6 +98,7 @@ This one is short
         &InstalledApplications;
         &Logout;
         &MultiTenancy;
+        &JAAS;
     </chapter>
 
     <chapter>

docbook/reference/en/en-US/modules/jaas.xml

@@ -0,0 +1,37 @@
+<section id="jaas-adapter">
+    <title>JAAS plugin</title>
+    <para>
+        It's generally not needed to use JAAS for most of the applications, especially if they are HTTP based, but directly choose one of our adapters.
+        However some applications and systems may still rely on pure legacy JAAS solution. Keycloak provides couple of login modules
+        to help with such use cases. Some login modules provided by Keycloak are:
+    </para>
+    <para>
+        <variablelist>
+            <varlistentry>
+                <term>org.keycloak.adapters.jaas.DirectAccessGrantsLoginModule</term>
+                <listitem>
+                    <para>
+                        This login module allows to authenticate with username/password from Keycloak database. It's using
+                        <link linkend="direct-access-grants">Direct Access Grants</link> Keycloak endpoint to validate on Keycloak side if provided username/password is valid.
+                        It's useful especially for non-web based systems, which need to rely on JAAS and want to use Keycloak credentials, but can't use classic browser based
+                        authentication flow due to their non-web nature. Example of such application could be messaging application or SSH system.
+                    </para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>org.keycloak.adapters.jaas.BearerTokenLoginModule</term>
+                <listitem>
+                    <para>
+                        This login module allows to authenticate with Keycloak access token passed to it through CallbackHandler as password.
+                        It may be useful for example in case, when you have Keycloak access token from classic web based authentication flow
+                        and your web application then needs to talk to external non-web based system, which rely on JAAS. For example to JMS/messaging system.
+                    </para>
+                </listitem>
+            </varlistentry>
+        </variablelist>
+    </para>
+    <para>
+        Both login modules have single configuration property <literal>keycloak-config-file</literal> where you need to provide location of keycloak.json configuration file.
+        It could be either provided from filesystem or from classpath (in that case you may need value like <literal>classpath:/folder-on-classpath/keycloak.json</literal> ).
+    </para>
+</section>

integration/adapter-core/src/main/java/org/keycloak/adapters/jaas/BearerTokenLoginModule.java

@@ -6,7 +6,7 @@ import org.keycloak.VerificationException;
 /**
  * Login module, which allows to authenticate Keycloak access token in environments, which rely on JAAS
  * <p/>
- * It expects login based on username and password where username must be equal to "Bearer" and password is keycloak access token.
+ * It expects login based on username and password where username doesn't matter and password is keycloak access token.
  *
  * @author <a href="mailto:mposolda@redhat.com">Marek Posolda</a>
  */