[teiid-commits] teiid SVN: r1976 - in trunk/documentation/server-extensions-guide/src/main/docbook/en-US: content and 1 other directory.

Author: shawkins Date: 2010-03-18 21:45:14 -0400 (Thu, 18 Mar 2010) New Revision: 1976 Removed: trunk/documentation/server-extensions-guide/src/main/docbook/en-US/content/custom-membership.xml Modified: trunk/documentation/server-extensions-guide/src/main/docbook/en-US/content/appendix-a.xml trunk/documentation/server-extensions-guide/src/main/docbook/en-US/content/introduction.xml trunk/documentation/server-extensions-guide/src/main/docbook/en-US/content/security.xml trunk/documentation/server-extensions-guide/src/main/docbook/en-US/server_extensions_guide.xml Log: TEIID-877 cleansed the extension doc for 7.0 Modified: trunk/documentation/server-extensions-guide/src/main/docbook/en-US/content/appendix-a.xml =================================================================== --- trunk/documentation/server-extensions-guide/src/main/docbook/en-US/content/appendix-a.xml 2010-03-19 00:20:58 UTC (rev 1975) +++ trunk/documentation/server-extensions-guide/src/main/docbook/en-US/content/appendix-a.xml 2010-03-19 01:45:14 UTC (rev 1976) @@ -1,29 +1,6 @@ <appendix id="advanced_topics"> <title>Advanced Topics</title> <sect1> - <title>Authentication Interceptor</title> - <para>In some circumstances a trusted payload may be applicable to authenticating in several membership - domains or may be a secondary authentication method for a built-in LDAP membership domain.  In these - situations a custom membership domain (intercepting domain) may be introduced at the beginning of the domain - list to authenticate into other domains.  To achieve this, the SuccessfulAuthenticationToken returned by the - intercepting domain should contain a fully qualified user name to a target domain.  </para> - <para /> - <para>The interceptor domain may be solely focused on authentication.  If it only authenticates into other - domains, then the interceptor domain may provide dummy implementations of the getGroupNames and - getGroupNamesforUser methods.</para> - </sect1> - <sect1> - <title>Deployment Considerations</title> - <para>Membership domains are not individual services that can be independently configured within a - cluster, rather they are dependent upon Membership Service instances.  Each installed membership domain - instance will be active on each MMProcess with a Membership Service.  </para> - <para /> - <para>NOTE: Since the Membership Service cannot be restarted changes to membership domain configurations - require bouncing the Teiid Server before taking effect.  It follows also that if a custom membership is - not written to recover gracefully from connectivity or other environmental issues a server restart is - required to re-initialize the membership domain.</para> - </sect1> - <sect1> <title>Migration From Previous Versions</title> <para>It is recommended that customers who have utilized the internal JDBC membership domain from releases prior to MetaMatrix 5.5 migrate those users and groups to an LDAP compliant directory server.  Several free @@ -40,8 +17,6 @@ Apache Directory Server <ulink url="http://directory.apache.org/">http://directory.apache.o... </para> - <para>Implementations of the MembershipDomainInterface interface from releases prior to - MetaMatrix 5.5 will need to be manually migrated to the new MembershipDomain interface. </para> <para>If there are additional questions or the need for guidance in the migration process, please contact technical support.</para> </sect1> Deleted: trunk/documentation/server-extensions-guide/src/main/docbook/en-US/content/custom-membership.xml =================================================================== --- trunk/documentation/server-extensions-guide/src/main/docbook/en-US/content/custom-membership.xml 2010-03-19 00:20:58 UTC (rev 1975) +++ trunk/documentation/server-extensions-guide/src/main/docbook/en-US/content/custom-membership.xml 2010-03-19 01:45:14 UTC (rev 1976) @@ -1,216 +0,0 @@ -<?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"> -<chapter id="custom_membership"> - <title>Custom Membership Domains</title> - <sect1> - <title>Creating a Custom Membership Domain</title> - <para>The creation of a custom membership domain based upon the MembershipDomain interface allows for easy - extensibility of the Teiid security system.   The API and associate classes are focused solely on - conveying authentication and group information.  At this time other development concerns, such as access to - the internal logging facilities, are not documented or generally available to custom membership domain - implementors.</para> - <para>Within the development IDE of choice the custom membership domain developer should add the - server-api.jar to project's classpath.  From there the MembershipDomain interface and the related classes can - be extended to create custom membership domain.</para> - <para>Custom membership domains should be implemented to the specific needs of the external security - system.  For example, in cases where explicit initialization or shutdown is not applicable the - implementations of these methods may be left empty.</para> - <para>For membership domains that do require configuration information, the initialization method provides a - built-in mechanism for provide a specific set of values.  Each instance of a custom membership domain defined - through the Console can have a different properties file to drive its initialization.  The lookup of a - properties file specified through the console will search the classpath, the filesystem, and finally as a URL - in that order.  </para> - <para>Once the classes that represent the custom membership domain have been implemented they can be made - available to a server installation by adding their jar file into the &lt;server install root&gt;/lib/patches directory.  If the server - is part of a multi-host cluster, the jar must be added to each host running a Membership Service.</para> - <para>From there the Console can be used to install and configure the custom membership domain for use in - the server environment.  See the Console Guide for detailed instructions.</para> - <sect2> - <title>Membership Domain API</title> - <para> - The com.metamatrix.platform.security.membership.spi.MembershipDomain - interface must be implemented to create a custom membership domain. The implementation class will then be - installed and configured in server to enable the custom membership domain. - </para> - </sect2> - <sect2> - <title>File Membership Domain Example</title> - <para>The following section contains an example of a membership domain that uses simple text files to - determine user authentication and group membership. The users are listed in a properties file containing - username=password entries. The group memberships are listed in a properties file containing comma - groupname=[username[,username]*] entries.</para> - <programlisting><![CDATA[ -import ... - -public class FileMembershipDomain implements MembershipDomain { - public static final String USERS_FILE = "usersFile"; - public static final String GROUPS_FILE = "groupsFile"; - public static final String CHECK_PASSWORD = "checkPassword"; - - private boolean checkPasswords; - private Properties users; - private HashMap groups = new HashMap(); - private HashMap userGroups = new HashMap(); - - private Properties loadFile(String fileName) throws ServiceStateException { - Properties result = new Properties(); - - //try the classpath - InputStream is = this.getClass().getResourceAsStream(fileName); - - if (is == null) { - try { - //try the filesystem - is = new FileInputStream(fileName); - } catch (FileNotFoundException err) { - try { - //try a url - is = new URL(fileName).openStream(); - } catch (MalformedURLException err1) { - throw new ServiceStateException(err, "Could not load file "+fileName+" for FileMembershipDomain"); - } catch (IOException err1) { - throw new ServiceStateException(err1, "Could not load file "+fileName+" for FileMembershipDomain"); - } - } - } - - try { - result.load(is); - } catch (IOException err) { - throw new ServiceStateException(err, "Could not load file "+fileName+" for FileMembershipDomain"); - } finally { - try { - is.close(); - } catch (IOException err) { - } - } - return result; - } - - public void shutdown() throws ServiceStateException { - } - -.... <covered in the next pages> ... - -} - ]]></programlisting> - - <para>The above snippet is shows a class that implements the MembershipDomain interface. In this example no - meaningful is performed in the shutdown method, so its implementation is left empty. The loadFile method is a - simple utility method that will be used to load the users and groups files during initialization (shown in the - next snippet).</para> - - <programlisting><![CDATA[ -public void initialize(Properties env) throws ServiceStateException { - checkPasswords = Boolean.valueOf(env.getProperty(CHECK_PASSWORD, Boolean.TRUE.toString())).booleanValue(); - - String userFile = env.getProperty(USERS_FILE); - String groupFile = env.getProperty(GROUPS_FILE); - - if (userFile == null) { - throw new ServiceStateException("Required property " +USERS_FILE+ " was missing."); - } - - users = loadFile(userFile); - - if (groupFile == null) { - throw new ServiceStateException("Required property " +GROUPS_FILE+ " was missing."); - } - - groups.clear(); - groups.putAll(loadFile(groupFile)); - userGroups.clear(); - for (Iterator i = groups.entrySet().iterator(); i.hasNext();) { - Map.Entry entry = (Map.Entry)i.next(); - String group = (String)entry.getKey(); - String userNames = (String)entry.getValue(); - String[] groupUsers = userNames.split(","); //$NON-NLS-1$ - - for (int j = 0; j < groupUsers.length; j++) { - String user = groupUsers[j].trim(); - Set uGroups = (Set)userGroups.get(user); - if (uGroups == null) { - uGroups = new HashSet(); - userGroups.put(user, uGroups); - } - uGroups.add(group); - } - } -} - ]]></programlisting> - <para>The initialize method is written to expect two properties “usersFile” and “groupsFile”. Values for these - properties should be defined in the properties file specified in the “properties file” connector binding. An - optional property “checkPasswords” may be specified that will determine if the membership domain should check - the credentials specified as passwords.</para> - <programlisting><![CDATA[ -public SuccessfulAuthenticationToken authenticateUser(String username, Credentials credential,Serializable trustedPayload, String applicationName) - throws UnsupportedCredentialException,InvalidUserException,LogonException,MembershipSourceException { - if (username == null || credential == null) { - throw new UnsupportedCredentialException("a username and password must be supplied for this domain"); - } - - String password = (String)users.get(username); - - if (password == null) { - throw new InvalidUserException("user " + username + " is invalid"); - } - - if (!checkPasswords || password.equals(String.valueOf(credential.getCredentialsAsCharArray()))) { - return new SuccessfulAuthenticationToken(trustedPayload, username); - } - - throw new LogonException("user " + username + " could not be authenticated"); -} - ]]></programlisting> - <para>The authenticateUser method implementation demonstrates several possible outcomes for an authentication - attempt.  If a user name and password (in the form of a Credentials object) are not supplied the domain will - indicate that it does not support the authentication attempt.  In this case for unqualified logons, - authentication would proceed to the next membership domain.</para> - <para /> - <para>If a password cannot be found for the user name cannot be found in the users file, then the domain - reports that the user is not valid for the current domain.  As with the previous case, unqualified logons would - proceed to the next membership domain.  </para> - <para /> - <para>If the domain is not checking passwords or the password value matches the supplied credentials, the - membership domain returns a SuccessfulAuthenticationToken.  This token may contain an augmented value of the - trustedPayload, however in this example the value that was passed in is returned unchanged.</para> - <para /> - <para>Finally if authentication was not successful, a LogonException is thrown to indicate the user has - failed authentication.  Authentication failure due to a LogonException will immediately fail the overall user - authentication even with an unqualified logon.</para> - <para /> - <para>NOTE: The message text, and any chained exceptions, in an UnsupportedCredentialException, -  InvalidUserException, or LogonException will appear in server log.</para> - - <programlisting><![CDATA[ -public Set getGroupNames() throws MembershipSourceException { - Set resultNames = new HashSet(groups.keySet()); - return resultNames; -} - -public Set getGroupNamesForUser(String username) throws InvalidUserException, - MembershipSourceException { - // See if this user is in the domain - if (!users.containsKey(username)) { - throw new InvalidUserException("user " + username + " is invalid"); - } - - Set usersGroups = (Set)userGroups.get(username); - if (usersGroups == null) { - return Collections.EMPTY_SET; - } - return usersGroups; -} - ]]></programlisting> - - <para>The last two methods needed to implement the MembershipDomain interface are shown above.  The - getGroupNames  method returns all known group names from the groups file.  The getGroupNamesForUser method - returns all groups for the given user.  The mapping from users to groups was established in the initialize - method.</para> - <para /> - <para>NOTE: It is important that the return values from all of the MembershipDomain methods are Serializable</para> - <para>NOTE:  The preceding example is case sensitive with respect to user names.  The Teiid system does - not require logons to be case insensitive.  That is up to the implementation of the member domain.</para> - </sect2> - </sect1> -</chapter> \ No newline at end of file Modified: trunk/documentation/server-extensions-guide/src/main/docbook/en-US/content/introduction.xml =================================================================== --- trunk/documentation/server-extensions-guide/src/main/docbook/en-US/content/introduction.xml 2010-03-19 00:20:58 UTC (rev 1975) +++ trunk/documentation/server-extensions-guide/src/main/docbook/en-US/content/introduction.xml 2010-03-19 01:45:14 UTC (rev 1976) @@ -2,18 +2,14 @@ <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> <chapter id="introduction"> <title>Introduction</title> - <para>This guide introduces to all the user extensions that are supported by the Teiid server. These - extensions are provided to let user introduce custom functionality into their deployment of the server. - All the extensions are provided though implementing Java based API.</para> - - <para>The following are the currently available extensions</para> - <orderedlist> - <listitem> - <para><link linkend="custom_security">Teiid Security</link></para> - </listitem> - <listitem> - <para><link linkend="command_logging">Command Logging</link></para> - </listitem> - </orderedlist> + <para>This guide introduces the extensions supported by Teiid to introduce custom functionality.</para> + <orderedlist> + <listitem> + <para><link linkend="custom_security">Teiid Security</link></para> + </listitem> + <listitem> + <para><link linkend="command_logging">Command Logging</link></para> + </listitem> + </orderedlist> </chapter> \ No newline at end of file Modified: trunk/documentation/server-extensions-guide/src/main/docbook/en-US/content/security.xml =================================================================== --- trunk/documentation/server-extensions-guide/src/main/docbook/en-US/content/security.xml 2010-03-19 00:20:58 UTC (rev 1975) +++ trunk/documentation/server-extensions-guide/src/main/docbook/en-US/content/security.xml 2010-03-19 01:45:14 UTC (rev 1976) @@ -1,111 +1,93 @@ <?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"> <chapter id="custom_security"> - <title>Teiid Security</title> - <sect1> - <title>Teiid Security</title> - <sect2> - <title>Introduction</title> - <para>The Teiid system provides a range of built-in and extensible security features to enable the - secure access of data.  </para> - <para /> - <para>For more detailed information see the:</para> - <orderedlist> - <listitem> - <para>Console Guide – for instructions on how to set a range of security - settings, on installing Membership Domains, and on setting up roles.</para> - </listitem> - <listitem> - <para>Connector Developers Guide – for information on how custom connectors can be - developed with advanced security features.</para> - </listitem> - <listitem> - <para>Web Services Guide – for information on how to secure web service - access to Teiid</para> - </listitem> - <listitem> - <para>Client Developers Guide – for information on how to authenticate - through JDBC and ODBC.</para> - </listitem> - </orderedlist> - </sect2> - <sect2> - <title>Authentication</title> - <para>JDBC, ODBC, and web service clients may use simple passwords, a pass-through mechanism called a - trusted payload, or a combination of that and related information to authenticate a user.  </para> - <para /> - <para>Typically a user name is required, however user names may be considered optional if the - identity of the user can be discerned from the trusted payload or another mechanism.  In any case it is up - to the installed membership domains to actually determine whether a user can be authenticated.</para> - <para /> - <para>NOTE: All passwords or security credentials that are passed through the Teiid system will - either be encrypted or sent of an encrypted transport by default.</para> - </sect2> - <sect2> - <title>Authorization</title> - <para>Authorization is split into three areas of concern.  Admin roles, repository roles, and - data roles can be managed in the Console to enforce authorization of administrative tasks, the MetaBase - repository, and enterprise data respectively.  A role is simply a collection of permissions and a - collection of entitled principals.  Currently the Teiid security system only allows principals that - represent groups to be assigned to a role. The set of available groups are determined by the installed - membership domains.</para> - </sect2> - </sect1> - <sect1> - <title> Membership Domains</title> - <para>Membership domains are at the core of Teiid’s security system and bridge the gap between - Teiid and an external security system.  A membership domain provides:</para> - <itemizedlist> - <listitem> - <para>User authentication</para> - </listitem> - <listitem> - <para>A set of groups</para> - </listitem> - <listitem> - <para>The groups to which an authenticated user belongs</para> - </listitem> - </itemizedlist> - <para>Access to membership domains is coordinated through the Membership Service.  The Membership - Service together with the Authorization Service implement the necessary logic to authenticate users, - determine role membership, and to enforce roles.</para> - <para> - There are multiple types of membership domains that allow for connectivity to different security systems. -  A Teiid server environment can be configured with multiple membership domains (there can be multiple - instances of a given membership domain type).  Each membership domain instance must be assigned a unique - domain name in the Teiid system.  The domain name can be used to fully qualify user names to - authenticate only against that domain.  The format for a qualified name is - <ulink url="mailto:username@domain">username@domainname.</ulink> - </para> - <para>If a user name is not fully qualified, then the installed membership domains will be consulted in - order until a domain successfully or unsuccessfully authenticates the user.  If a membership domain reports - the user does not exist or that the credentials are not recognized, that is not considered an unsuccessful - authentication and the next membership domain will be consulted.</para> - <para>If no membership domain can authenticate the user, the logon attempt will fail.  For any failed logon - attempt the message the users sees will always be the same.  It will simply indicate the user could not be - authenticated by any membership domain – it will not reveal any further details which could potentially be - sensitive information.  Details including invalid users, which domains were consulted, etc. will be in the - server log with appropriate levels of severity.</para> - <sect2> - <title>Built-in Membership Domains</title> - <para>The Teiid System provides LDAP and File membership domain types.  </para> - <para>The LDAP membership domain provides flexible integration with a variety of LDAP servers through JNDI - (Java Naming and Directory Interface).  Enterprise environments with an LDAP compliant directory server - should attempt to utilize the built-in LDAP membership domain before attempting to create a custom - solution.</para> - <para>The File membership domain utilizes a simple set of text files to authenticate users and to define - their groups.  Please note however that the File membership domain is not intended for production use. - </para> - <para>Instructions for configuring both of these can be found in the Teiid Console Guide.</para> - <para>Support will be added for additional membership domains with subsequent releases.</para> - </sect2> - <sect2> - <title>Custom Membership Domains</title> - <para>In circumstances not covered by a built-in membership domain, a custom membership domain allows the - Teiid security system to interact seamlessly with other enterprise security providers.  </para> - <para>Java development is required to implement a custom membership domain.  The API and a full example - are covered in the following chapters of this document.</para> - </sect2> - </sect1> - + <title>Teiid Security</title> + <para>The Teiid system provides a range of built-in and extensible + security features to enable the + secure access of data.  </para> + <sect1> + <title>Authentication</title> + <para>JDBC clients may use simple passwords to authenticate a user. + </para> + <para>Typically a user name is required, however user names may be + considered optional if the + identity of the user can be discerned by + the password credential alone.  In + any case it is up + to the configured + security domain to determine whether a user can be + authenticated. + </para> + </sect1> + <sect1> + <title>Authorization</title> + <para>Authorization covers both administrative activities and + data + roles.  A data role is a collection of permissions (also referred to + as entitlements) and a + collection of entitled principals or groups. + With the deployment of a VDB + the deployer can choose which principals + and groups have which data roles.</para> + </sect1> + <sect1> + <title>Encryption</title> + <para>At a transport level Teiid provides built-in support for JDBC + over SSL or just sensitive message encryption when SSL is not in use. + </para> + <para> + Passwords in configuration files however are by default stored in + plain text. If you need these values to be encrypted, please see + <ulink + url="http://community.jboss.org/wiki/maskingpasswordsinjbossasxmlcon... passwords</ulink> + for instructions on encryption facilities provided by the container. + </para> + </sect1> + <sect1> + <title>LoginModules</title> + <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. See + <ulink + url="http://docs.jboss.org/jbossas/admindevel326/html/ch8.chapter.ht... Security</ulink> + for general information on configuring security in JBossAS.</para> + <para> + Teiid can be configured with multiple named application policies + that group together relevant LoginModules. Each of these application + policy (or domains) names can be used to fully + qualify user names to + authenticate only against that domain.  The format for a qualified + name is username@domainname. + </para> + <para>If a user name is not fully qualified, then the installed + domains will be consulted in order until a domain + successfully or unsuccessfully authenticates the + user. + </para> + <para>If no domain can authenticate the user, the logon + attempt will fail. + Details of the failed attempt including invalid users, which + domains were consulted, etc. will be in the server log with appropriate + levels of severity.</para> + <sect2> + <title>Built-in LoginModules</title> + <para>JBossAS provides several LoginModules for common authentication needs, such as authenticating from text files or LDAP.</para> + <para>The UsersRolesLoginModule, which utilizes simple text files + to authenticate users and to define + their groups.  The teiid-jboss-beans.xml configuration file contains an example of how to use UsersRolesLoginModule. + Note that this is typically not for production use. + </para> + <para>See <ulink url="http://community.jboss.org/docs/DOC-11253">LDAP LoginModule configuration</ulink> for utilizing LDAP based authentication. + </para> + </sect2> + <sect2> + <title>Custom LoginModules</title> + <para> + If your authentication needs go beyond the provided LoginModules, please consult the + <ulink url="http://java.sun.com/j2se/1.5.0/docs/guide/security/jaas/JAASLMD... development guide</ulink>. + There are also numerous guides available. + </para> + </sect2> + </sect1> </chapter> \ No newline at end of file Modified: trunk/documentation/server-extensions-guide/src/main/docbook/en-US/server_extensions_guide.xml =================================================================== --- trunk/documentation/server-extensions-guide/src/main/docbook/en-US/server_extensions_guide.xml 2010-03-19 00:20:58 UTC (rev 1975) +++ trunk/documentation/server-extensions-guide/src/main/docbook/en-US/server_extensions_guide.xml 2010-03-19 01:45:14 UTC (rev 1976) @@ -48,7 +48,6 @@ <xi:include href="content/introduction.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> <xi:include href="content/logging.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> <xi:include href="content/security.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <xi:include href="content/custom-membership.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> <xi:include href="content/appendix-a.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> </book>