[jboss-cvs] JBossAS SVN: r73470 - in projects/security/security-negotiation/trunk/docs/userguide/src/docbkx/en: modules and 1 other directory.
jboss-cvs-commits at lists.jboss.org
jboss-cvs-commits at lists.jboss.org
Sat May 17 19:17:38 EDT 2008
Author: darran.lofthouse at jboss.com
Date: 2008-05-17 19:17:38 -0400 (Sat, 17 May 2008)
New Revision: 73470
Modified:
projects/security/security-negotiation/trunk/docs/userguide/src/docbkx/en/master.xml
projects/security/security-negotiation/trunk/docs/userguide/src/docbkx/en/modules/general_installation.xml
projects/security/security-negotiation/trunk/docs/userguide/src/docbkx/en/modules/introduction.xml
Log:
[SECURITY-154] General configuration documentation.
Modified: projects/security/security-negotiation/trunk/docs/userguide/src/docbkx/en/master.xml
===================================================================
--- projects/security/security-negotiation/trunk/docs/userguide/src/docbkx/en/master.xml 2008-05-17 22:38:54 UTC (rev 73469)
+++ projects/security/security-negotiation/trunk/docs/userguide/src/docbkx/en/master.xml 2008-05-17 23:17:38 UTC (rev 73470)
@@ -7,7 +7,7 @@
<subtitle>A Guide for Administrators</subtitle>
- <releaseinfo>0.0.0</releaseinfo>
+ <releaseinfo>2.0.3.Beta1</releaseinfo>
<authorgroup>
<author>
Modified: projects/security/security-negotiation/trunk/docs/userguide/src/docbkx/en/modules/general_installation.xml
===================================================================
--- projects/security/security-negotiation/trunk/docs/userguide/src/docbkx/en/modules/general_installation.xml 2008-05-17 22:38:54 UTC (rev 73469)
+++ projects/security/security-negotiation/trunk/docs/userguide/src/docbkx/en/modules/general_installation.xml 2008-05-17 23:17:38 UTC (rev 73470)
@@ -5,8 +5,147 @@
<title>General Installation</title>
<section>
- <title></title>
+ <para>This section of the document describes the general installation
+ process of the negotiation module, the following chapters in this guide
+ describe the specific configuration requirements for the KDC and the web
+ browser.</para>
- <para>Describe the general installation requirements.</para>
+ <para>This documentation covers two topics.</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Installation and configuration of the library itself.</para>
+ </listitem>
+
+ <listitem>
+ <para>Installation of the negotiation toolkit to test the
+ installation.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>It is recommended that you use the negotiation toolkit to test that
+ the security settings are correctly working before attempting to secure
+ your own web application, this way you can eliminate if any problems are
+ specific to your web application and also use the toolkit to obtain
+ additional debug information.</para>
</section>
+
+ <section>
+ <title>Authenticator Installation</title>
+
+ <para>The authenticator is contained within a single jar
+ 'jboss-negotiation.jar', this jar should be placed in the following
+ location: -</para>
+
+ <para> {jboss.home}/server/{configuration}/lib</para>
+
+ <para>After copying the jar to the above location you will need to add the
+ authenticator itself to the following descriptor: -</para>
+
+ <para>
+ {jboss.home}/server/{configuration}/deploy/jboss-web.deployer/META-INF/jboss-service.xml</para>
+
+ <para>Within this descriptor you should see a set of authenticators, to
+ add SPNEGO you should add the following entry: -</para>
+
+ <para><code> <java:property> </code></para>
+
+ <para><code> <java:key>SPNEGO</java:key> </code></para>
+
+ <para><code> <java:value></code></para>
+
+ <para><code>
+ org.jboss.security.negotiation.spnego.SPNEGOAuthenticator</code></para>
+
+ <para><code> </java:value> </code></para>
+
+ <para><code> </java:property></code></para>
+
+ <para>The key can be any value you choose, however using SPNEGO is
+ recommended to be consistent with the rest of this document.</para>
+ </section>
+
+ <section>
+ <title>Realm Properties</title>
+
+ <para>If you are running your JBoss installation on a host which is
+ already configured to authenticate against a Kerberos KDC then you can
+ skip this step, however if the host is not already configured against a
+ KDC or if you need JBoss to authenticate against a different KDC a couple
+ of system properties need to be set so that JBoss can identify the correct
+ realm and kdc.</para>
+
+ <para>The two properties that need to be set are.</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>java.security.krb5.realm - This is the Kerberos realm to
+ authenticate against.</para>
+ </listitem>
+
+ <listitem>
+ <para>java.security.krb5.kdc - This is the hostname of the KDC
+ itself.</para>
+ </listitem>
+ </itemizedlist>
+
+ <section>
+ <title>Command Line</title>
+
+ <para>The easiest way to set the properties is to pass them to JBoss on
+ the command line when you start the server e.g.</para>
+
+ <para> ./run.sh -Djava.security.krb5.realm=KERBEROS.JBOSS.ORG
+ -Djava.security.krb5.kdc=kerberos.security.jboss.org</para>
+
+ <para></para>
+ </section>
+
+ <section>
+ <title>System Properties Service</title>
+
+ <para>JBoss also make a properties service available which will allow
+ you to define these properties in a descriptor and the properties
+ service will set them as JBoss starts, the only requirement is that
+ these properties are set before the first authentication attempt - JBoss
+ does not allow incomming HTTP connections until the server is completely
+ started so this is not a proble.</para>
+
+ <para>The properties service is documented in the Wiki at <link
+ linkend="???">http://wiki.jboss.org/wiki/PropertiesService</link></para>
+
+ <para>There is already a deployment of the properties service that you
+ can add your properties to, this is in the following descriptor:
+ -</para>
+
+ <para>
+ {jboss.home}//server/{configuration}/deploy/properties-service.xml</para>
+
+ <para>Add the following attribute to the
+ 'jboss:type=Service,name=SystemProperties' MBean to set the properties:
+ -</para>
+
+ <para><code><attribute name="Properties"></code></para>
+
+ <para><code>
+ java.security.krb5.kdc=kerberos.security.jboss.org</code></para>
+
+ <para><code> java.security.krb5.realm=KERBEROS.JBOSS.ORG</code></para>
+
+ <para><code></attribute></code></para>
+ </section>
+ </section>
+
+ <section>
+ <title>Host Security Domain</title>
+
+ <para>The application server requires a security domain that it can use to
+ first authenticate against the KDC, in order to configure this a keytab
+ will be required for the principal that represents the application server.
+ The following chapters will cover the details of setting up a service host
+ and obtaining the keytab from the KDC but the general requirements to
+ configure the security domain in JBoss are the same.</para>
+
+ <para></para>
+ </section>
</chapter>
\ No newline at end of file
Modified: projects/security/security-negotiation/trunk/docs/userguide/src/docbkx/en/modules/introduction.xml
===================================================================
--- projects/security/security-negotiation/trunk/docs/userguide/src/docbkx/en/modules/introduction.xml 2008-05-17 22:38:54 UTC (rev 73469)
+++ projects/security/security-negotiation/trunk/docs/userguide/src/docbkx/en/modules/introduction.xml 2008-05-17 23:17:38 UTC (rev 73470)
@@ -51,21 +51,66 @@
enable you to verify that the required steps are working correctly and
to debug where failures may be occuring.</para>
</listitem>
+ </itemizedlist>
+ </sect1>
+ <sect1>
+ <title>General Authentication Process</title>
+
+ <para>When working with the JBoss login modules and the existing
+ authentication mechanisms work by asking the user to authenticate
+ themseves by the client sending thier credentials to the server and then
+ the login module verifying the credentials against either a local store of
+ credentials or against a store on a remote repository such as a database
+ server or a LDAP server.</para>
+
+ <para>The SPNEGO authentication mechansim is slightly different.</para>
+
+ <para></para>
+
+ <itemizedlist>
<listitem>
- <para>Configuration Project</para>
+ <para><emphasis role="bold">Server Authentication</emphasis> - First
+ the application server itself authenticates against the KDC and
+ obtains it's own ticket.</para>
+ </listitem>
- <para>This project allow you to specify a couple of properties within
- a property file and the build script contained within the project will
- configure and deploy your security configuration automatically - after
- this is deployed all you will need to do it deploy your web
- application configured to use the SPNEGO authenticator and set the
- correct security domain.</para>
+ <listitem>
+ <para><emphasis role="bold">Client Authentication</emphasis> - After
+ the server prompt the client to authenticate the client responds with
+ a SPNEGO token, the server then makes use of it's own ticket to decode
+ the clients ticked and respond to the client.</para>
+
+ <para>This process can take a couple of round trips for the client to
+ authenticate against the server.</para>
</listitem>
+
+ <listitem>
+ <para><emphasis role="bold">Mututal Authentication</emphasis> - If
+ this is required it is even possible for the client to request that
+ the server authenticates itself against the client.</para>
+ </listitem>
+
+ <listitem>
+ <para><emphasis role="bold">Credential Delegation</emphasis> - A
+ client can also be configured so that the credentials used for
+ authentication can be delegated to the server, this means that the
+ application server can then go on and call other systems on behalf of
+ the calling client.</para>
+ </listitem>
</itemizedlist>
+
+ <para></para>
</sect1>
<sect1>
- <para />
+ <title>Pre-requisits</title>
+
+ <para>The installation of this module requires the externalised
+ authenticator capability of JBoss which was added from JBoss 4.0.5.GA,
+ these instructions have been prepared against JBoss 4.2.2.GA.</para>
+
+ <para><link
+ linkend="???">http://wiki.jboss.org/wiki/ExternalizeTomcatAuthenticators</link></para>
</sect1>
</chapter>
\ No newline at end of file
More information about the jboss-cvs-commits
mailing list