[jboss-cvs] JBossAS SVN: r109509 - projects/security/security-negotiation/branches/dlofthouse/Temp/docs/userguide/en/modules.
jboss-cvs-commits at lists.jboss.org
jboss-cvs-commits at lists.jboss.org
Sat Nov 27 09:52:11 EST 2010
Author: darran.lofthouse at jboss.com
Date: 2010-11-27 09:52:11 -0500 (Sat, 27 Nov 2010)
New Revision: 109509
Modified:
projects/security/security-negotiation/branches/dlofthouse/Temp/docs/userguide/en/modules/general_installation.xml
projects/security/security-negotiation/branches/dlofthouse/Temp/docs/userguide/en/modules/introduction.xml
projects/security/security-negotiation/branches/dlofthouse/Temp/docs/userguide/en/modules/microsoft_ad.xml
Log:
Intermediate doc updates.
Modified: projects/security/security-negotiation/branches/dlofthouse/Temp/docs/userguide/en/modules/general_installation.xml
===================================================================
--- projects/security/security-negotiation/branches/dlofthouse/Temp/docs/userguide/en/modules/general_installation.xml 2010-11-27 14:51:11 UTC (rev 109508)
+++ projects/security/security-negotiation/branches/dlofthouse/Temp/docs/userguide/en/modules/general_installation.xml 2010-11-27 14:52:11 UTC (rev 109509)
@@ -54,16 +54,35 @@
<section>
<title>Authenticator Installation</title>
+ <note>
+ <para>
+ Starting from JBoss 5.1.0.GA JBoss Negotiation is already included in the distribution,
+ this step only needs to be performed if installing a later version.
+ </para>
+ </note>
+
<para>
The authenticator is contained within a single jar '
- <code>jboss-negotiation-2.0.3.GA.jar</code>
- ', this jar should be placed in the following location -
- <code>{jboss.home}/server/{configuration}/lib/</code>
+ <code>jboss-negotiation.jar</code>
+ '.
</para>
+
+ <para>
+ If you are running JBoss AS 4.2.x copy the
+ <code>jboss-negotiation.jar</code> to
+ <code>{jboss.home}/server/{configuration}/lib/</code>.
+ </para>
+
+ <para>
+ If you are running JBoss AS 5.x the jar
+ <code>jboss-negotiation.jar</code> should be copied to
+ <code>{jboss.home}/server/common/lib/</code>.
+ </para>
<para>
- The locations to define the authenticator are slightly different
- between JBoss AS 4.2.x and JBoss AS 5.0.x.
+ Throughout the remainder of this user guide the locations to define the
+ authenticator are slightly different between JBoss AS 4.2.x and JBoss AS 5.0.x
+ but the overall approach is the same.
</para>
<section>
@@ -100,25 +119,33 @@
After copying the jar to the above location you will need to
add the authenticator itself to the following descriptor -
<code>
- {jboss.home}/server/{configuration}/deployers/jbossweb.deployer/META-INF/war-deployers-jboss-beans.xml
+ {jboss.home}/server/{configuration}/deployers/
+ jbossweb.deployer/META-INF/war-deployers-jboss-beans.xml
</code>
</para>
<para>
Within this descriptor you should see a set of authenticators
defined using a property called "authenticators", you should
- add the following entry: -
+ add a new entry: -
</para>
<programlisting>
<![CDATA[
<entry>
- <key>SPNEGO</key>
- <value>org.jboss.security.negotiation.NegotiationAuthenticator</value>
+ <key>{key}</key>
+ <value>{authenticator}</value>
</entry>
]]>
</programlisting>
+ <para>
+ For the <code>{key}</code> you can choose any value but for consistency
+ it will be assumed this is set to <code>SPNEGO</code> for the remainder
+ of this user guide, the <code>{authenticator}</code> should be set to
+ '<code>org.jboss.security.negotiation.NegotiationAuthenticator</code>'.
+ </para>
+
<tip>
<para>
Ensure that there is no white space around the classname as
@@ -139,13 +166,6 @@
</para>
</warning>
-
- <para>
- The key can be any value you choose, however using SPNEGO is
- recommended to be consistent with the rest of this document,
- this is also required by the Negotiation Toolkit.
- </para>
-
</section>
</section>
Modified: projects/security/security-negotiation/branches/dlofthouse/Temp/docs/userguide/en/modules/introduction.xml
===================================================================
--- projects/security/security-negotiation/branches/dlofthouse/Temp/docs/userguide/en/modules/introduction.xml 2010-11-27 14:51:11 UTC (rev 109508)
+++ projects/security/security-negotiation/branches/dlofthouse/Temp/docs/userguide/en/modules/introduction.xml 2010-11-27 14:52:11 UTC (rev 109509)
@@ -149,7 +149,7 @@
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 AS
- 4.2.3.GA and JBoss AS 5.0.0.GA.
+ 4.2.3.GA and JBoss AS 5.x.
</para>
<para>
Modified: projects/security/security-negotiation/branches/dlofthouse/Temp/docs/userguide/en/modules/microsoft_ad.xml
===================================================================
--- projects/security/security-negotiation/branches/dlofthouse/Temp/docs/userguide/en/modules/microsoft_ad.xml 2010-11-27 14:51:11 UTC (rev 109508)
+++ projects/security/security-negotiation/branches/dlofthouse/Temp/docs/userguide/en/modules/microsoft_ad.xml 2010-11-27 14:52:11 UTC (rev 109509)
@@ -27,9 +27,7 @@
A couple of additional command line utilities are going to be
required when configuring the service accounts on the domain
controller, these can be downloaded directly from Microsoft
- <ulink url="http://go.microsoft.com/fwlink/?LinkId=100114">
- http://go.microsoft.com/fwlink/?LinkId=100114
- </ulink>
+ <ulink url="http://go.microsoft.com/fwlink/?LinkId=100114" />
</para>
</section>
@@ -46,6 +44,20 @@
a computer account - we will perform some additional steps later
to map the user account to a service account.
</para>
+
+ <warning>
+ <para>
+ If the JBoss server is going to be running on a Windows machine which
+ is also a member of the Active Directory domain it is important that the
+ selected username is different to the name of the machine.
+ </para>
+
+ <para>
+ Although in this example the username is based on the fully qualified
+ domain name this is not a requirement and the name of the account can be
+ anything as we associate the two later.
+ </para>
+ </warning>
<para>
As we are going to be referring to the server using the name
@@ -53,14 +65,13 @@
'testserver'.
</para>
- <warning>
+ <note>
<para>
- It is important to set a valid password on the account as soon
- as you create as changing the password later can invalidate the
- keytab that you export which would break your JBoss
- installations.
+ At this stage do set a user password, however be aware that
+ this password will need to be reset later in the installation
+ process.
</para>
- </warning>
+ </note>
<para>The first step is to create the actual user.</para>
@@ -141,107 +152,115 @@
</para>
<para>
- The first utility to use is the setspn.exe utility installed with
- the Windows 2003 support tools. Documentation for this tool is
- available from Microsoft
- <ulink
- url="http://technet2.microsoft.com/windowsserver/en/library/b3a029a1-7ff0-4f6f-87d2-f2e70294a5761033.mspx?mfr=true">
- http://technet2.microsoft.com/windowsserver/en/library/b3a029a1-7ff0-4f6f-87d2-f2e70294a5761033.mspx?mfr=true
- </ulink>
+ The utilities to use are installed with
+ the Windows 2003 support tools.
</para>
- <para>
- You should execute the following two command to map the testserver
- user to the correct service principals.
- </para>
-
- <programlisting>
-<![CDATA[setspn.exe -a host/testserver.kerberos.jboss.org testserver
-setspn.exe -a HTTP/testserver.kerberos.jboss.org testserver]]>
- </programlisting>
-
+ <section>
+ <title>Clear Existing Mappings</title>
+
+ <note>
+ <para>
+ This sub-section is only applicable if the server running JBoss is
+ a windows machine that is already a member of the Active Directory
+ domain or if you have already configured the mapping and wish to start again.
+ </para>
+ </note>
+
+ <para>
+ If the server running JBoss is a Windows machine which is a member of the domain
+ then the first step is to check if there is a principal mapping in place and to
+ clear this mapping.
+ </para>
+
+ <para>
+ To check if the machine is mapped execute the command <code>setspn -L {machine_name}</code>,
+ if either of <code>HTTP/{hostname}</code> or <code>host/{hostname}</code> are listed they
+ need to be deleted with <code>setspn -D HTTP/{hostname} {machine_name}</code> and
+ <code>setspn -D host/{hostname} {machine_name}</code>.
+ </para>
+
+ <para>
+ If you are trying to clear a previous mapping from following this guide then the above
+ commands can be used but instead of <code>{machine_name}</code> you would use the username of the account
+ created for the mapping.
+ </para>
+
+ </section>
+
+ <section>
+ <title>Add New Mapping</title>
+
+ <para>
+ The next step is to use the ktpass.exe utility from the Windows
+ 2003 support tools to create the host / user account mapping.
+ </para>
+
+ <note>
+ <para>
+ The following images need some updates.
+ </para>
+ </note>
- <figure id="ad-setspn">
- <title>Set Service Principals</title>
- <mediaobject>
- <imageobject>
- <imagedata align="center" fileref="images/ad-setspn.png" />
- </imageobject>
- </mediaobject>
- </figure>
+ <programlisting>
+ <![CDATA[ktpass -princ HTTP/testserver.kerberos.jboss.org at kerberos.jboss.org -pass * -mapuser KERBEROS\testserver ]]></programlisting>
- <para>
- The following command then can be used to list the mappings.
- </para>
+ <figure id="ad-command-ktpass">
+ <title>KTPass</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata align="center"
+ fileref="images/ad-command-ktpass.png" />
+ </imageobject>
+ </mediaobject>
+ </figure>
- <programlisting>
- <![CDATA[setspn.exe -l testserver]]></programlisting>
+ <para>
+ The following command then can be used to list the mappings.
+ </para>
- <figure id="ad-setspn-list">
- <title>List Service Principals</title>
- <mediaobject>
- <imageobject>
- <imagedata align="center" fileref="images/ad-setspn-list.png" />
- </imageobject>
- </mediaobject>
- </figure>
+ <programlisting>
+ <![CDATA[setspn.exe -l testserver]]></programlisting>
- <para>
- The next step is to use the ktpass.exe utility from the Windows
- 2003 support tools and also the ktab.exe tool from the Java
- installation to export the keytab.
- </para>
+ <figure id="ad-setspn-list">
+ <title>List Service Principals</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata align="center" fileref="images/ad-setspn-list.png" />
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ </section>
- <note>
+ <section>
+ <title>Export Keytab</title>
+
<para>
- This section needs some further consideration, it may be
- possible to just use one of the commands.
+ The ktab.exe utility is then used to export the keytab that will
+ be used by the application server using the following command.
</para>
- </note>
- <para>
- The ktpass.exe command line utility takes the user created earlier
- and maps it as a trusted host, in this case you would need to
- execute the following command: -
- </para>
+ <programlisting>
+ <![CDATA[ktab -k c:\testserver.host.keytab -a testserver at KERBEROS.JBOSS.ORG]]></programlisting>
- <programlisting>
- <![CDATA[ktpass -princ host/testserver at kerberos.jboss.org -pass * -mapuser KERBEROS\testserver
--out C:\testserver.host.keytab]]></programlisting>
+ <figure id="ad-ktab">
+ <title>Export Keytab</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata align="center" fileref="images/ad-ktab.png" />
+ </imageobject>
+ </mediaobject>
+ </figure>
- <figure id="ad-command-ktpass">
- <title>KTPass</title>
- <mediaobject>
- <imageobject>
- <imagedata align="center"
- fileref="images/ad-command-ktpass.png" />
- </imageobject>
- </mediaobject>
- </figure>
+ <para>
+ The resulting keytab should then be used in setting up the host
+ security domain as described in
+ <xref linkend="host_security_domain" />.
+ </para>
+
+ </section>
- <para>
- The ktab.exe utility is then used to export the keytab that will
- be used by the application server using the following command.
- </para>
-
- <programlisting>
- <![CDATA[ktab -k c:\testserver.host.keytab -a testserver at KERBEROS.JBOSS.ORG]]></programlisting>
-
- <figure id="ad-ktab">
- <title>Export Keytab</title>
- <mediaobject>
- <imageobject>
- <imagedata align="center" fileref="images/ad-ktab.png" />
- </imageobject>
- </mediaobject>
- </figure>
-
- <para>
- The resulting keytab should then be used in setting up the host
- security domain as described in
- <xref linkend="host_security_domain" />
- .
- </para>
</section>
<section>
More information about the jboss-cvs-commits
mailing list