| Back | Next | Contents | Cams Administrator's Guide |
This document guides you through a simple Cams integration assuming that you've already installed the Cams server and deployed at least one Cams web agent. You should have also downloaded and reviewed the Cams Tour and the Introduction to become familiar with Cams terminology and architecture.
Most of the activity associated with a Cams integration is centered on the XML files containing configuration parameters for each security domain you deploy. In summary, the steps you'll take are:
These instructions use the symbol CAMS_HOME to represent the directory in which you've installed Cams.
WARNING: Make sure that you follow the instructions in this document closely to ensure that your first Cams integration is successful. Once you've come through the initial learning curve and integration, it will be much easier to branch out, make changes specific to your environment, and try more advanced options!
The file security-domain-registry.xml defines the security domains available within a Cams server. By default, the security domain registry is in located in CAMS_HOME/conf/domains. You can change the location by editing the CAMS_HOME/conf/cams.conf value:
security.domain.registry.factory.params=${cams.home}/conf/domains/security-domain-registry.xml
These instructions assume that you leave the Cams security domains in their default location. Open the file CAMS_HOME/conf/domains/security-domain-registry.xml in a text editor. The default Cams server includes two security domains:
In the default Cams server security-domain-registry.xml file contents shown in example 1, you'll see that system is enabled and mydomain is disabled.
<!-- User-defined variables that apply across all security domains --> <!-- The mydomain security domain (template) -->
<security-domain enabled="false">
<name>mydomain</name>
<home>${cams.home}/conf/domains/mydomain</home>
</security-domain>
|
Example 1 - The default Cams server security domain registry configuration
To disable a security domain, set the enabled flag to false. To completely remove a security domain, delete the references in security-domain-registry.xml and remove the corresponding directory and files. To add a new security domain, create a reference to it in security-domain-registry.xml similar to those shown above but using the new name. Then, create a new subdirectory with the corresponding security domain name and copy the template XML files from the default mydomain template to the new security domain.
The system security domain should never be deleted or disabled. By default, it protects all HTTP/HTTPS resources, is used for Cams web agent authentication, and is always the initial point of permission delegation to other security domains.
Security domains should be considered as a point of administration. You can create as many security domains as required for your administrative purposes. They can also be nested. There's no requirement to create a user security domain, but you might consider creating them when:
NOTE: Cams web single sign-on is currently supported for resources managed by a single security domain. If you delegate resources to more than one security domain, users must authenticate with each security domain (even if the security domains use the same user directory). A future release of Cams will support single sign-on across Cams security domains.
Example 1 also shows use of the value ${cams.home}, which is a Cams substitution value. You can create your own in any security domain configuration file using the syntax shown. Substitution values are hierarchically inherited from the security domain registry by the security domain configuration files. Additionally, the following substitution values are provided by the Cams server and are always available in any security domain configuration file:
Each security domain configuration requires three files:
NOTE: The cams-users.xml user directory is optionally included in each security domain. This user directory is loaded into system memory and only recommended for development and testing, and for small production user communities. Most production security domains will configure an LDAP or SQL relational database as the user directory.
The access-control-policy.xml file configures a Cams access control policy, which consists of a default bias, rules, and permissions. Rules define how an access control policy will protect resources. Most of the rules you'll use are supplied with Cams (they're called intrinsic rules). You can also create custom rules and/or combine existing rules to create new ones. A permission is the binding of a rule to a specific resource pattern (such as a URL for web security). The default bias specifies if access to resources without permissions will be granted or denied.
Open the system security domain's access-control-policy.xml file in a text editor. At the top of the file you see the declaration of an access control policy and the default bias setting:
<access-control-policy defaultBias="denied">
It is recommended that you set the default bias to denied and grant access as required to specific resources. This helps prevent situations where access is accidentally granted due to a misconfiguration or omission in the access control policy.
Example 2 shows the system security domain's default HTTP permissions. The permission that applies to a given access control check is determined by:
If no permission contains a matching action and resource pattern for a given access control check, then the default bias determines whether access to the resource is granted or denied.
Cams URL-based resource patterns have the following general form:
schemePattern :// hostPattern : portPattern / uriPattern
Hard values can be specified as well as wildcards to match in any of the four components (scheme, host, port or URI). For example, the following are all valid permission resource patterns:
See the Configuring Cams Access Control Policy for more information on resource pattern matching.
In Example 2, the first two permissions unconditionally grant access to the cams and cgi-bin/cams- resources. This ensures that Cams login/logout URIs and the login, denied, and error pages can always be accessed. The next permission unconditionally grants access to all HTTP/HTTPS resources. A permission always has either an <acr-ref> or <owner> tag. The <acr-ref> references an access control rule that will be evaluated when the permission is applied because it best matches a resource request. In this permission, the intrinsic Cams granted rule will always grants access. The next permission is not active but is included to show use of the <owner> tag, which delegates access control to the mydomain security domain. The last permission, used for testing Cam web agents, is also not active by default (see the Web Agent Guide for more information).
NOTE: You activate the last two permissions by uncommenting them (move the trailing "-->" above the XML tag elements). You must also enable the mydomain security domain in the security domain registry before you use a permission that delegates to it.
<!-- HTTP and HTTPS resource permissions --> <!-- Example: Delegate all HTTP/HTTPS permissions for "/myresource/*" to
another security domain. Uncomment to enable.
<permission desc="Delegate all HTTP/HTTPS requests" actions="">
<resource-pattern id="*://*:*/myresource/*"/>
<owner id="mydomain"/>
</permission>
-->
<!-- Example: Apply an access control rule to the Cams web agent test
page that only grantis access to authenticated users with the
administrator role. Uncomment to enable.
<Permission desc="allow administrators to access web agent test page" actions="">
<resource-pattern id="*://*:*/cams/cams-webagent-test*"/>
<acr-ref id="cams administrator rule"/>
</permission>
-->
</permission-collection>
|
Example 2 - Permissions from the default system security domain
Before exiting access-control-policy.xml, look at the <permission-collection type="cams">. This permission collection defines the permissions for Cams web agent connections. You'll see the access control rule reference:
<acr-ref id="cams agent rule"/>
Example 3 shows the access control rules section of the file, marked by the <acr-lib> tags. You see that the cams agent rule requires that authenticated Cams web agents have the cams-agent role. Now, open the cams-users.xml user directory in a text editor to see that the cams-web-agent user has the cams-agent role. Without it, an authenticated Cams web agent would be denied access to the Cams server. If you decide to configure the system security domain to use and LDAP or SQL database for the user repository, you'll need to create an account for cams-web-agent.
The cams administrator rule grants access to resources that require the authenticated user to have the administrator role. By uncommenting the last default permission, this rule will protect the Cams web agent test page.
<!-- Library of access control rules --> <!-- Cams administrators must have the "administrator" role --> <auth-acr id="cams administrator rule"> <role-constraint> <role-name>administrator</role-name> <role-class>com.cafesoft.cams.auth.CSRolePrincipal</role-class> </role-constraint> </auth-acr> <!-- Cams agents must have the "cams-agent" role --> <auth-acr id="cams agent rule"> <role-constraint> <role-name>cams-agent</role-name> <role-class>com.cafesoft.cams.auth.CSRolePrincipal</role-class> </role-constraint> </auth-acr> </acr-lib> |
Example 3 - Rules from the default system security domain
These instructions assume that you are using the XML-based Cams user directory with the system security domain, which is already configured by default. Hence, you only need to ensure that the login page value is correctly defined in login-config.xml files at this time (security-domain.xml will not require modification).
Open CAMS_HOME/conf/domains/system/login-conf.xml in a text editor. Scroll to the bottom of the file where you will see the XML tag elements shown in example 4.
<!-- The Cams server sends the camsLoginUrl value to a Cams web agent when an 2) POSTs the credentials to the login URL configured by the Cams web agent
("/cams/login" by default).
The value of camsLoginUrl can be an absolute or relative URL. Any
server with a Cams web agent can be used provided the server is in the
same Internet domain as the web server that made the original request.
NOTE: You must change camsLoginUrl to reference a login page at your site.
For example, IIS sites might use "/cams/login.asp" and Apache sites might
use "/CGI-bin/cams-login.sh". -->
<login-parameters>
<login-parameter name="camsLoginUrl" value="/cams/login.jsp"/>
</login-parameters>
|
Example 4 - Defining the login URL in login-config.xml
The comment in example 4 describes the importance of ensuring this value is correct for your site. As stated in the note, it is essential that you reference the login page at your site. For example, IIS sites might use /cams/login.asp and Apache sites might use /cgi-bin/cams-login.sh.
WARNING: Do not forget to configure this value, it is easily overlooked but essential to correct operation of Cams!
This step will guide you through the creation of a custom rule and permission in the system security domain.
Open CAMS_HOME/conf/domains/system/access-control-policy.xml in a text editor. By default, access is granted to all HTTP/HTTPS requests with any HTTP actions (e.g., GET, POST, HEAD, PUT, DELETE, TRACE). Specifying HTTP actions enables access control to be specific to a resource and the action. So, you could have multiple permissions that apply to the same HTTP URL, but differ according to the requested action. For example, you could unconditionally grant access to a URL for the GET action, but require an authenticated user with the "webmaster" role for DELETE and PUT actions.
The access control rule reference to the granted rule id, <acr-ref id="granted"/>, is an intrinsic Cams rule that grants access to everyone for the specified resource. In this case, it is applied to the root directory for all HTTP and HTTPS resource requests. To tighten security for a system HTTP resource request, first, define an access control rule that requires a user to have the myrole role. Between the <acr-lib> and </acr-lib> tags, insert:
<!-- Requires authenticated users to have the "myrole" role --> <auth-acr id="require myrole"> <role-constraint> <role-name>myrole</role-name> </role-constraint> </auth-acr>
Now, edit the HTTP resource permission by changing the tag <acr-ref id="granted"/> to:
<acr-ref id="require myrole"/>
The permission should now look like:
<!-- Grant GET and POST permission to all HTTP resources -->
<permission desc="HTTP Permissions" actions="GET,POST">
<resource-pattern id="*://*:*/*"/>
<acr-ref id="require myrole"/>
</permission>
Alternatively, you might leave the default permissions intact and add a new permission to protect only a specific directory. For example, to secure a directory (and all of its contents) on your web server named mysecuredir, add the following permission:
<!-- Grant GET and POST permission to all HTTP resources -->
<permission desc="HTTP Permissions" actions="GET,POST">
<resource-pattern id="*://*:*/mysecuredir/*"/>
<acr-ref id="require myrole"/>
</permission>
Save and exit the file. Next, you need to add a user with the myrole role to the cams-user.xml file in the system security domain. Using a text editor, add the following line to CAMS_HOME/conf/domains/mydomain/cams-user.xml:
<user name="myuser" password="myuser" roles="myrole"/>
Save and exit the file.
NOTE: If you want to use an LDAP or SQL user directory instead of cams-users.xml, you'll need to edit the login-config.xml file. To learn more, read the Login Configuration document.
Cams is now configured to require users to authenticate with the myrole role to access the the HTTP/HTTPS resources protected in the system security domain by myrule.
Follow the instructions in the Web Agent Guide to install and configure your web agent of choice. Make sure that you follow the configuration instructions to ensure that the values in cams-webagent.conf are correct for your Cams server installation. Specifically, make sure that the following values are correctly defined in the Cams web agent cams-webagent.conf file:
This document assumes that you have placed at least one file, named index.html, at the root level of the protected web server's document tree. Furthermore, the document assumes that you have configured the Cams login, error, and denied pages or scripts. See the agent-specific installation and configuration instructions for these pages/scripts.
You're now ready to test the configuration by starting the Cams server.
NOTE: If you have installed the Cams server as a Windows service, it is highly recommended that you use the console command shown below during development so output is displayed immediately.
Linux/UNIX:
$CAMS_HOME/bin/runcams.sh
Windows:
%CAMS_HOME%\bin\runcams.bat
This document assumes you are using the Tomcat web server. To start Tomcat with the Cams web agent:
Linux/UNIX:
$CATALINA_HOME/bin/startup.sh
Windows:
%CATALINA_HOME%\bin\startup.bat
NOTE: The order in which you start Cams and servers with Cams web agents are not order dependent, you can start or restart the Cams server and Cams web agents in any order.
To test the integration, try to access:
http://localhost:8080/index.html
or
http//localhost:8080/mysecuredir/index.html
You should see be prompted with the Cams login page where you can login as:
username: myuser
password: myuser
After clicking submit, you should see index.html in your browser.
Congratulations, you have now completed your first Cams security domain configuration. You can find more information in the Security Domain Registry Configuration, Security Domain Configuration, Access Control Services, and Login Configuration and their associated tag references in the appendix.
© Copyright 1996-2003 Cafésoft LLC. All rights reserved.