[Apache Geronimo Wiki] Updated: Security

[sc...@geronimo.apache.org]

   Date: 2004-11-20T00:56:19
   Editor: AaronMulder <am...@alumni.princeton.edu>
   Wiki: Apache Geronimo Wiki
   Page: Security
   URL: http://wiki.apache.org/geronimo/Security

   no comment

Change Log:

------------------------------------------------------------------------------
@@ -6,16 +6,104 @@
 
 '''Security Realm:''' This is what most app servers would consider to be a security realm.  It has a name, and a set of back-end stuff that makes authentication work.  It can do auditing and lockout and so on.  As it happens, under the covers, it uses a series of Login Modules to make this work.
 
-'''Login Module:''' A JAAS LoginModule, which is a portable API for security services.  In theory any login module should work with any product; however, some of the ones we ship with Geronimo take advantage of Geronimo-specific features and wouldn't really work elsewhere.  Still, any portable JAAS login module developed elsewhere will run fine in Geronimo.  A Login Module may represent a back-end Login Domain, or it might just enforce a policy (such as auditing every login attempt).  It's up to you to arrange the login modules (order and control flags) in the Security Realm to get the desired effect.
+'''Login Module:''' A JAAS {{{LoginModule}}}, which is a portable API for security services.  In theory any login module should work with any product; however, some of the ones we ship with Geronimo take advantage of Geronimo-specific features and wouldn't really work elsewhere.  Still, any portable JAAS login module developed elsewhere will run fine in Geronimo.  A Login Module may represent a back-end Login Domain, or it might just enforce a policy (such as auditing every login attempt).  It's up to you to arrange the login modules (order and control flags) in the Security Realm to get the desired effect.
 
 '''Login Domain:''' What your network administrator might consider to be a security realm -- Active Directory, LDAP, a SQL database with security information, a Netegrity or RSA product, etc.  A valid source of authentication information (typically, users and groups).  When you successfully log in to a login domain, you get a set of Principals that identify you (usually one of type user and several of type group, though any type of Principal is possible).  The way for a Geronimo application to interact with a Login Domain is to configure a Login Module for that Login Domain, and then stuff the Login Module into a Security Realm.
 
-'''Principal:''' Something that a Login Domain (via a LoginModule) uses to identify you.  Implements {{{java.security.Principal}}}.  Every Login Domain may use different Principal types.  So when you go to map users to J2EE roles, you need to say which Principal class / Principal name combinations map to each role -- the equivalent of "user Bob" or "group Developers" should be in a role.  You should also say which Login Domain this applies to, so if there were 2 different LDAP servers, you could say "user Bob from the Finance LDAP server and group Developers from the Engineering LDAP server" should be in a role.  However, that's not presently implemented correctly.
+'''Principal:''' Something that a Login Domain (via a {{{LoginModule}}}) uses to identify you.  Implements {{{java.security.Principal}}}.  Every Login Domain may use different Principal types.  So when you go to map users to J2EE roles, you need to say which Principal class / Principal name combinations map to each role -- the equivalent of "user Bob" or "group Developers" should be in a role.  You should also say which Login Domain this applies to, so if there were 2 different LDAP servers, you could say "user Bob from the Finance LDAP server and group Developers from the Engineering LDAP server" should be in a role.  However, that's not presently implemented correctly.
 
 '''Control Flag:''' There are 4 possible control flags for a login module, and they indicate what should happen in the overall login process if a particular login module succeeds or fails.  For the specific options and what they mean, see http://java.sun.com/j2se/1.4.2/docs/api/javax/security/auth/login/Configuration.html
 
-= Security Realms & Login Modules =
+= Current State =
 
+== Configuring LoginModules and Security Realms ==
+
+To configure a security realm, you must first declare login modules (one GBean each) and then declare a security realm that uses those login modules.  Here's an example:
+
+{{{
+<gbean name="geronimo.security:type=LoginModule,name=properties-login"
+    class="org.apache.geronimo.security.jaas.LoginModuleGBean">
+    <attribute name="loginModuleClass" type="java.lang.String">
+        org.apache.geronimo.security.realm.providers.PropertiesFileLoginModule
+    </attribute>
+    <attribute name="serverSide" type="boolean">true</attribute>
+    <attribute name="options" type="java.util.Properties">
+        usersURI=var/security/users.properties
+        groupsURI=var/security/groups.properties
+    </attribute>
+</gbean>
+
+<gbean name="geronimo.security:type=LoginModule,name=credential-populator"
+    class="org.apache.geronimo.security.jaas.LoginModuleGBean">
+    <attribute name="loginModuleClass" type="java.lang.String">
+        org.apache.geronimo.security.realm.providers.GeronimoPasswordCredentialLoginModule
+    </attribute>
+    <attribute name="serverSide" type="boolean">true</attribute>
+</gbean>
+
+<gbean name="geronimo.security:type=SecurityRealm,realm=geronimo-properties-realm"
+       class="org.apache.geronimo.security.realm.GenericSecurityRealm">
+    <attribute name="realmName" type="java.lang.String">geronimo-properties-realm</attribute>
+    <attribute name="loginModuleConfiguration" type="java.util.Properties">
+        LoginModule.1.REQUISITE=geronimo.security:type=LoginModule,name=properties-login
+        LoginModule.2.OPTIONAL=geronimo.security:type=LoginModule,name=credential-populator
+    </attribute>
+    <reference name="ServerInfo">geronimo.system:role=ServerInfo</reference>
+    <attribute name="autoMapPrincipalClasses" type="java.lang.String">
+        org.apache.geronimo.security.realm.providers.PropertiesFileGroupPrincipal
+    </attribute>
+</gbean>
+}}}
+
+In this example we configure a {{{PropertiesFileLoginModule}}} (which loads users and groups from separate files), and a credential populator (which stores a user's credentials for use by realm bridges).  The properties file module takes options indicating where to find the properties files, while the credential populator has no relevent options.  The security realm configuration declares the properties file module as REQUISITE (it's required, and the login will immediately fail if it doesn't succeed) and the credential populator as OPTIONAL (it will be used, but if it doesn't succeed for some reason, we don't stop the login).
+
+== Configuring Server Components to Talk to Security Realms ==
+
+The {{{LoginService}}} component manages security realms and logins.  However, it's a bit painful to deal with directly, so we provide a handy helper class.
+
+The {{{JaasLoginCoordinator}}} does the dirty work of dealing with the {{{LoginService}}} on your behalf.  The {{{JaasLoginCoordinator}}} is itself a {{{LoginModule}}}, so you think you're dealing with one single {{{LoginModule}}}, where under the covers it's interacting with the {{{LoginService}}} and a security realm that may be configured with an arbitrarily complex set of login modules.
+
+Each security realm automatically has a {{{JaasLoginCoordinator}}} registered under the same name as the security realm name.  If you can just use that, then no further configuration is necessary.
+
+Otherwise, to set up a configuration with a different name than the realm name, you usually create a {{{ServerRealmConfigurationEntry}}} GBean, where you give it the name of the realm you want to work with, and the name you plan to use to identify it when you try to log in (which must be different than the realm name so as not to conflict with the automatic mapping above).  You might give it the realm name "foo-realm" and the configuration name "foo-client".  Then when you try to login to "foo-client", under the covers, it will log you in using all the login modules configured for the security realm "foo-realm".  A typical configuration looks like this:
+
+{{{
+<gbean name="geronimo.security:type=ConfigurationEntry,jaasId=foo-client"
+       class="org.apache.geronimo.security.jaas.ServerRealmConfigurationEntry">
+    <attribute name="applicationConfigName" type="java.lang.String">foo-client</attribute>
+    <attribute name="realmName" type="java.lang.String">foo-realm</attribute>
+</gbean>
+}}}
+
+== Configuring Clients to Talk to Security Realms ==
+
+This is pretty much the same, only you need to manually configure the client to use a {{{JaasLoginCoordinator}}}, and give it the realm name and server host/port as options.  Typically, you'd use a JAAS configuration file to do this, with an entry like this:
+
+{{{
+my-app {
+    org.apache.geronimo.security.jaas.JaasLoginCoordinator required
+    host="localhost"
+    port="4242"
+    realm="my-realm";
+};
+}}}
+
+In this case, the configuration name can be the same as the realm name, because the coordinator configuration runs on the client side and the realm configuration runs on the server side.  Still, it might be easier to make them different, so the configuration name identifies the application while the realm name identifies the security realm, as in the example above.
 
 
 = Future Changes =
+
+There are a number of to-dos in the security area:
+
+ * We need to provide more login modules, including:
+   * One that audits every login attempt to a file in {{{var/}}} somewhere
+   * One that rejects logins for a user after X unsuccessful attempts (in a row or in Y minutes)
+   * One that validates against an LDAP login domain
+ * The current {{{RealmPrincipal}}} gets the security realm name, whereas it really should get the login domain name
+ * Therefore, we need to be able to specify a login domain name for every login module
+ * Role mapping needs to change to support login domain names
+   * The mapping should go by login domain name, principal class, and principal name
+   * You should be able to specify more than one default principal; for example, you might want the default (unauthenticated) subject to get one user principal and two group principals
+ * Auto-mapping of principals to groups needs to be enhanced (better configuration, etc.)
+ * The old functionality to get a list of all available users and groups from a security realm has been broken.  It needs to be brought back in the form of a helper class that can be configured on the {{{GenericSecurityRealm}}}.
+ * We need more tests of all this functionality