Date: 2004-11-20T00:56:19
Editor: AaronMulder <[EMAIL PROTECTED]>
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
