<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
<!ENTITY % CustomDTD SYSTEM "../../../../../../docbook/custom.dtd">
%CustomDTD;
]>
<chapter>
<title>Custom Security</title>
<section id="custom_login_modules">
    <title>Login Modules</title>
    <para>The Teiid system provides a range of built-in and extensible security features to enable the
        secure access of data.  For details about how to configure the available security features check out
        Admin Guide.</para>
        <para>
            LoginModules are an essential part of the JAAS security
            framework and provide Teiid customizable user authentication and the
            ability to reuse existing LoginModules defined for JBossAS. Refer to 
            the JBoss Application Server security documentation for information about 
            configuring security in JBoss Application Server,  
            <ulink url="http://docs.jboss.org/jbossas/admindevel326/html/ch8.chapter.html"/>.
            </para>
    
		<section>
			<title>Built-in LoginModules</title>
			<para>
			JBoss Application Server provides several LoginModules for common 
			authentication needs, such as authenticating from text files or LDAP. 
         </para>

         <para>
         Below are are some of those available in JBoss Application Server:
         </para>
         
         <variablelist>

            <varlistentry>
               <term>UserRoles LoginModule</term>
               <listitem>
                  <para>
                  Login module that uses simple file based authentication. 
                  </para>
                  <para>
                  Refer to <ulink url="http://community.jboss.org/docs/DOC-12510"/>.
                  </para>
               </listitem>
               </varlistentry>
               <varlistentry>
                  <term>LDAP LoginModule</term>
               <listitem>
                  <para>
                  Login module that uses LDAP based authentication.
                  </para>
                  <para>
                  Refer to <ulink url="http://community.jboss.org/docs/DOC-11253"/>.  
                  </para>
               </listitem>
               </varlistentry>
               <varlistentry>
                  <term>Database LoginModule</term>
               <listitem>
                  <para>
                  Login module that uses Database-based authentication.
                  </para>
                  <para>
                  Refer to <ulink url="http://community.jboss.org/docs/DOC-9511"/>.
                  </para>
               </listitem>
               </varlistentry>
               <varlistentry>
                  <term>Cert LoginModule</term>
               <listitem>
                  <para>
                  Login module that uses X509 certificate based authentication. 
                  </para>
                  <para>
                  See <ulink url="http://community.jboss.org/docs/DOC-9160"/>.
                  </para>
               </listitem>
            </varlistentry>
         
         </variablelist>

         <para>
         For all the available login modules refer to <ulink url="http://community.jboss.org/docs/DOC-11287"/>.
         </para>

      </section>
		
		<section>
			<title>Custom LoginModules</title>
			<para>
				If your authentication needs go beyond the provided LoginModules, please refer 
				to the JAAS development guide at 
				<ulink url="http://java.sun.com/j2se/1.5.0/docs/guide/security/jaas/JAASLMDevGuide.html"/>.
				There are also numerous guides available.
			</para>
            
            <para>If you are extending one of the built-in LoginModules, refer to  
            <ulink url="http://community.jboss.org/docs/DOC-9466"/>.</para>
		</section>
</section>
<section>
	<title>Custom Authorization</title>
	<para>In situations where Teiid's built-in role mechanism is not sufficient, a  
	<code>org.teiid.PolicyDecider</code> can be installed via JBoss module. Extend the <code>org.teiid.PolicyDecider</code> interface
    and build a custom java class. If you are using maven as your build process, you can use following dependencies</para>
    
    <programlisting role="XML" language="XML"><![CDATA[
   <dependencies>
      <dependency>
         <groupId>org.jboss.teiid</groupId>
         <artifactId>teiid-api</artifactId>
         <scope>provided</scope>
      </dependency>
      <dependency>
         <groupId>org.jboss.teiid</groupId>
         <artifactId>teiid-common-core</artifactId>
         <scope>provided</scope>
      </dependency>
   </dependencies>
    ]]></programlisting>     
	
    <para> For adding Teiid API dependencies,
    add MANIFEST.MF file in the MATA-INF directory, and the following line. 
    <emphasis>Dependencies: org.jboss.teiid.common-core,org.jboss.teiid.api,javax.api</emphasis>.
    PoilcyDecider is loaded by the Teiid using the Java's standard service loader mechanism. For this add the following named
    file <emphasis>META-INF/services/org.teiid.PolicyDecider</emphasis> with full name of your PolicyDecider as the contents. 
    Now package all these files into a jar file and build JBoss module in &gt;jboss-as&lt;/modules directory. If your PolicyDecider
    has any third party dependencies those jar files can also be added to the same module. Make sure you list all the files in the
    module.xml file.
    </para>
    
    <para>
     After the module has been added then configuration needs to be changed before the changes can take effect. Edit either 
    standalone-teiid.xml or domain-teiid.xml file, and in the "teiid" subsystem xml fragment add the following xml with the 
    module name created.
    
    <programlisting role="XML" language="XML"><![CDATA[
        <policy-decider module="module-name"/>
    ]]></programlisting>       
    
    then restart the system. 
	A <code>PolicyDecider</code> may be consulted many times for a single user command, but it is only called to make 
    decisions based upon resources that 
	appear in user queries.  Any further access of resources through views or stored procedures, just as with data roles, 
    is not checked against a <code>PolicyDecider.</code>
	</para>
</section>
</chapter>