| = Security |
| :index-group: Configuration |
| :jbake-date: 2018-12-05 |
| :jbake-type: page |
| :jbake-status: published |
| |
| = Security - How To. |
| |
| We currently have two authentication mechanisms to choose from: * |
| _PropertiesLoginModule_ (a basic text file based login that looks up |
| users and groups from the specified properties files) * _SQLLoginModule_ |
| (database based login that looks up users and groups in a database |
| through SQL queries) |
| |
| To make your program authenticate itself to the server, simply construct |
| your InitialContext with the standard javax.naming.Context properties |
| for user/pass info, which is: |
| |
| [source,java] |
| ---- |
| Properties props = new Properties(); |
| props.setProperty(Context.INITIAL_CONTEXT_FACTORY, "org.apache.openejb.client.RemoteInitialContextFactory"); |
| props.setProperty(Context.PROVIDER_URL, "ejbd://localhost:4201"); |
| props.setProperty(Context.SECURITY_PRINCIPAL, "someuser"); |
| props.setProperty(Context.SECURITY_CREDENTIALS, "thepass"); |
| props.setProperty("openejb.authentication.realmName", "PropertiesLogin"); |
| // optional |
| InitialContext ctx = new InitialContext(props); |
| ctx.lookup(...); |
| ---- |
| |
| That will get you logged in and all your calls from that context should |
| execute as you. |
| |
| _$\{openejb.base}/conf/login.config_ is a standard JAAS config file. |
| Here, you can configure any number of security realms to authenticate |
| against. To specify which of the realms you want to authenticate |
| against, you can set the _openejb.authentication.realmName_ property to |
| any of the configured realm names in _login.config_. If you don't |
| speficy a realm name, the default (currently _PropertiesLogin_) is used. |
| For examples and more information on JAAS configuration, see the |
| http://java.sun.com/javase/6/docs/technotes/guides/security/jaas/JAASRefGuide.html[JAAS |
| Reference Guide] . |
| |
| == PropertiesLoginModule |
| |
| Supported options: |
| |
| Option |
| |
| Description |
| |
| Required |
| |
| UsersFile |
| |
| name of the properties file that contains the users and their passwords |
| |
| _yes_ |
| |
| GroupsFile |
| |
| name of the properties file that contains the groups and their member |
| lists |
| |
| _yes_ |
| |
| _UsersFile_ and _GroupsFile_ are read in on every login, so +you can |
| update them+ on a running system and those users will "show up" |
| immediately +without the need for a restart+ of any kind. |
| |
| == SQLLoginModule |
| |
| You can either use a data source or configure the JDBC URL through which |
| the user/group lookups will be made. |
| |
| If you use a _DataSource_, you must specify its JNDI name with the |
| _dataSourceName_ option. |
| |
| If you use JDBC directly, you have to specify at least the JDBC URL of |
| the database. The driver should be autodetected (provided the |
| appropriate jar is on your classpath), but if that fails for some |
| reason, you can force a specific driver using the _jdbcDriver_ option. |
| For more information on JDBC URLs, see the |
| http://java.sun.com/javase/6/docs/technotes/guides/jdbc/[JDBC Guide] |
| |
| The _userSelect_ query must return a two-column list of user names |
| (column 1) and passwords (column 2). This query should normally return a |
| single row, which can be achieved by the use of a query parameter |
| placeholder "?". Any such placeholders in both queries will be filled in |
| with the username that the client is trying to log in with. The |
| _groupSelect_ query must return a two-column list of user names and |
| their groups (or "roles" in the EJB world). |
| |
| Supported options: |
| |
| Option |
| |
| Description |
| |
| Required |
| |
| dataSourceName |
| |
| the name of a data source |
| |
| _yes_ (alternative 1) |
| |
| jdbcURL |
| |
| a standard JDBC URL |
| |
| _yes_ (alternative 2) |
| |
| jdbcDriver |
| |
| the fully qualified class name of the database driver |
| |
| no |
| |
| jdbcUser |
| |
| the user name for accessing the database |
| |
| no |
| |
| jdbcPassword |
| |
| the password for accessing the database |
| |
| no |
| |
| userSelect |
| |
| the SQL query that returns a list of users and their passwords |
| |
| _yes_ |
| |
| groupSelect |
| |
| the SQL query that returns a list of users and groups (roles) |
| |
| _yes_ |
| |
| digest |
| |
| the name of the digest algorithm (e.g. "MD5" or "SHA") for digest |
| authentication |
| |
| no |
| |
| encoding |
| |
| the digest encoding, can be "hex" or "base64" |
| |
| no |
| |
| = PLUG POINTS |
| |
| There are four-five different plug points where you could customize the |
| functionality. From largest to smallest: - _The SecurityService |
| interface_: As before all security work (authentication and |
| authorization) is behind this interface, only the methods on it have |
| been updated. If you want to do something really "out there" or need |
| total control, this is where you go. Plugging in your own |
| SecurityService should really be a last resort. We still have our "do |
| nothing" SecurityService implementation just as before, but it is no |
| longer the default. +You can add a new SecurityService impl by creating |
| a service-jar.xml and packing it in your jar+. You can configure OpenEJB |
| to use a different SecurityService via the openejb.xml. |
| |
| * _JaccProvider super class_: If you want to plug in your own JACC |
| implementation to perform custom authorization (maybe do some fancy |
| auditing), this is one way to do it without really having to understand |
| JACC too much. We will plug your provider in to all the places required |
| by JACC if you simply +set the system property+ |
| "_org.apache.openejb.core.security.JaccProvider_" with the name of your |
| JaccProvider impl. |
| * _Regular JACC_. The JaccProvider is simply a wrapper around the many |
| things you have to do to create and plugin a JACC provider, but you can |
| still plugin a JACC provider in the standard ways. Read the JACC spec |
| for that info. |
| * _JAAS LoginModule_. You can setup a different JAAS LoginModule to do |
| all your authentication by simply editing the conf/login.config file |
| which is a plain JAAS config file. At the moment we only support |
| username/password based login modules. At some point it would be nice to |
| support any kind of input for a JAAS LoginModule, but username/password |
| at least covers the majority. It actually _is_ possible to support any |
| LoginModule, but you would have to supply your clients with your own way |
| to authenticate to it and write a strategy for telling the OpenEJB |
| client what data to send to the server with each invocation request. See |
| the |
| http://java.sun.com/javase/6/docs/technotes/guides/security/jaas/JAASLMDevGuide.html[JAAS |
| LoginModule Developer's Guide] for more information. |
| * _Client IdentityResolver_. This is the just mentioned interface you |
| would have to implement to supply the OpenEJB client with alternate data |
| to send to the server with each invocation request. If you're plugging |
| in a new version of this it is likely that you may also want to plugin |
| in your own SecurityService implementation. Reason being, the object |
| returned from IdentiyResolve.getIdentity() is sent across the wire and |
| straight in to the SecurityService.associate(Object) method. |