Fedora 2.1 represents the first release of Fedora that includes support for authentication, SSL, and authorization using XACML policies. This document provides an overview of the security configurations that ship with Fedora 2.1 and describes how to setup and configure Fedora to run in each of the four base security modes.
Fedora 2.0 provided a very minimal level of security that consisted of the following:
- API-M restricted by IP address to the hostname of "localhost"
- API-A unrestricted
- Single super user with username of fedoraAdmin; password configurable in fedora.fcfg
- no SSL support
In Fedora 2.0, these security measures were handled through the fedora.fcfg file and special use of the single super user name(fedoraAdmin) in the codebase. In Fedora 2.1, these security measures are now handled through a set of XACML policies and with authentication information provided through Tomcat or external authentication sources.
There are four base security configurations provided with the Fedora 2.1 server distribution: (1) "ssl-authenticate-apim" configuration, (2) "ssl-authenticate-all" configuration, (3) "no-ssl-authenticate-apim" configuration, and (4) "no-ssl-authenticate-all" configuration. Unlike Fedora 2.0, there is no longer a "default" configuration. Before starting the Fedora server, you must run a server setup utility to select a base security configuration that will initialize the servers security configuration. After setup, you can customize that base configuration as needed. Section 2.0 describes the server setup process and the nature of the different base security configurations.
To select your base security configuration, run the "fedora-setup" command-line utility. This utility requires a single argument which is the name of the base security configuration you wish to use.
Under Windows:
Under Unix:
The valid values for configuration-name include:
- ssl-authenticate-apim
- ssl-authenticate-all
- no-ssl-authenticate-apim
- no-ssl-authenticate-all
The fedora-setup utility initializes one of the four base security configurations by copying a set of configuration files into the distribution tree. The contents of these configuration files will vary depending on the base security configuration selected. The resultant functionalities of the four possible base security configurations are described in more detail below. You can rerun the Fedora setup utility at any time to change your repository configuration. Just stop the server, run fedora-setup, and restart the server. The setup utility automatically puts an appropriate version of the three necessary Fedora configuration files into play:
fedora.fcfg - Fedora server configuration file
web.xml - Fedora Tomcat web application configuration file; controls whether basic authentication and SSL are enabled for API-M and API-A
beSecurity.xml - Fedora backend services configuration file; controls security for services calling back to Fedora (see beSecurity Configuration document for details)
The "ssl-authenticate-apim" configuration is designed for repositories that desire a secure management interface for administering and maintaining a repository, but wish to keep access to the repository content completely open.
The "ssl-authenticate-all" configuration is designed for repositories that desire full security for both management and access and also want to add additional security regarding how backend services are allowed to communicate with the Fedora server. Note that as authentication is enabled for API-A, the hostname used for the "fedoraServerHost" parameter in fedora.fcfg must be a resolvable, fully qualified domain name. You cannot use just "localhost" or "127.0.0.1" since remote backend services use this as the hostname to communicate with the fedora server.
The "no-ssl-authenticate-apim" configuration is designed for repositories that desire to simulate the security that was available in Fedora 2.0. Note that this configuration does not use SSL on API-M so authentication passwords are in clear text and API-A is completely unrestricted. This configuration is NOT recommended for any repositories requiring a secure environment. Note that because there is no basic authentication for API-A, you also cannot write policies for API-A that use any user attribute information.
The "no-ssl-authenticate-all" configuration is designed for repositories that want the features of basic authentication for both API-M and API-A, but are not ready to tackle some of the additional issues imposed by SSL with their client-side or middleware applications. Note that since there is no SSL support for either API-M or API-A any authentication passwords are in clear text. This configuration is NOT recommended for any repositories requiring a secure environment. Since API-A and API-M both support basic authentication, you can write policies for both API-M and API-A that use user-based attributes. This configuration can be a good choice if you want to experiment with policy writing for API-M and API-A, but are not ready to tackle SSL and security is not a concern. Note that as authentication is enabled for API-A, the hostname used for the "fedoraServerHost" parameter in fedora.fcfg must be a resolvable, fully qualified domain name. You cannot use just "localhost" or "127.0.0.1" since remote backend services use this as the hostname to communicate with the fedora server.
After selecting a base security configuration and running "fedora-setup", you can then begin customizing your configuration. Care must be exercised when performing customizations since there are some dependencies in the three configuration files: fedora.fcfg, beSecurity.xml, and web.xml that must be preserved.
fedora.fcfg - The Fedora server configuration file is found in the Fedora configuration directory ($FEDORA_HOME\server\config). The fedora.fcfg configuration file can be customized as needed as it was in Fedora 2.0 with one exception. The value of the parameter named "doMediateDatastreams" that is in the API-A module section is dependent on the authentication setting for API-A. If authentication is disabled for API-A, then the setting for "doMediateDatastreams" should be set to "false". If authentication is enabled for API-A, then "doMediateDatastreams" should be set to "true". Running "fedora-setup" will ensure that this parameter is set appropriately for the particular security configuration you have chosen. It is recommended that you do NOT directly edit the "doMediateDatastreams" parameter. Instead, let "fedora-setup" control this setting. Also, remember that if you ran "fedora-setup" with a setting that enables authentication for API-A (i.e., ssl-authenticate-all or no-ssl-authenticate-all), the value of "fedoraServerHost" must be a resolvable, fully-qualified domain name. You cannot use just "localhost" since remote backend services use this hostname to communicate with the fedora server.
web.xml - The web.xml configuration file is found in the Fedora Tomcat web application directory under the Fedora Tomcat path ($FEDORA_HOME\server\jakarta-tomcat-5.0.28\webapps\fedora\WEB-INF). This file controls the settings for authentication and SSL forwarding for API-M and API-A. It is strongly recommended that you do not customize this file unless you have very special needs that cannot be met by one of the four base configuration files. If you decide you have to customize this file, here are some helpful pointers to keep in mind:
Remember that settings web.xml for authentication and SSL can interact with settings in fedora.fcfg, beSecurity, and in XACML policies so exercise care when making customized changes to web.xml:
- fedora.fcfg - if web.xml enables authentication for API-A, you must ensure that the doMediateDatastreams parm is set to true in fedora.fcfg
- beSecurity - if web.xml enables authentication and SSL forwarding for API-A, these settings must be reflected in the backend service profiles in beSecurity.xml
- XACML policies - if web.xml does NOT enable authentication for particular API, then XACML policy enforcement will not be able to match "Subject" attributes within a policy that targets that API.
beSecurity.xml - Customization of this file is only necessary for repositories that are using custom disseminators that point to external services. The Fedora backend security configuration file is found in the Fedora configuration directory ($FEDORA_HOME\server\config). If you want to set up a totally secure repository, you must configure things up so that external services can securely call back to the Fedora repository. Customization of the beSecurity.xml configuration file is described in detail in the document entitled beSecurity Configuration. The main issue to remember when customizing beSecurity is that it controls how backend services communicate with the Fedora server and how the Fedora server communicates with backend services. Hence, you have to be aware of what setting you are using for API-A in regards to authentication and SSL support. For example, if you have authentication and SSL support turned off for API-A, it would not make sense to have a beSecurity setting that tries to enable authentication or SSL when a backend service is attempting to connect to the Fedora server. Note also that beSecurity is only needed if you are using custom disseminators and care about how backend services communicate with the Fedora server. If this is not a concern, you can use the minimal beSecurity configuration file that is part of the "ssl-authenticate-apim" or "no-ssl-authenticate-apim" configurations.
tomcat-users_fedoraTemplate.xml - This a Fedora-specific template file is found in the Fedora Tomcat directory ($FEDORA_HOME/inc/server/jakarta-tomcat-5.0.28/conf). If you are using the default Tomcat authentication (out-of-the-box with Fedora 2.0), you will probably need to add new users. This is done by making additions to the Fedora-specific template (tomcat-users_fedoraTemplate.xml) which is automatically converted into a runtime Tomcat users configuration file (i.e., tomcat-users.xml). New entries will be necessary here if you are using the tomcat-users file for authentication and you add additional authenticated users and also if you customize beSecurity.xml with new usernames, passwords, or roles. See the section on Authentication for additional details in customizing the tomcat-users file.
The Fedora server is built on top of Apache's Tomcat and authentication information is channeled through the normal Tomcat mechanisms. Fedora currently provides two authentication sources: (1) Simple user/password file, and (2) LDAP. Other sources can be configured by the repository administrator. These two authentication sources are described within the context of three different authentication configuration options for Fedora (i.e., options A, B anc C), described below. Note that option B is the default configuration with Fedora out-of-the-box. First, we describe the two authentication sources available in Fedora 2.1:
tomcat-users.xml - simple user/password file
This file is part of the Tomcat configuration files and is auto-generated from the tomcat-user_fedoraTemplate.xml file. It contains username and password information about "authenticated" users. Roles can also be assigned to user entries. These can then be used as attributes in related XACML policies, or in customized web.xml files. Refer to the next section entitled "Option A - Single Authentication Source" for details concerning the contents of the Tomcat users file. This file is a single source of simple authentication when used in option A. It is one of potentially many when used in options B or C.
LDAP
The configuration of Tomcat to use LDAP for authentication follows the standard rules outlined by the Apache Tomcat group. Refer to http://jakarta.apache.org/tomcat/tomcat-5.0-doc/realm-howto.html#JNDIRealm for details on how to configure Tomcat to use LDAP for authentication. Fedora's use of LDAP for authentication is as one of several authentication sources multiplexed as JAAS Login Modules. The Apache description of JNDI Realm parameters is adapted to the options of the jaas.config file, as described following under "Option B - Configuring Multiple Login Modules (Multiplexing via Tomcat's JAAS)" and "Option C - Configuring Multiple Login Modules (Multiplexing via Fedora's JAAS)". LDAP is one of potentially many authentication sources when used in options B or C.
Fedora software is "aware" of any user that is authenticated through Tomcat. Authentication methods other than the two described here are possible through Tomcat, but require configuring other Realm or Login Modules obtained separately from the Apache Project or third parties, or writing your own custom Realms or LoginModules. Additional user attributes can be merged with those which Tomcat provides through the mechanisms supplied here, by configuring a site-written servlet filter, which calls the Fedora API. For more details on the Fedora security architecture, refer to the document entitled Fedora Security Architecture - Authentication and User Attributes.
This Realm provides basic functionality which is available as well in options B and C (described below). For this Realm, the source of user identity information is the file named "tomcat-users.xml" which is automatically generated by the Fedora server at startup based on the contents of the template file named "tomcat-users_fedoraTemplate.xml". It is recommended that you make changes to this template file instead of the generated file. Each time the server is started a new tomcat-users.xml will be generated. The template file is located:
In source distribution:
Unix: $FEDORA_HOME/inc/server/jakarta-tomcat-5.0.8/conf/tomcat-users_fedoraTemplate.xmlWindows: %FEDORA_HOME%\inc\server\jakarta-5.0.8\conf\tomcat-users_fedoraTemplate.xml
In binary distribution:
Unix: $FEDORA_HOME/server/jakarta-tomcat-5.0.8/conf/tomcat-users_fedoraTemplate.xmlWindows: %FEDORA_HOME%\server\jakarta-tomcat-5.0.8\conf\tomcat-users_fedoraTemplate.xml
By default, the template contains the following users, passwords, and roles:
<tomcat-users>
<user name="#1" password="#2" roles="fedoraRole=administrator"/>
<user name="fedoraIntCallUser" password="changeme" roles="fedoraRole=fedoraInternalCall-1"/>
<user name="surrogate64" password="surrogate64" roles="webfrontend"/>
<user name="testuser1" password="testuser1" roles="fedoraRole=professor"/>
<user name="testuser2" password="testuser2" roles="fedoraRole=researcher"/>
<user name="testuser3" password="testuser3" roles="fedoraRole=student"/>
<user name="testuser4" password="testuser4" roles="fedoraRole=visitor"/>
<user name="guest" password="" roles=""/>
</tomcat-users>
The placeholders indicated by #1 and #2 will be substituted with the values specified for adminUsername(default is fedoraAdmin) and adminPassword(default is fedoraAdmin) specified in the fedora.fcfg file at server startup time. To change these values, make the changes in fedora.fcfg and leave the #1, and #2 markers unchanged in "tomcat-users_fedoraTemplate.xml". The role of "fedoraRole=administrator" is a special role that grants super user privileges for the Fedora server and should not be edited.
The username of "fedoraIntCallUser" is also a special Fedora system user. The role of "fedoraRole=fedoraInternalCall-1" grants special system privileges to this user. This username is used as the authenticating user when the fedora server needs to make calls to itself. The values for username and password may be edited, but you should leave the role unchanged. If you do change the username or password, you must also update these values in the beSecurity.xml file.
The third entry provides a username that can be used when a webfrontend is authenticated outside of Fedora and you want that authenticated webfrontend user to then be able to authenticate with fedora. You can edit this entry as needed, but the value used for role must match the value specified in the corresponding surrogate user policy. An example of a repository wide policy that uses a surrogate user can be found in the set of example policies under the name "permit-webfrontend-as-surrogate.xml". This example policy uses the role of "webfrontend" which corresponds to the value in the tomcat-users_fedoraTemplate.xml file. See the next sections for additional details regarding configuring a surrogate user.
The remaining usernames in the example tomcat-users_fedoraTemplate.xml file are used by the example policies described in Fedora XACML Policy Writing Guide. If you plan to experiment with the sample policies, you will need to retain these usernames and roles in order for the policies to function properly.
In addition to username and password, you can also assign what Tomcat refers to as "roles". (These roles have a matching function against Tomcat's web.xml file, which remains unchanged.) In addition, for Fedora, you can think of these "roles" in the tomcat-users file as attributes about the user which are entered as "name=value" pairs. You can use "roles" to define groups of users and then write policies based on these attributes.
Option A is not the default. It is chosen by editing a configuration file. server.xml contains a comment, which can be uncommented to use MemoryRealm instead of the more complicated, default JAASRealm. Of course, the specification of JAASRealm must be commented out, to go along with this. The resulting content would then look like:
<Realm className="org.apache.catalina.realm.MemoryRealm" />
<!-- Realm className="org.apache.catalina.realm.JAASRealm" appName="fedora"
userClassNames="org.apache.catalina.realm.IdPasswordPrincipal"
roleClassNames="org.apache.catalina.realm.RolePrincipal" / --> In source distribution:
Unix: $FEDORA_HOME/inc/server/jakarta-tomcat-5.0.8/conf/server_fedoraTemplate.xmlWindows: %FEDORA_HOME%\inc\server\jakarta-5.0.8\conf\server_fedoraTemplate.xml
In binary distribution:
Unix: $FEDORA_HOME/server/jakarta-tomcat-5.0.8/conf/server_fedoraTemplate.xmlWindows: %FEDORA_HOME%\server\jakarta-tomcat-5.0.8\conf\server_fedoraTemplate.xml
With the multiplexor features of options B or C, you could also have access to user attributes from other sources. For example, using jaas.config you could also configure a ldap server to provide additional attributes about an authenticated user. There is an example in the jaas.config file that demonstrates how to do this with the public UVa ldap server which is used to provide additional attribute information about authenticated users. Of course, this is for demonstration only, and practically not useful for those not at UVa.
Two aspects of tomcat-users use need pointing out. First, the equal character ("=") is just another character in Tomcat's processing of role strings. The match of a role containing "=" from this or another authentication source against a role coded in web.xml is simply the comparison of one string with another. So, Fedora's introduced convention of optional "=" in roles is not harmful. If Fedora software sees such a role from Tomcat, one of form "name=value", a user attribute so-named will be created with the associated value for use with XACML policies. If a Tomcat role does not contain "=", it is taken by Fedora to be a user attribute with that name and null string value. Second, Tomcat allows multiple roles per user through this authentication source, hence the attribute name as plural "roles". These two aspects of role coding in tomcat-users is illustrated in the following snippet, which suggests a single user entry both allowed super user privileges and allowed to identify middleware software in front of the fedora server.
roles="webfrontend,fedoraRole=administrator"
If you need to combine user attributes from multiple sources, use either option B or C, or refer to the document entitled Fedora Security Architecture - Authentication for how to customize authentication for your needs.
Tomcat comes with realms other than the Memory Realm. In general, each realm supports a single source for authentication. One of these other realms, however, is different: the JAAS Realm. As a realm, it supplies Tomcat with an apparent single authentication source. But internally, it multiplexes several authentication sources. It is unique among Tomcat realms in doing this, and so has an adapter or utility quality. Fedora is configured out-of-the-box with the JAAS Realm enabled. By default, the Tomcat configuration file named "server.xml" specifies this as follows, which also applies to option C. This is mentioned chiefly for reference, in case you change that file and need later to undo your edit. You will not need to change the original file, if you opt for option B or C. (The commented line is there to be used in option A.)
<!-- Realm className="org.apache.catalina.realm.MemoryRealm" / -->
<Realm className="org.apache.catalina.realm.JAASRealm" appName="fedora"
userClassNames="org.apache.catalina.realm.IdPasswordPrincipal"
roleClassNames="org.apache.catalina.realm.RolePrincipal" /> For this Realm, configuration of the sources of user identity information is given in a file named "jaas.config". This file is located:
In source distribution:
Unix: $FEDORA_HOME/inc/server/jakarta-tomcat-5.0.8/conf/jaas.configWindows: %FEDORA_HOME%\inc\server\jakarta-5.0.8\conf\jaas.config
In binary distribution:
Unix: $FEDORA_HOME/server/jakarta-tomcat-5.0.8/conf/jaas.configWindows: %FEDORA_HOME%\server\jakarta-tomcat-5.0.8\conf\jaas.config
The jaas.config file includes one or more login module configurations. The default shipped with Fedora 2.1 provides an entry for the basic JAASMemoryLoginModule that uses the tomcat-users.xml file. The entry appears twice so that it applies to the Fedora webapp and also to other urls in the webserver which aren't more specifically identified. The examples below show only a single entry. Any editing should be done to both entry identifically. Two comments are shown for reference, in case you change that file and need later to undo your edit. You will not need to change the original file, if you opt for option B (or C), and want only to use the Memory Login Module.)
org.apache.catalina.realm.JAASMemoryLoginModule
required
debug=false
path="conf/tomcat-users.xml"
;
/** uncomment to enable end-user ldap attributes in case of surrogate
org.apache.catalina.realm.JAASNullLoginModule
required debug=false;
**/
/** uncomment to test against uva ldap; e.g., put wdn5e in tomcat-users.xml, it will match here
org.apache.catalina.realm.JAASJNDILoginModule optional debug=false
connectionURL="ldap://ldapvs.itc.virginia.edu:389"
userBase="o=University of Virginia,c=US"
userSearch="(uid={0})"
userRoleName="objectClass,uid,ou,UnixUid,eduPersonOrgDN,eduPersonOrgUnitDN,eduPersonPrimaryAffiliation,eduPersonScopedAffiliation"
userSubtree=true
userPassword="NO_AUTHENTICATION"
;
**/
As configured, all authenticated users must have an entry in the tomcat-users_fedoraTemplate.xml file. This is as explained for option A.
jaas.config also includes two additional examples that are commented out. The second in order of these added examples (third, including the Memory Login Module) includes accessing an ldap server that is not used for authentication, but instead to provide additional attributes about an authenticated user.
org.apache.catalina.realm.JAASMemoryLoginModule
required
debug=false
path="conf/tomcat-users.xml"
;
/** uncomment to enable end-user ldap attributes in case of surrogate
org.apache.catalina.realm.JAASNullLoginModule
required debug=false;
**/
org.apache.catalina.realm.JAASJNDILoginModule optional debug=false
connectionURL="ldap://ldapvs.itc.virginia.edu:389"
userBase="o=University of Virginia,c=US"
userSearch="(uid={0})"
userRoleName="objectClass,uid,ou,UnixUid,eduPersonOrgDN,eduPersonOrgUnitDN,eduPersonPrimaryAffiliation,eduPersonScopedAffiliation"
userSubtree=true
userPassword="NO_AUTHENTICATION"
;
This allows attributes provided by the ldap server to be gathered in addition to any attributes associated with this user in the tomcat-users file. For example, if there is user entry in the tomcat-users file for "wdn5e", then this authenticated username will match against the corresponding entry in the ldap server and any attributes associated with the username "wdn5e" in the ldap server will also be available for use by Fedora. Editing jaas.config to try this example, is different in kind from the edit of server_fedoraTemplate.xml described above, and in two ways: (a) there is no template or "shadow" file, just straightforwarding jaas.config; (b) unlike the either/or situation in editing server_fedoraTemplate.xml for Tomcat Realm selection, more than one JAAS source can be uncommented.
The first in order of these added examples (second, including the Memory Login Module) supports separation of authentication and authorization subjects (user identities), and is primarily in support of LDAP attributes in special usage. If a non-browser client or a web frontend (middleware) chooses, it can include a From: http header with a request, indicating that the authorization identity differs from the authentication identity. The basic-auth user must still pass authentication and -also- be authorized to represent (server as "surrogate" for) other users. In this case, the represented user is accepted as pre-authenticated: the Null Login Module accomplishes this. (Surrogate access must be turned on in the appropriate fedora-x.fcfg file for this to work.)
org.apache.catalina.realm.JAASMemoryLoginModule
required
debug=false
path="conf/tomcat-users.xml"
;
org.apache.catalina.realm.JAASNullLoginModule
required debug=false;
org.apache.catalina.realm.JAASJNDILoginModule optional debug=false
connectionURL="ldap://ldapvs.itc.virginia.edu:389"
userBase="o=University of Virginia,c=US"
userSearch="(uid={0})"
userRoleName="objectClass,uid,ou,UnixUid,eduPersonOrgDN,eduPersonOrgUnitDN,eduPersonPrimaryAffiliation,eduPersonScopedAffiliation"
userSubtree=true
userPassword="NO_AUTHENTICATION"
; This allows attributes provided by the external authentication agent to be gathered in addition to any attributes associated with this user in the tomcat-users file. For less practical and more technical information on all this, refer to the document entitled Fedora Security Architecture - Authentication.
Several needs required editing and compilation of a few Tomcat source files. This is explained further in the document entitled Fedora Security Architecture - Authentication. If the original Tomcat JAASRealm is needed, you will need to delete the equivalent Fedora file from one of the following locations:
In source distribution:
Unix: $FEDORA_HOME/src/java/org/apache/catalina/realm/JAASRealm.javaWindows: %FEDORA_HOME%\src\java\org\apache\catalina\realm\JAASRealm.java
In binary distribution:
Unix: $FEDORA_HOME/dist/server/jakarta-tomcat-5.0.28/server/classes/org/apache/catalina/realm/JAASRealm.classNote that after deleting from the source location, you would need to do an ant build. This would be a lasting delete. Or after deleting from the binary distribution, the effect would be immediate but temporary, lasting only until the next ant build. Editing of the configuration files is the same as for option B.Windows: %FEDORA_HOME%\dist\server\jakarta-tomcat-5.0.28\server\classes\org\apache\catalina\realm\JAASRealm.class
Fedora 2.0 hardcoded minimal authorization constraints, beyond those provided by specifications in Tomcat's web.xml file. Fedora 2.1 instead exposes these to customization by encoding them in the XACML standard. A complete description can be found in the documentation for the Fedora Authorization with XACML Policy Enforcement.
Fedora 2.1 ships with a set of default repository-wide XACML policies that approximate the minimal security level provided by Fedora 2.0. This set of repository-wide policies includes the following policies:
Note that the default repository policies enforce a minimal level security (e.g., API-A is totally unrestricted). If you need a more customized level of access control what is provided by the default, you will need to add additional repository-wide policies or individual object-specific policies to customize your access environment. Refer to the Fedora XACML Policy Writing Guide document for more information about how to construct policies for your repository.
Here is a brief step-by-step guide that describes what you will need to do to configure your fedora repository. It is recommended that you start with one of the base security configurations and set of default policies and become familiar with the new security features of Fedora 2.1. Then you can go back and experiment with customizing various aspects of your repository configuration and policies.
- Select a base security configuration by running "fedora-setup"
- Optionally customize fedora.fcfg for your repository
- Optionally customize beSecurity.xml for your custom disseminators *
- Optionally customize XACML policies (repository-wide and object-specific policies)
- Optionally customize tomcat-users_fedoraTemplate.xml for your repository and users
- Optionally customize server_fedoraTemplate.xml and/or jaas.config for your repository
- Start the fedora server
* If using the beSecurity Configuration Tool to customize the beSecurity.xml file, the server needs to be running prior to using the configuration tool. In this case, make all other customizations first, start the server, and then use beSecurity Configuration Tool to finish customization of beSecurity.xml. For additional information on using the beSecurity Configuration Tool see the beSecurity Configuration document.