From jboss-identity-commits at lists.jboss.org Mon Feb 2 16:04:43 2009 Content-Type: multipart/mixed; boundary="===============1690944840581333237==" MIME-Version: 1.0 From: jboss-identity-commits at lists.jboss.org To: jboss-identity-commits at lists.jboss.org Subject: [jboss-identity-commits] JBoss Identity SVN: r272 - identity-federation/trunk/doc/UserGuide/src/main/docbook. Date: Mon, 02 Feb 2009 16:04:42 -0500 Message-ID: --===============1690944840581333237== Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Author: anil.saldhana(a)jboss.com Date: 2009-02-02 16:04:42 -0500 (Mon, 02 Feb 2009) New Revision: 272 Modified: identity-federation/trunk/doc/UserGuide/src/main/docbook/UserGuide.xml Log: userguide Modified: identity-federation/trunk/doc/UserGuide/src/main/docbook/UserGuid= e.xml =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D --- identity-federation/trunk/doc/UserGuide/src/main/docbook/UserGuide.xml = 2009-02-02 13:39:43 UTC (rev 271) +++ identity-federation/trunk/doc/UserGuide/src/main/docbook/UserGuide.xml = 2009-02-02 21:04:42 UTC (rev 272) @@ -27,7 +27,8 @@ Identity based services or applications. = Part I 'Getting Started' introduces the federated identity - technologies that are provided in this product. + technologies that are provided in this product. It also indicates + the libraries required for the installation. = Part II 'Simple Usage' describes SAML v2 Web Browser based = Single Sign On (SSO). @@ -35,6 +36,10 @@ Part III 'Advanced Usage' describes SAML v2 Web Browser based SS= O = with advanced features such as Trust Management and XML Digital Signatures. + = + Part IV 'Trouble Shooting' section describes some basic + troubleshooting tips when things do not work the way they were intende= d. + = @@ -64,10 +69,51 @@ = + = + + Installation + + JBoss Identity Federation requires the following libraries + to be either downloaded separately or as part of the Java JDK + or as part of JBoss Application Server. + + + + JBoss Identity Federation Library + + + + JBoss XACML Library (jboss-xacml.jar and jboss-sunxacml.j= ar) + + + + JAXB V2 Library + + + + STAX API Library (a dependency for JAXB2) + + + + Activation API Library (a dependency for JAXB2) + + + + = + + Location for downloading the jars + + JBoss Maven Rep= ository + = + + = + + = + = + Simple Usage = - - Simple Usage - + + Web Single Sign On (SSO) In this chapter, we will look at usage of JBoss Identity Federation to help you obtain a platform to implement federated iden= tity based services (including centralized identity services @@ -392,6 +438,362 @@ = - + - + = + + Advanced Usage (Trust Management) + + Web SSO - XML Signature Support + + In this chapter, we describe the configuration for Web SSO with = XML Signature Support. + = +
+ Configuring the Identity Provider + + The IDP needs to be configured to provide Web SSO with XML Signa= ture Support. + + = + + Check list for configuring the IDP + + Configure the IDP as a secure web application. + + Configure the web.xml to either allow FORM or BASIC= authentication. + + Configure the context.xml for IDP valves. + + Configure the jboss-idfed.xml for IDP configuration. + + + + = +
+ Configure the IDP Web Application Security + + Configure the web application security for IDP + Follow the web.xml security configuration for the IDP= from the previous section + "Simple Usage". + + +
+ = +
+ Configure the IDP Valves + Create a context.xml file for configuring = + the valves for the IDP. + + The context.xml file should look like: + + + <Context> + <Valve = + className + =3D"org.jboss.identity.federation.bindings.tomcat.idp.IDPR= edirectWithSignatureValve" = + /> + </Context> + + = + = + If the IDP is running in Apache Tomcat, then place the = context.xml in = + META-INF of your IDP web = application. + + + = + + If the IDP is running in JBoss Application Server, the= n place the context.xml in = + WEB-INF of your IDP web a= pplication. + + + = +
+ = +
+ Configure the JBoss Identity Federation configuration f= ile (jboss-idfed.xml) + Configure jboss-idfed.xml in WEB-INF of your = + IDP web application + + <JBossIDP xmlns=3D"urn:jboss:identity-federation:config:1.0= " > + <IdentityURL>http://localhost:8080/idp-sig</Identit= yURL> + <Trust> + <Domains>localhost,jboss.com,jboss.org</Domains&= gt; + </Trust> + <KeyProvider = + ClassName=3D"org.jboss.identity.federation.bindings.tomca= t.KeyStoreKeyManager"> + <Auth Key=3D"KeyStoreURL" Value=3D"jbid_test_keystore.= jks" /> + <Auth Key=3D"KeyStorePass" Value=3D"store123" /> + <Auth Key=3D"SigningKeyPass" Value=3D"test123" /> + <Auth Key=3D"SigningKeyAlias" Value=3D"servercert" /&g= t; + <ValidatingAlias Key=3D"localhost" Value=3D"servercert= "/> + <ValidatingAlias Key=3D"127.0.0.1" Value=3D"servercert= "/> + </KeyProvider> + </JBossIDP> + + = + In this configuration file, you are providing the URL of= your IDP. = + This is the URL that gets added as the issuer in the outgoing = SAML2 assertions = + to the Service Providers. + + + Additionally, you can configure the = Trust + element to indicate which domains the IDP trusts. + + + You can configure a TrustKeyManager + implementation for the Signing (Private) Key and the Validatin= g (Public) Key + information. In this example, we have used the = + KeyStoreKeyManager that + stores the keys in a Java KeyStore. The Auth + element define the key value pair needed to authenticate again= st the = + TrustKeyManager implementat= ion. The + ValidatingAlias is a map = of the domains + that need to be validated against an alias where the public ke= y of the domains + are stored. + +
+ = + = +
+ Configure the Service Provider (SP) + + Check List for configuring the Service Provider. + + + Configure the SP as a secure FORM authentication b= ased web application. + + Configure the web.xml of the SP web application. + + Configure the context.xml for the SP valves. + + Configure the jboss-idfed.xml for the SP configura= tion. + + + = + = + The SP can be a JBoss Application Server or a Tomcat insta= nce. + + + You need to configure a web application as the Service Provider(= SP). = + + = +
+ Configure the SP Web Application Security + + Configure the web application security for SP + Follow the web.xml security configuration for the SP = from the previous section + "Simple Usage". + + +
+ = +
+ Configure the SP Valves + Create a context.xml file for configuring = + the valves for the SP. + + The context.xml file should look like: + + + = + <Context> + <Valve + className=3D + "org.jboss.identity.federation.bindings.tomcat.sp.SPRedirect= SignatureFormAuthenticator" = + /> + </Context> + + + = + = + If the SP is running in Apache Tomcat, then place the c= ontext.xml in = + META-INF of your SP web a= pplication. + + + = + + If the SP is running in JBoss Application Server, then= place the context.xml in = + WEB-INF of your SP web ap= plication. + + + = +
+ = +
+ Configure the JBoss Identity Federation configuration f= ile (jboss-idfed.xml) + Configure jboss-idfed.xml in WEB-INF of your = + IDP web application + + <JBossIDP xmlns=3D"urn:jboss:identity-federation:config:1.0= " > + <IdentityURL>http://localhost:8080/idp-sig</Identit= yURL> + <Trust> + <Domains>localhost,jboss.com,jboss.org</Domains&= gt; + </Trust> + <KeyProvider = + ClassName=3D"org.jboss.identity.federation.bindings.tomca= t.KeyStoreKeyManager"> + <Auth Key=3D"KeyStoreURL" Value=3D"jbid_test_keystore.= jks" /> + <Auth Key=3D"KeyStorePass" Value=3D"store123" /> + <Auth Key=3D"SigningKeyPass" Value=3D"test123" /> + <Auth Key=3D"SigningKeyAlias" Value=3D"servercert" /&g= t; + <ValidatingAlias Key=3D"localhost" Value=3D"servercert= "/> + <ValidatingAlias Key=3D"127.0.0.1" Value=3D"servercert= "/> + </KeyProvider> + </JBossIDP> + + = + In this configuration file, we define the URLs for the s= ervice provider and = + the identity provider. + + + Additionally, you can configure the = Trust + element to indicate which domains the SP trusts. + + + You can configure a TrustKeyManager + implementation for the Signing (Private) Key and the Validatin= g (Public) Key + information. In this example, we have used the = + KeyStoreKeyManager that + stores the keys in a Java KeyStore. The Auth + element define the key value pair needed to authenticate again= st the = + TrustKeyManager implementat= ion. The + ValidatingAlias is a map = of the domains + that need to be validated against an alias where the public ke= y of the domains + are stored. + +
+ = + + + = + + Troubleshooting + +
+ Configuring Logging + + JBoss Identity Federation uses Apache log4j as the logging fra= mework. + +
+ Configuring Logging on Apache Tomcat + + Log4J jars and xml file + + Add a log4j.jar (from the Apache log4j Distribution) into t= he lib directory of + tomcat 6.x or server/lib of tomcat 5.5.x + + Also add a log4j.xml as shown below to the lib direc= tory. + + + = + + <?xml version=3D"1.0" encoding=3D"UTF-8"?> +<!DOCTYPE log4j:configuration SYSTEM "log4j.dtd"> + +<!-- =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D --> +<!-- = --> +<!-- Log4j Configuration = --> +<!-- = --> +<!-- =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D --> + +<!-- + | For more configuration information and examples see the Jakarta Log4j + | owebsite: http://jakarta.apache.org/log4j + --> + +<log4j:configuration xmlns:log4j=3D"http://jakarta.apache.org/log4j/" d= ebug=3D"false"> + + <!-- =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D --> + <!-- Preserve messages in a local file --> + <!-- =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D --> + + <!-- A time/date based rolling appender --> + <appender name=3D"FILE" class=3D"org.apache.log4j.DailyRollingFileAp= pender"> + <param name=3D"File" value=3D"../logs/server.log"/> + <param name=3D"Append" value=3D"false"/> + <!-- = + Set the threshold via a system property. Note this is parsed by l= og4j, + so the full JBoss system property format is not supported; e.g. + setting a default via ${jboss.server.log.threshold:WARN} will not= work. = + --> + <param name=3D"Threshold" value=3D"TRACE"/> + + <!-- Rollover at midnight each day --> + <param name=3D"DatePattern" value=3D"'.'yyyy-MM-dd"/> + + <!-- Rollover at the top of each hour + <param name=3D"DatePattern" value=3D"'.'yyyy-MM-dd-HH"/> + --> + + <layout class=3D"org.apache.log4j.PatternLayout"> + <!-- The default pattern: Date Priority [Category] (Thread) Me= ssage\n --> + <param name=3D"ConversionPattern" value=3D"%d %-5p [%c] (%t) %= m%n"/> + + <!-- The full pattern: Date MS Priority [Category] (Thread:NDC= ) Message\n + <param name=3D"ConversionPattern" value=3D"%d %-5r %-5p [%c] (= %t:%x) %m%n"/> + --> + </layout> + </appender> + + <!-- =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D --> + <!-- Append messages to the console --> + <!-- =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D --> + + <appender name=3D"CONSOLE" class=3D"org.apache.log4j.ConsoleAppender= "> + <param name=3D"Target" value=3D"System.out"/> + <param name=3D"Threshold" value=3D"INFO"/> + + <layout class=3D"org.apache.log4j.PatternLayout"> + <!-- The default pattern: Date Priority [Category] Message\n -= -> + <param name=3D"ConversionPattern" value=3D"%d{ABSOLUTE} %-5p [= %c{1}] %m%n"/> + </layout> + </appender> + + <!-- =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D --> + <!-- Limit categories --> + <!-- =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D --> + + <!-- Limit the org.apache category to INFO as its DEBUG is verbose -= -> + <category name=3D"org.apache"> + <priority value=3D"TRACE"/> + </category> + <category name=3D"org.jboss"> + <priority value=3D"TRACE"/> + </category> + = + <!-- Setup the Root category --> + <!-- =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D --> + + <root> + <appender-ref ref=3D"CONSOLE"/> + <appender-ref ref=3D"FILE"/> + </root> + +</log4j:configuration> + = + = + + Location of the generated log file + + The generated log file will be server.log in the logs direc= tory. + + + = +
+ = +
+ Configuring logging in JBoss + + You can configure log4j in the conf directory of your JBoss se= rver (default, all etc) + + + Please refer to JBoss AS documentation on logging. + +
+ = +
+ + + \ No newline at end of file --===============1690944840581333237==--