Procedure 2.1. Setup Authentication Settings for a Security Domain

1. Open the security domain's detailed view.

   1. Click the Configuration label at the top of the management console.
   2. Select the profile to modify from the Profile selection box at the top left of the Profile view.
   3. Expand the Security menu, and select Security Domains.
   4. Click the View link for the security domain you want to edit.

2. Navigate to the Authentication subsystem configuration.

   Select the Authentication label at the top of the view if it is not already selected.
   The configuration area is divided into two areas: Login Modules and Details. The login module is the basic unit of configuration. A security domain can include several login modules, each of which can include several attributes and options.

3. Add an authentication module.

   Click Add to add a JAAS authentication module. Fill in the details for your module.
   The Code is the class name of the module. The Flag setting controls how the module relates to other authentication modules within the same security domain.
   Explanation of the Flags

   The Java Enterprise Edition 6 specification provides the following explanation of the flags for security modules. The following list is taken from http://docs.oracle.com/javase/6/docs/technotes/guides/security/jaas/JAASRefGuide.html#AppendixA. Refer to that document for more detailed information.

   Flag	Details
   required	The LoginModule is required to succeed. If it succeeds or fails, authentication still continues to proceed down the LoginModule list.
   requisite	LoginModule is required to succeed. If it succeeds, authentication continues down the LoginModule list. If it fails, control immediately returns to the application (authentication does not proceed down the LoginModule list).
   sufficient	The LoginModule is not required to succeed. If it does succeed, control immediately returns to the application (authentication does not proceed down the LoginModule list). If it fails, authentication continues down the LoginModule list.
   optional	The LoginModule is not required to succeed. If it succeeds or fails, authentication still continues to proceed down the LoginModule list.

4. Edit authentication settings

   After you have added your module, you can modify its Code or Flags by clicking Edit in the Details section of the screen. Be sure the Attributes tab is selected.

5. Optional: Add or remove module options.

   If you need to add options to your module, click its entry in the Login Modules list, and select the Module Options tab in the Details section of the page. Click the Add button, and provide the key and value for the option. Use the Remove button to remove an option.
6. Reload the Red Hat JBoss Data Virtualization server to make the authentication module changes available to applications.

Procedure 2.2. Setup Authorization in a Security Domain

1. Open the security domain's detailed view.

   1. Click the Configuration label at the top of the management console.
   2. In a managed domain, select the profile to modify from the Profile drop down box at the top left.
   3. Expand the Security menu item, and select Security Domains.
   4. Click the View link for the security domain you want to edit.

2. Navigate to the Authorization subsystem configuration.

   Select the Authorization label at the top of the screen.
   The configuration area is divided into two areas: Policies and Details. The policy module is the basic unit of configuration. A security domain can include several authorization policies, each of which can include several attributes and options.

3. Add a policy.

   Click Add to add a JAAS authorization policy module. Fill in the details for your module.
   The Code is the class name of the module. The Flag controls how the module relates to other authorization policy modules within the same security domain.
   Explanation of the Flags

   The Java Enterprise Edition 6 specification provides the following explanation of the flags for security modules. The following list is taken from http://docs.oracle.com/javase/6/docs/technotes/guides/security/jaas/JAASRefGuide.html#AppendixA. Refer to that document for more detailed information.

   Flag	Details
   required	The policy module is required to succeed. If it succeeds or fails, authorization still continues to proceed down the policy module list.
   requisite	The policy module is required to succeed. If it succeeds, authorization continues down the policy module list. If it fails, control immediately returns to the application (authorization does not proceed down the poicy module list).
   sufficient	The policy module is not required to succeed. If it does succeed, control immediately returns to the application (authorization does not proceed down the policy module list). If it fails, authorization continues down the policy module list.
   optional	The policy module is not required to succeed. If it succeeds or fails, authorization still continues to proceed down the policy module list.

4. Edit authorization settings

   After you have added your module, you can modify its Code or Flags by clicking Edit in the Details section of the screen. Be sure the Attributes tab is selected.

5. Optional: Add or remove module options.

   If you need to add options to your module, click its entry in the Policies list, and select the Module Options tab in the Details section of the page. Click Add and provide the key and value for the option. Use the Remove button to remove an option.

Procedure 3.1. Configure Pass-Through Authentication

• Change the Teiid security-domain name in the embedded "transport" section to the same name as your application's security domain name. (You can make this change via the CLI or by editing the standalone.xml file if you are running the product in standalone mode.).

  Important

  The security domain must be a JAAS-based LoginModule and your client application must obtain its Teiid connection using a Local Connection with the PassthroughAuthentication connection flag set to true.

Procedure 4.1. Configure Pass-Through Authentication

• Set the security domain

  Change the JBoss Data Virtualization security domain to the same name as your application's security domain name in the transport section of the server configuration file.

1. Implement the org.teiid.PolicyDecider interface and build a custom java class. If you are using maven as your build process, you can use the following dependencies:

   <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>
   

2. The PolicyDecider interface is loaded by JBoss Data Virtualization using Java's standard service loader mechanism. For this to work, add the META-INF/services/org.teiid.PolicyDecider file with the full name of your PolicyDecider implementation class as its contents. Here is an example:

   org.jboss.teiid.auth.MyCustomPolicyDecider
   

3. Package all of these files into a JAR archive.
4. Create a directory called [JDV_HOME]/modules/com/mycompany/main/.
5. Copy your jar file into the newly-created directory.
6. Create a module.xml file and also put it in the [JDV_HOME]/modules/com/mycompany/main/ directory.
   Here is an example that shows dependencies specific to JBoss Data Virtualization:

   <?xml version="1.0" encoding="UTF-8"?>
     <module xmlns="urn:jboss:module:1.0" name="com.mycompany">
            <resources>
               <resource-root path="my_custom_policy.jar" />
               <!--add any other dependent jars here, if they are not defined as modules -->
           </resources>
       <dependencies>
           <module name="org.jboss.teiid.common-core"/>
           <module name="org.jboss.teiid.api"/>
           <module name="javax.api"/>
       </dependencies>
     </module>
   

   Note

   If your PolicyDecider has any third-party dependencies, add them as dependencies to the module.xml file. Ensure you list all the files required. If dependencies are missing you will be informed when you start the software.
7. After the module has been added, edit the server configuration file (standalone.xml or its equivalent) to use your module name. The module must be added to the "teiid" subsystem:

       
   			<policy-decider-module>MODULE-NAME</policy-decider-module>
   			

8. Restart the system.

Procedure 7.1. Configure the Caller Identity Login Module

1. Create the Login Module

   Configure authentication modules using the Management Console according to the following specification:

   <security-domain name="my-security-domain" cache-type="default">
       <authentication>
           <login-module code="org.picketbox.datasource.security.CallerIdentityLoginModule" module="org.picketbox" flag="required">
               <module-option name="password-stacking" value="useFirstPass"/>
               <module-option name="userName" value="guest"/>
               <module-option name="password" value="guest"/>
           </login-module>
       </authentication>
   </security-domain>
   

2. • Configure the Data Source

     Configure the datasource according to the following specification.

     <datasource jndi-name="java:/mysql-ds" pool-name="mysql-ds" enabled="true">
         <connection-url>jdbc:mysql://localhost:3306/txns</connection-url>
         <driver>mysql</driver>
          <pool><allow-multiple-users/></pool>
          <security>
               <security-domain>my-security-domain</security-domain>
          </security>
     </datasource>

   • Configure the Connection Factory

     Configure the resource adapter according to the following specification:

     <resource-adapter>
                 <archive>teiid-connector-ldap.rar</archive>
                 <transaction-support>NoTransaction</transaction-support>
                 <connection-definitions>
                     <connection-definition class-name="org.teiid.resource.adapter.ldap.LDAPManagedConnectionFactory"
                             jndi-name="java:/ldapDS"
                             enabled="true"
                             use-java-context="true"
                             pool-name="ldap-ds">
     
                       <config-property name="LdapUrl">ldap://ldapServer:389</config-property>
                       <config-property name="LdapAdminUserDN">cn=???,ou=???,dc=???</config-property>
                       <config-property name="LdapAdminUserPassword">pass</config-property>
                       <config-property name="LdapTxnTimeoutInMillis">-1</config-property>
     
                       <security>
                          <security-domain>my-security-domain</security-domain>
                      </security>
                     </connection-definition>
                 </connection-definitions>
             </resource-adapter>

Procedure 7.2. Configure Role-Based Credential Map Identity Login Module

1. Create the Login Module

   Configure authentication modules using the Management Console according to the following specification:

   			<subsystem xmlns="urn:jboss:domain:security:1.1">
   			</subsystem>
       <security-domains>
       </subsystem>
           <security-domain name="my-security-domain" cache-type="default">
           </security-domain>
               <authentication>
                   <login-module code="UsersRoles" flag="required">
                   </subsystem>
                       <module-option name="password-stacking" value="useFirstPass"/>
                       <module-option name="usersProperties" value="file://${jboss.server.config.dir}/teiid-security-users.properties"/>
   										<module-option name="rolesProperties" value="file://${jboss.server.config.dir}/teiid-security-roles.properties"/>
                   </login-module>
   
                   <login-module code="org.teiid.jboss.RoleBasedCredentialMapIdentityLoginModule" flag="required">
                   </login-module>
                       <module-option name="password-stacking" value="useFirstPass"/>
                       </login-module>
                       <module-option name="credentialMap" value="file://${jboss.server.config.dir}/teiid-credentialmap.properties"/>
                   </login-module>
   
               </authentication>
           </security-domain>
       </security-domains>
       </subsystem>

2. Complete the Configuration

   Configure the data source or connection factory in the same way as for the CallerIdentityLoginModule.

Procedure 8.1. Setup Kerberos Support for Local Connection

• Set the JDBC URL property PassthroughAuthentication to true and use JBoss Negotiation for authentication of your Web application with Kerberos.

Procedure 8.2. Configure Kerberos for Remote Connection

1. Define the security domain

   Now we need to define a security domain for krb5-domain.
   Since Kerberos cannot define authorization roles, it relies on authorization provided by the teiid-security domain. The following example uses the UsersRolesLoginModule for this purpose.

   Note

   This configuration replaces the default JBoss Data Virtualization login configuration, and you should change the principal and keyTab locations accordingly.

     <security-domain name="krb5-domain">
       <authentication>
           <login-module code="Kerberos" flag="required">
               <module-option name="storeKey" value="true"/>
               <module-option name="useKeyTab" value="true"/>
               <module-option name="principal" value="dv/my.host.com@EXAMPLE.COM"/>
               <module-option name="keyTab" value="/path/to/krb5.keytab"/>
               <module-option name="doNotPrompt" value="true"/>
               <module-option name="debug" value="false"/>
           </login-module>
       </authentication>
   </security-domain>
   <security-domain name="EXAMPLE.COM">
      <authentication>
         <!-- Check the username and password -->
         <login-module code="SPNEGO"  flag="requisite">
            <module-option name="password-stacking" value="useFirstPass"/>
            <module-option name="serverSecurityDomain" value="krb5-domain"/>
         </login-module>
         <!-- Search for roles -->
         <login-module code="UserRoles" flag="required">
            <module-option name="password-stacking" value="useFirstPass"/>
            <module-option name="usersProperties" value="file://${jboss.server.config.dir}/spnego-users.properties"/>
            <module-option name="rolesProperties" value="file://${jboss.server.config.dir}/spnego-roles.properties"/>
         </login-module>
      </authentication>
   </security-domain>

2. You can add following combination VDB properties in the vdb.xml file to select or force the security-domain and authentication type:

   <property name="security-domain" value="EXAMPLE.COM"/>
   <property name="gss-pattern" value="{regex}" />
   <property name="password-pattern" value="{regex}" />
   <property name="authentication-type" value="GSS or USERPASSWORD" />
   		

   All the properties above are optional on a VDB. If you want to define VDB based security configuration "security-domain" property is required. If you want to enforce single authentication type use "authentication-type" property is required. If your security domain can support both GSS and USERPASSWORD, then you can define "gss-pattern" and "password-pattern" properties, and define a regular expression as the value. During the connection, these regular expressions are matched against the connecting user's name provided to select which authentication method user prefers. Here is a sample configuration:

   		
   <property name="security-domain" value="EXAMPLE.COM"/>
   <property name="gss-pattern" value="logasgss" />
   				

   In this case, if you passed the "user=logasgss" in the connection string, then GSS authentication is selected as login authentication mechanism. If the user name does not match, then default transport's authentication method is selected. Alternatively, if you want choose USERPASSWORD like this:

   		
   <property name="security-domain" value="EXAMPLE.COM"/>
   <property name="password-pattern" value="*-simple" />
   

   If the user name is "mike-simple", then that user will be subjected to authenticate against USERPASSWORD based authentication domain. You can configure different security-domains for different VDBS. VDB authentication will no longer be dependent upon underlying transport. If you wish to use "GSS" all the time then use this configuration:

   	
   <property name="security-domain" value="EXAMPLE.COM"/>
   <property name="authentication-type" value="GSS" />
   

3. Edit JVM configuration

   Edit the EAP_HOME/bin/MODE.conf file and add the following JVM options (changing the realm and kdc settings according to your environment):

   JAVA_OPTS = "$JAVA_OPTS -Djava.security.krb5.realm=EXAMPLE.COM -Djava.security.krb5.kdc=kerberos.example.com -Djavax.security.auth.useSubjectCredsOnly=false"

   You can also add these properties to the standalone.xml file, right after the {extensions} segment:

   	
   <system-properties>
       <property name="java.security.krb5.conf" value="/pth/to/krb5.conf"/>
       <property name="java.security.krb5.debug" value="false"/>
       <property name="javax.security.auth.useSubjectCredsOnly" value="false"/>
   </system-properties>
   

4. Set the security domains

   There are two ways to do this. You first option is to define one default authentication per transport:

   <transport name="jdbc" protocol="teiid" socket-binding="teiid-jdbc"/>
   <authentication security-domain="EXAMPLE.COM" type="GSS"/>
   </transport>

   Your second option is to secure only one virtual database:

   <property name="security-domain" value="EXAMPLE.COM"/>
   <property name="authentication-type" value="GSS" />
   

5. Restart the server

   Restart the server, ensuring there are no errors as it launches.

Procedure 8.3. Setup Kerberos for JDBC Client

1. Set JAAS configuration

   In the client VM the JAAS configuration for kerberos authentication needs to be written. Here is sample configuration file (client.conf):

   			Client {
       com.sun.security.auth.module.Krb5LoginModule required
       useTicketCache=true
       storeKey=true
       useKeyTab=true 
       keyTab="/path/to/krb5.keytab" 
       doNotPrompt=false 
       debug=false
       principal="user@EXAMPLE.COM";
   };

2. Set JVM configuration

   Add the following JVM options to your client's startup script. Change realm and kdc settings according to your environment:

   -Djava.security.krb5.realm=EXAMPLE.COM
   -Djava.security.krb5.kdc=kerberos.example.com
   -Djavax.security.auth.useSubjectCredsOnly=false
   -Dsun.security.krb5.debug=false
   -Djava.security.auth.login.config=/path/to/client.conf

   Or if you want to control the kdc and realm system wide, use below instead.

   -Djava.security.krb5.conf=/path/to/krb5.conf (on Linux /etc/krb5.conf)
   -Djava.security.auth.login.config=/path/to/client.conf
   -Djavax.security.auth.useSubjectCredsOnly=false
   -Dsun.security.krb5.debug=false
   

3. Set URL connection properties

   Add the following URL connection properties to the JBoss Data Virtualization JDBC connection string:

   authenticationType=KRB5;jaasName=Client;kerberosServicePrincipleName=dv/my.host.com@EXAMPLE.COM

Procedure 9.1. Create a Private/Public Key Pair with Keytool

1. Run the keytool -genkey -alias ALIAS -keyalg ALGORITHM -validity DAYS -keystore server.keystore -storetype TYPE command:

   keytool -genkey -alias teiid -keyalg RSA -validity 365 -keystore server.keystore -storetype JKS

2. If the specified keystore already exists, enter the existing password for that keystore, otherwise enter a new password:

   Enter keystore password: <password>

3. Answer the following questions when prompted:

   What is your first and last name?
   [Unknown]:  <user's name>
   What is the name of your organizational unit?
   [Unknown]:  <department name>
   What is the name of your organization?
   [Unknown]:  <company name>
   What is the name of your City or Locality?
   [Unknown]:  <city name>
   What is the name of your State or Province?
   [Unknown]:  <state name>
   What is the two-letter country code for this unit?
   [Unknown]:  <country name>

4. Enter yes to confirm the provided information is correct:

   Is CN=<user's name>, OU=<department name>, O="<company name>",
   L=<city name>, ST=<state name>, C=<country name>  correct?
   [no]:  yes

5. Enter your desired keystore password:

   Enter key password for <server>
   (Return if same as keystore password)

Procedure 9.2. Extract a Self-signed Certificate from the Keystore

1. Run the keytool -export -alias ALIAS -keystore server.keystore -rfc -file public.cert command:

   keytool -export -alias teiid -keystore server.keystore -rfc -file public.cert

2. Enter the keystore password when prompted:

   Enter keystore password: <password>

Procedure 9.3. Add a Certificate to a Truststore Using Keytool

1. Run the keytool -import -alias ALIAS -file public.cert -storetype TYPE -keystore server.truststore command:

   keytool -import -alias teiid -file public.cert -storetype JKS -keystore server.truststore

2. If the specified truststore already exists, enter the existing password for that truststore, otherwise enter a new password:

   Enter keystore password:  <password> 

3. Enter yes when prompted to trust the certificate:

   Owner: CN=<user's name>, OU=<dept name>, O=<company name>, L=<city>, ST=<state>, C=<country>
   Issuer: CN=<user's name>, OU=<dept name>, O=<company name>, L=<city>, ST=<state>, C=<country>
   Serial number: 416d8636
   Valid from: Fri Jul 31 14:47:02 CDT 2009 until: Sat Jul 31 14:47:02 CDT 2010
   Certificate fingerprints: 
            MD5:  22:4C:A4:9D:2E:C8:CA:E8:81:5D:81:35:A1:84:78:2F
            SHA1: 05:FE:43:CC:EA:39:DC:1C:1E:40:26:45:B7:12:1C:B9:22:1E:64:63
   Trust this certificate? [no]:  yes

1. Add an extension to the PicketLink subsystem:

    
   		<extensions>
     <extension module="org.picketlink.as.extension" />
   <extensions>
   

2. Configure the PicketLink subsystem:

    
   	<subsystem xmlns="urn:jboss:domain:picketlink:1.0">
     <federation alias="odata">
       <saml token-timeout="4000" clock-skew="0"/>
       <key-store url="/\{CERTIFICATE-FILE-NAME\}" passwd="\{PASSWD\}" sign-key-alias="\{CERTIFICATE-ALIAS\}" sign-key-passwd="\{PASSWD\}"/>
       <identity-provider url="\{SSO-IDP-POST-URL\}" alias="idp.war" security-domain="idp" supportsSignatures="true" strict-post-binding="true">
    
         <trust>
           <trust-domain name="localhost" cert-alias="\{CERTIFICATE-ALIAS\}"/>
           <trust-domain name="127.0.0.1" cert-alias="\{CERTIFICATE-ALIAS\}"/>
           <trust-domain name="{IDP-DNS-NAME}" cert-alias="\{CERTIFICATE-ALIAS\}"/>
         </trust>
       </identity-provider>
       <service-providers>
       <service-provider alias="odata.war" security-domain="sp" url="http://\{SP-DNS-NAME\}:8080/odata/" post-binding="true" supportsSignatures="true"/>
       </service-providers>
     </federation>
   </subsystem>
   

   Note

   Normally, the certificate alias is the domain name, such as "idp.jboss.org"
3. Configure the security domains to be used by the security provider:

    
   	<subsystem xmlns="urn:jboss:domain:security:1.2">
       <security-domains>
           <security-domain name="sp" cache-type="default">
               <authentication>
                   <login-module code="org.picketlink.identity.federation.bindings.jboss.auth.SAML2LoginModule" flag="required"/>
                   <login-module code="org.jboss.security.ClientLoginModule" flag="required"/>
               </authentication>
           </security-domain>
       </security-domains>
   </subsystem>
   

4. Change the OData transport in the Teiid subsystem:

    
   	 <transport name="odata">
        <authentication security-domain="sp"/>
      </transport>
   

5. Move the teiid-odata-xxxx.war file from dataVirtualization/vdb/teiid-odata-xxx.war to a temporary location.
6. Edit the jboss-web.xml file:

    
   	<?xml version="1.0" encoding="UTF-8"?>
   <jboss-web>
       <context-root>odata</context-root>
   </jboss-web>
   

7. Edit the web.xml file:

    
   	<?xml version="1.0" encoding="UTF-8"?>
   <web-app xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://java.sun.com/xml/ns/javaee" xmlns:web="http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd" xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd" version="2.5">
       <display-name>odata</display-name>
       <context-param>
           <param-name>javax.ws.rs.Application</param-name>
           <param-value>org.teiid.odata.TeiidODataApplication</param-value>
       </context-param>  
       <context-param>
           <param-name>batch-size</param-name>
           <param-value>256</param-value>
       </context-param> 
       <context-param>
           <param-name>skiptoken-cache-time</param-name>
           <param-value>300000</param-value>
       </context-param>  
       <context-param>
           <param-name>local-transport-name</param-name>
           <param-value>odata</param-value>
       </context-param>     
       <listener>
           <listener-class>org.jboss.resteasy.plugins.server.servlet.ResteasyBootstrap</listener-class>
       </listener>   
       <servlet>
           <servlet-name>Resteasy</servlet-name>
           <servlet-class>org.teiid.odata.ODataServlet</servlet-class>
       </servlet>    
        
       <servlet-mapping>
           <servlet-name>Resteasy</servlet-name>
           <url-pattern>/*</url-pattern>
       </servlet-mapping>
             
       <security-constraint>
           <display-name>require valid user</display-name>
           <web-resource-collection>
               <web-resource-name>Teiid Rest Application</web-resource-name>
               <url-pattern>/*</url-pattern>
           </web-resource-collection>
           <auth-constraint>
               <role-name>*</role-name>
           </auth-constraint>
       </security-constraint>
    
       <login-config>
           <auth-method>FORM</auth-method>
           <realm-name>sp</realm-name>
           <form-login-config>
               <form-login-page>/jsp/login.jsp</form-login-page>
               <form-error-page>/jsp/loginerror.jsp</form-error-page>
           </form-login-config>
       </login-config>
             
        <security-role>
           <description>security role</description>
           <role-name>*</role-name>
       </security-role>
         
   </web-app>
   

8. Add the certificate received from IDP vendor to the WEB-INF/classes directory.

   Note

   This must be same name as {CERTIFICATE-FILE-NAME} used in when you configured the PicketLink subsystem.
9. Recreate the WAR file based on the modified contents of the other files by running this command: jar -cvf teiid-odata-xxxx.war /temp/*
10. Copy the newly-created WAR file into the /modules/system/base/org/jboss/teiid/main/deployments directory.
11. Start the Data Virtualization server, and access the OData URL, You will be redirected to the SSO-based authentication.

Procedure 11.1. Subscribe to the JBoss Watch List

1. Click the following link to go to the JBoss Watch mailing list page: JBoss Watch Mailing List.
2. Enter your email address in the Subscribing to Jboss-watch-list section.
3. [You may also wish to enter your name and select a password. Doing so is optional but recommended.]
4. Press the Subscribe button to start the subscription process.
5. You can browse the archives of the mailing list by going to: JBoss Watch Mailing List Archives.

Procedure 11.4. Apply a patch to a JBoss product via the RPM method

1. Get notified about the security patch either via being a subscriber to the JBoss watch mailing list or by browsing the JBoss watch mailing list archives.
2. Read the errata for the security patch and confirm that it applies to a JBoss product in your environment.
3. If the security patch applies to a JBoss product in your environment, then follow the link to download the updated RPM package which is included in the errata.
4. Use

   yum update

   to install the patch.

   Important

   When updating an RPM installation, your JBoss product is updated cumulatively with all RPM-released fixes.