[teiid-commits] teiid SVN: r1976 - in trunk/documentation/server-extensions-guide/src/main/docbook/en-US: content and 1 other directory.
teiid-commits at lists.jboss.org
teiid-commits at lists.jboss.org
Thu Mar 18 21:45:14 EDT 2010
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.org/</ulink>
</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 <server install root>/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 at domain">username at 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/maskingpasswordsinjbossasxmlconfiguration">encrypting 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.html">JBossAS 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 at 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/JAASLMDevGuide.html">JAAS 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>
More information about the teiid-commits
mailing list