DACS.QUICK(7) | DACS Miscellaneous Information | DACS.QUICK(7) |
NAME¶
dacs.quick - DACS Quick Start TutorialDESCRIPTION¶
The purpose of DACS Quick Start is to explain, step-by-step, how to configure a very basic DACS-enabled web site from scratch so that you can try DACS with minimal effort. We hope that by performing the entire example configuration yourself, you will gain a better understanding of how DACS works and how to go about configuring it to meet your needs. By following along with some simple examples, you will create a completely stand-alone, single jurisdiction DACS federation on one of your hosts. You will become familiar with some of the DACS utilities and web services. When you are done, you can simply delete a few directories to uninstall everything. The tutorial should take about 30 minutes to complete the first time. This tutorial will be useful for those who want Those upgrading from pre-1.4 releases of DACS may benefit from Quick Start by noticing important changes in DACS 1.4, thereby easing the transition. After successfully completing Quick Start, you should understand DACS well enough that you can proceed to experiment with configuration and features, and perhaps use the example configuration as a starting point to meet your requirements. We do not provide much background or technical information about DACS here, or tell you how to set up a fully functional, production-quality DACS system. You may find it worthwhile to review the FAQ[1] before beginning, but if you're itching to get started right away you may do so. For technical details, please refer to the manual pages[2] and other documentation. We assume that you've got some hands-on experience configuring and using Apache, although Quick Start tells you exactly what to do. To avoid frustrating problems, we recommend that you resist the temptation to stray from the instructions except as indicated. Experienced Apache administrators may recognize the opportunity for some shortcuts, but since we're trying to keep things simple for a wide audience, we'd rather not get sidetracked by mentioning them. Likewise, experienced DACS administrators may recognize alternative ways - maybe even better ways - of doing things. But our goal is to get beginners started quickly, so we'll progress in small steps, explaining what is being done, and providing assurance that everything is correct so far. That way if you run into a problem, you should be able to isolate and fix it more easily. We'll assume that you've already obtained the latest version of DACS, unpacked it, and at least skimmed through dacs.readme(7)[3] and dacs.install(7)[4]. The document you are reading should have come from that version of DACS. 1.You will be installing and configuring a
basic Apache server ( httpd) as part of this tutorial. You may
perform this installation on your desktop Unix host or on a host other than
your desktop, such as a remote server. You will find the former somewhat
easier and safer to do, so it is recommended when possible. If doing the
installation on a particular host may expose the tutorial's web server to
requests from the Internet, be sure to carefully consider the security
implications and take appropriate precautions before proceeding. Nothing in
the tutorial ought to make the host running the web server more vulnerable,
but if you experiment with DACS on your own there could be unintended
consequences. It is probably a good idea to stop Apache when you are no
longer using it.
2.You will find it much easier to follow
along if you use the HTML version of this document because it includes links
that save you from having to type examples. Obviously these links will only
work if you have configured the tutorial's environment. Some links from this
document to other documentation point at the tutorial environment, so they
will not function if that environment is not available. Also, your web browser
must be capable of handling cookies and have that feature enabled.
3.Make sure that this document came with the
DACS release that you are working with.
4.The Quick Start procedure has been
performed successfully on FreeBSD and CentOS Linux, but we expect it to work
on most Unix-like systems. If you run into a problem, you should not proceed
until you have fixed it.
5.Depending on your environment, some tasks
may need to be done as root (in particular, editing /etc/hosts, setting file
ownership and permissions, and each "make install"). No program or
web service used in the examples needs to run as root. Except for one or two
optional DACS web services, none of the DACS web services needs
to run set-uid or set-gid.
6.Ordinarily, all DACS-related network
communication must be done over SSL. Setting up SSL appropriately is
primarily an Apache configuration task[5], requiring a server
certificate; anyone who has done this before will likely understand what needs
to be done after completing Quick Start. To help keep this document simpler
and because our goal is not to create a production-quality DACS
installation, we will neither use SSL in the examples nor mention SSL
again.
7.It's a challenge to write instructions that
will work everywhere, everytime, for everyone, so please accept our apologies
for any deficiencies in this document. We are keen to improve it, so if you
encounter any problems while trying this tutorial, or if you have any
questions, please contact us[6]. Our goal is to make it as easy as
possible to get started with DACS.
1.Step 1: Install required third-party
packages
2.Step 2: Install and configure Apache
3.Step 3: Build and install DACS
4.Step 4: DACS-enable Apache
5.Step 5: Do basic DACS configuration
6.Step 6: Do basic Apache configuration for
DACS
7.Step 7: Test basic DACS services
8.Step 8: Try DACS authentication
9.Step 9: DACS-wrapping a web service
10.Step 10: What's next?
11.Step 11: Clean up
Step 1: Install required third-party packages¶
Obtain the versions of Apache[7], OpenSSL[8], and Expat[9] that are specified in dacs.install(7)[4]. The instructions here assume that Apache 2.0 is being used; you can use 2.2 if you are able to adapt the instructions on your own. For the purposes of this exercise, those are the only third-party packages that you need, other than gmake, GCC, and the usual software development tools. Install OpenSSL and Expat now; we will deal with Apache in the next step.Step 2: Install and configure Apache¶
Because you probably do not want to use a production web server for this exercise, so that we're on the same page to begin with, and to make it easier for you to clean up later, we'll build and install a fresh Apache server. It will be best if you start from scratch by unpacking an Apache distribution into a new directory, building and installing it, and then verifying that the default Apache configuration works. We will install this Apache in /usr/local/apache-dacs so that it does not interfere with anything already on your system - you may change this path, but remember to make appropriate changes to the instructions that follow. 1.From the root of the Apache
distribution, build Apache. Review the Apache INSTALL file. You
will run commands like the following (again, adjust the paths for your
environment):
Do not configure any Apache modules or customizations. We want to create
a vanilla web server. The path /usr/local/apache-dacs is being used to avoid
any existing Apache installation; when you are finished with the
tutorial, you will remove this directory.
% ./configure --enable-ssl --with-ssl=/usr/local/ssl \ --prefix=/usr/local/apache-dacs % make % make install
2.We will soon configure a virtual host for a
(fake) domain name that we have reserved for this purpose, but first we must
make dodgers.dacstest.dss.ca an alias for the host that will run httpd.
Choose one of the following two options:
Notes
To verify the change, use ping:
(You may need to run it as /sbin/ping or something similar on your
system.)
1.If you are installing Apache on the
same machine from which you are running your web browser, edit /etc/hosts as
follows:
127.0.0.1 localhost dodgers.dacstest.dss.ca
2.If you will be running your browser on a
host different from where Apache is running, you will need to add an
alias in /etc/hosts for that host's IP address on both machines. The
entry will have the format:
For example, on my system I used:
hostip hostname dodgers.dacstest.dss.ca
10.0.0.5 bsd5.dss.ca bsd5 dodgers.dacstest.dss.ca
1.If your desktop is a Windows platform
rather than Unix-based, you will need to edit
C:\Windows\system32\drivers\etc\hosts or C:\WINNT\system32\drivers\etc\hosts
(or similar) instead of /etc/hosts.
2.You can use the domain
dodgers.dacstest.dss.ca and the others in this document no matter where your
host is located. These domain names will not be visible outside of the hosts
on which you define them by hand.
3.After you have completed this exercise,
please remember to delete the aliases.
% ping dodgers.dacstest.dss.ca
3.We need to make a few changes to
Apache's default configuration, in case you are already running a web
server on this machine and as a first step towards some customization that we
will need shortly. We will add a virtual host definition and do some initial
set up for DACS. Edit /usr/local/apache-dacs/conf/httpd.conf, advance
to the bottom of the file, and insert the text that appears below:
As discussed earlier, if necessary, replace each occurrence of 127.0.0.1 with
the hostip. Or, use a configuration like:
This VirtualHost[10] section is going to correspond to the DACS
jurisdiction that we will define shortly. The purpose of the
Directory[11] and Alias[12] directives is to make various web
resources available without having to copy them under your
DocumentRoot[13].
Note
# Permit access to the DACS documents <Directory /usr/local/dacs/www/*> Options Indexes FollowSymLinks Order allow,deny Allow from all </Directory> # Configure a virtual host and make the DACS documents available NameVirtualHost 127.0.0.1:18123 Listen 127.0.0.1:18123 <VirtualHost 127.0.0.1:18123> ServerName dodgers.dacstest.dss.ca DocumentRoot "/usr/local/apache-dacs/htdocs" ErrorLog "/usr/local/apache-dacs/logs/error_log" TransferLog "/usr/local/apache-dacs/logs/access_log" ScriptAlias /cgi-bin/ "/usr/local/apache-dacs/cgi-bin/" Alias /css "/usr/local/dacs/www/css/" Alias /dacs "/usr/local/dacs/www/" Alias /dtd-xsd "/usr/local/dacs/www/dtd-xsd/" Alias /examples "/usr/local/dacs/www/examples/" Alias /handlers "/usr/local/dacs/www/handlers/" Alias /infocards "/usr/local/dacs/www/infocards/" Alias /man "/usr/local/dacs/www/man/" Alias /misc "/usr/local/dacs/www/misc/" Alias /mod "/usr/local/dacs/www/mod/" </VirtualHost>
... NameVirtualHost 127.0.0.1:18123 NameVirtualHost hostip:18123 Listen 127.0.0.1:18123 Listen hostip:18123 <VirtualHost 127.0.0.1:18123 hostip:18123> ...
1.In our examples, we use port 18123, which
we're guessing is unlikely to already be in use on your machine. If you are
unlucky and it is in use, Apache will complain when you start it and
you will obviously need to select a different port number. So that the
examples will continue to work, consider creating a copy of this document and
changing all occurrences of "18123" to the port number you have
selected. If available, commands such as netstat(1)[14] and
sockstat(1)[15] can tell you which ports are currently in use. In the
event that you will be accessing your server from the other side of a firewall
(which is not recommended, as previously mentioned), keep in mind that traffic
may not ordinarily be passed through on this port.
2.If you are already running Apache on
port 80 (the default) or if you are not root whenever you run apachectl
in any of the following steps, you must comment out (or delete) all
Listen[16] directives for port 80 in httpd.conf. Therefore, comment out
all directives that look like any of the following:
Listen 80 Listen 0.0.0.0:80 Listen [::]:80
4.It is good practice to run httpd as
an unprivileged user id and Apache does this by default through the
User[17] directive in httpd.conf:
DACS web services are run as the same user id as httpd, but they
must be able to read and sometimes write files within the DACS
installation directory. These files should not be readable or writable by
other processes or anyone other than a DACS administrator. Using
mod_suexec[18] is one approach, but for the purpose of this tutorial we
want to keep things simple. Note that setting User[17] (or
Group[19]) to root is not a good idea.
The Apache documentation recommends setting up a new group specifically
for running the server, and we will take this approach. We will assume in our
examples that this group is called www. You may need to create this group (see
group(5)[20]) or you may already have a different but suitable group
name to use (e.g., webservd). Whatever group name you choose, when DACS
is installed in the next step you will be prompted for this group id and you
must make the appropriate change to httpd.conf:
Note
Because we will refer to this group name often in later steps, save its name as
the value of the shell variable dacsgroup (we will use
csh/tcsh syntax - use the syntax preferred by your shell):
Change the group id of files in the Apache installation directory to this
group and adjust permissions (you may have to do this as root):
User nobody
Group www
% set dacsgroup=www
% chgrp -R $dacsgroup /usr/local/apache-dacs % chmod -R g+w /usr/local/apache-dacs
5.Start your httpd...
% /usr/local/apache-dacs/bin/apachectl start
6.Use your favourite browser to verify that
Apache is serving content:
7.You should now check that your httpd
was built properly. First, make sure that test-cgi is executable (a CGI
that is installed by Apache):
And then invoke it:
Look for the SERVER_SOFTWARE variable in its output and ensure that its
value shows the correct versions of Apache, mod_ssl, and
OpenSSL; if you find something unexpected, you probably didn't
configure and/or install Apache or OpenSSL correctly.
% chmod 0750 /usr/local/apache-dacs/cgi-bin/test-cgi
8.You have confirmed that Apache is
properly installed, so stop the web server:
% /usr/local/apache-dacs/bin/apachectl stop
Step 3: Build and install DACS¶
Now it is time to build and install the DACS utilities and web services. Make your working directory the src subdirectory of the DACS distribution. 1.Build and install DACS web services
and utilities (note: gmake is the GNU Make utility, which you must
use):
If all goes well,
You will be prompted for the user id and group id to be used for DACS
files and directories. The group id you give should match the value you used
for Apache's Group directive (that is, the value of $dacsgroup).
The user id can be your user id. You will need to do gmake install as root if
your account has insufficient privileges to set the user and group ids that
you specify. The installation procedure will remember your answers to the
prompts; if you make a mistake or want to change them, do:
and try gmake install again.
% ./configure --prefix=/usr/local/dacs --disable-shared \ --enable-static --enable-passwd-auth \ --disable-bdb --with-apache=/usr/local/apache-dacs \ --with-expat=/usr/local % gmake
% gmake install
% conftools/setaccess-sh reset
Step 4: DACS-enable Apache¶
We'll continue by installing the mod_auth_dacs[21] module for Apache. Make your working directory the apache subdirectory of the DACS distribution. 1.Compile and install the
mod_auth_dacs module:
If this succeeds, your Apache httpd.conf[22] file should now
contain the following directive:
Please check that this is so. If you cannot find that directive, add it manually
near the part of httpd.conf that talks about the LoadModule[23]
directive.
% gmake tag % gmake install
LoadModule auth_dacs_module modules/mod_auth_dacs.so
2.Start Apache again:
and take another look at the SERVER_SOFTWARE variable, this time using
the DACS web service dacs_prenv, which displays its environment:
The SERVER_SOFTWARE variable ought to look the same as before, except it
should now also mention mod_auth_dacs.
Congratulations - you are now running a DACS-enabled web server!
DACS is not configured to do anything at the moment, mind you, but your
web server is now capable of DACS-wrapping web services. You should be
able to view the DACS manual pages served from the web server you just
installed:
% /usr/local/apache-dacs/bin/apachectl start
Step 5: Do basic DACS configuration¶
Although your Apache is now DACS-enabled, a little more configuration of both DACS and Apache are necessary before you can do anything interesting. We'll continue by working with the DACS configuration (see dacs.conf(5)[25]). We begin this step by defining a new DACS federation that consists of one jurisdiction. We will call the new federation DACSTEST and associate it with the domain name dacstest.dss.ca. We will call our jurisdiction LA. Incidentally, the names that we are using in this tutorial for our federation and jurisdiction ("DACSTEST", "LA", and "dacstest.dss.ca") are not "special"; there's an underlying theme that should be apparent to any baseball fan but we could have chosen any syntactically valid names. The domain name for our jurisdiction (dodgers.dacstest.dss.ca) is only special in that it is a subdomain of dacstest.dss.ca; this must be the case for all jurisdictions in our example federation.% set dacs=/usr/local/dacs % set bin=$dacs/bin % set feds=$dacs/federations % set la=$feds/dacstest.dss.ca/LA
1.Although you can get away with having a
single DACS configuration file on a host, we recommend a hierarchical
organization. The file site.conf, although optional, holds standard default
configuration directives as well as site-specific directives for all
federations configured on this host. One or more files named dacs.conf can be
used on a per-jurisdiction, per-federation, or per-host basis; that is, each
jurisdiction on a host can have its own dacs.conf, or all (or some) of the
jurisdictions on a host can share a dacs.conf, or everything can just be
lumped into one dacs.conf. It's entirely up to you.
When configure is run to build DACS, you can specify default
locations for various configuration files, including site.conf and dacs.conf.
We did not change the defaults when we built DACS, so our examples will
use the default paths.
Tip
We recommend that you always use the site.conf-std that comes with your
DACS distribution as your site.conf file and that you do not make any
modifications to it, instead putting customizations in your dacs.conf file.
This will make upgrades easier and less error-prone.
Proceed by installing the default site configuration file as $feds/site.conf:
Note
If the install command is unavailable on your system, you can use
src/conftools/install-sh relative to your DACS distribution directory.
Or just use cp (or mkdir), chgrp, and chmod.
% install -c -g $dacsgroup -m 0640 $feds/site.conf-std $feds/site.conf
2.Since we are not using SSL in this
tutorial, edit $feds/site.conf and change the value of the
SECURE_MODE[28] directive to "off". For production use, the
directive's value should always be "on":
SECURE_MODE "off"
3.It is convenient - though not required - to
collect the configuration directives for all jurisdictions on this host in a
single file. It's not unusual for a host to be associated with just one
jurisdiction (and one federation), but this is certainly not always the case.
% install -c -g $dacsgroup -m 0660 /dev/null $feds/dacs.conf
4.We will create a directory where most of
the files associated with our new federation will live:
% install -d -g $dacsgroup -m 0770 $feds/dacstest.dss.ca
5.And a subdirectory within it where most of
the files associated with our new jurisdiction will live:
% install -d -g $dacsgroup -m 0770 $la
6.Create a directory where we will put access
control rules (also called ACLs, access control lists, or simply rules) for
our jurisdiction, and we also need an empty revocation file:
% install -d -g $dacsgroup -m 0770 $la/acls % install -c -g $dacsgroup -m 0660 /dev/null $la/acls/revocations
7.Create directories where we will put group
definitions for our jurisdiction and define the membership of our federation:
Paste the following text into $la/groups/DACS/jurisdictions.grp:
(Change 18123 if you are using a different port.) The purpose of
jurisdictions.grp is to provide DACS with information about the
jurisdictions in this federation. All jurisdictions in a federation should use
identical jurisdictions.grp files. We're not going to make much use of this in
this document, but if you add a jurisdiction or if any of this information
changes, this file would ordinarily be updated. For instance, if you were to
add a jurisdiction to your federation, you should add another group_member
element to the group_definition that describes the new jurisdiction, and then
copy the updated jurisdictions.grp file to each jurisdiction. Please see
dacs.groups(5)[29] for additional information.
% install -d -g $dacsgroup -m 0770 $la/groups $la/groups/LA $la/groups/DACS % install -c -g $dacsgroup -m 0660 /dev/null $la/groups/DACS/jurisdictions.grp
<groups xmlns="http://dss.ca/dacs/v1.4"> <group_definition jurisdiction="LA" name="jurisdictions" mod_date="Tue, 14-Jun-2005 16:06:00 GMT" type="public"> <group_member jurisdiction="LA" name="LA Jurisdiction" type="meta" alt_name="Test Jurisdiction for the LA Dodgers" dacs_url="http://dodgers.dacstest.dss.ca:18123/cgi-bin/dacs" authenticates="yes" prompts="no"/> </group_definition> </groups>
8.We need some basic configuration directives
for the jurisdiction LA. Paste the following text into $feds/dacs.conf:
<Configuration xmlns="http://dss.ca/dacs/v1.4"> <Default> FEDERATION_DOMAIN "dacstest.dss.ca" FEDERATION_NAME "DACSTEST" LOG_LEVEL "info" </Default> <Jurisdiction uri="dodgers.dacstest.dss.ca"> JURISDICTION_NAME "LA" </Jurisdiction> </Configuration>
9.And let's make this the default
configuration file for DACS jurisdictions at this site:
% rm -f $la/dacs.conf % ln -s $feds/dacs.conf $la/dacs.conf
10.Now, let's ask DACS to display its
configuration by running the dacsconf(1)[30] utility:
This configuration is the result of merging the contents of $la/dacs.conf (which
points to $feds/dacs.conf) and $feds/site.conf, with directives in the former
file overriding directives in the latter.
% $bin/dacsconf -uj LA -q
11.We must create encryption keys for this
federation using the dacskey(1)[31] utility:
We could not do this until after the jurisdiction had been configured because
dacskey needs to look at dacs.conf.
Security
The federation key file must be kept secret. Any person or process that
can read the federation key file can create DACS identities. It should
be readable only by its owner and DACS and not readable
by anyone else.
% install -c -g $dacsgroup -m 0640 /dev/null $feds/dacstest.dss.ca/federation_keyfile % $bin/dacskey -uj LA -q $feds/dacstest.dss.ca/federation_keyfile % ls -l $feds/dacstest.dss.ca/federation_keyfile
12.Similarly, we should create encryption keys
for our jurisdiction:
Like the federation keys, these keys must also be kept secret. But the
jurisdiction keys are private to their jurisdiction and are not shared among
federation members.
% install -c -g $dacsgroup -m 0640 /dev/null $la/jurisdiction_keyfile % $bin/dacskey -uj LA -q $la/jurisdiction_keyfile % ls -l $la/jurisdiction_keyfile
13.Make sure that all of the files and
directories starting with /usr/local/dacs have appropriate permissions, as
discussed earlier.
Step 6: Do basic Apache configuration for DACS¶
Your Apache is now DACS-enabled and we've configured DACS. Before we can do anything interesting we must make some changes to the Apache configuration. We will begin by DACS-wrapping DACS web services, which is required. 1.Edit /usr/local/apache-dacs/conf/httpd.conf
and locate the VirtualHost[10] section that you added earlier. Inside
that VirtualHost section and near its end, add the following text (remember to
adjust paths as necessary):
These directives configure the virtual host to DACS-wrap the contents of
all URLs that fall under the /cgi-bin/dacs namespace. The first three
directives tell mod_auth_dacs where to find the external DACS
access control program ( dacs_acs(8)[32]) and the DACS
configuration file.
AddDACSAuth dacs-acs /usr/local/dacs/bin/dacs_acs "-t -v" SetDACSAuthMethod dacs-acs external SetDACSAuthConf dacs-acs "/usr/local/dacs/federations/dacs.conf" <Location /cgi-bin/dacs> AllowOverride AuthConfig Require valid-user Options ExecCGI AuthType DACS AuthDACS dacs-acs </Location>
2.Restart Apache so that it uses its
new configuration:
DACS should now be enforcing access control on the /cgi-bin/dacs part of
the server's URL space.
% /usr/local/apache-dacs/bin/apachectl restart
3.Check that you can still access
test-cgi (which you have not DACS-wrapped):
4.Now, let's see what happens when we try to
access dacs_prenv:
You should get a "403 Forbidden" error, which will cause DACS
to display an "Access Denied by DACS" page (actually, it is the
contents of the file /usr/local/dacs/www/handlers/acs_failed.html). This
happens because the default rules do not grant access to dacs_prenv, so
all access will be denied.
5.To finish up this step, let's add a rule
that will grant everyone access to dacs_prenv. Create
$la/acls/acl-prenv.0 with appropriate permissions:
and then paste the following text into it:
Whenever you add or change an access rule, you must rebuild the rule index for
the jurisdiction:
(It's currently only really necessary to run dacsacl if you add a rule or
modify any part of a rule's services element, but this may change in a future
release so just do it always.)
This rule grants everyone access, so invoking dacs_prenv should work now:
This output includes some new environment variables that are passed to all
DACS-wrapped programs. These variables begin with "DACS_",
such as DACS_VERSION - see dacs_acs(8)[33] for additional
information.
% install -c -g $dacsgroup -m 0660 /dev/null $la/acls/acl-prenv.0
<acl_rule status="enabled"> <services> <service url_expr='"${Conf::dacs_cgi_bin_prefix}/dacs_prenv${Conf::dacs_cgi_bin_suffix}"'/> </services> <rule order="allow,deny"> <allow> user("any") </allow> </rule> </acl_rule>
% $bin/dacsacl -uj LA
Step 7: Test basic DACS services¶
There's still not too much you can do at this point, but there are a few DACS services that you can try. If one of these requests fails, take a look at the DACS log files in the /usr/local/dacs/logs directory for clues. The most likely cause is incorrect permissions on a file or directory, or possibly you made an editing mistake. 2.The dacs_list_jurisdictions(8)[35]
web service displays information about jurisdictions:
You may recognize some of this material from the jurisdictions.grp file.
3.We saw the conf utility earlier. We
can get the same information from a web service:
Ooops! You should have been denied access to this web service. If you examine
the default ACL (see dacs.acls(5)[36]) for this web service, which can
be found in /usr/local/dacs/acls/acl-conf.0, you might suspect that access to
dacs_conf will only be granted to identities that satisfy the
expression "dacs_admin()" (see dacs.exprs(5)[37]). And since
you have not established a DACS identity yet, the ACL should deny
access. After we do a little more DACS configuration work in the next
step, we will give this another try.
Step 8: Try DACS authentication¶
It is possible to create "accounts" specifically for DACS users. These identities are managed by the dacspasswd(1)[38] utility and are "private" in that they are unrelated to any other identities you might have on your system, unless you tie them together (similar to Apache's htpasswd[39] command). For example, we can create a DACS identity named "root" that has no relationship to a Unix system's superuser - perhaps you are creating a DACS account for actor Stephen Root[40]. 1.We begin this step by creating an empty
password file for dacspasswd (to ensure correct permissions). Then we
create a DACS account for username "sandy".
You will be prompted for a password to assign to sandy's account. Choose any
password you like as long as it is at least six characters long. You can
change sandy's password by running this command again.
% install -c -g $dacsgroup -m 0660 /dev/null $la/passwd % $bin/dacspasswd -uj LA -q -a sandy
2.Next, we edit $la/dacs.conf and add the
following text in the Jurisdiction section for dodgers.dacstest.dss.ca:
This configuration enables authentication (see dacs_authenticate(8)[41])
for accounts managed by the dacspasswd utility. Check again that all
files starting with /usr/local/dacs have appropriate permissions, as discussed
earlier.
<Auth id="passwd"> URL \ "http://dodgers.dacstest.dss.ca:18123/cgi-bin/dacs/local_passwd_authenticate" STYLE "pass" CONTROL "sufficient" </Auth>
3.We should now be able to authenticate
("login") as sandy by providing the password you set up earlier. If
successful, your browser will be sent credentials (in an HTTP cookie) for the
identity DACS calls LA:sandy. Note that the cookies DACS creates
are deleted when your browser exits. Even if a cookie is not deleted, DACS
credentials have a limited lifetime and will become useless when they expire.
DACS comes with examples of simple HTML login pages with which you can
authenticate:
Your browser must have JavaScript enabled to use this page. Select the
jurisdiction (LA), enter the username (sandy) and password, and then click
"Login". If all is well, you should see the "DACS
Authentication Succeeded" page, which is the contents of
/usr/local/dacs/www/handlers/auth_ok.html. Of course in a production
environment you would write custom login and signout pages, or integrate the
functionality with a portal or in whatever way you prefer for your site.
4.Things get a bit more interesting now that
you are able to authenticate. You can follow one link on the "DACS
Authentication Succeeded" page to see your current credentials (using
dacs_current_credentials[42]) or another to visit a page that will
allow you to signout ( dacs_signout(8)[43]) from all or some identities
(you can also invoke dacs_signout directly[44] to signout from all
identities). If you signout, there will be a link that you can follow to login
again.
5.Use dacspasswd to create another
account:
You can now authenticate as sandy or don. You can also have both identities
active at the same time (try it)!
% $bin/dacspasswd -uj LA -q -a don
6.Now that you're able to authenticate, let's
have another try at running dacs_conf (recall you were not granted
access to it earlier). We must first make one of the identities that you have
created a DACS administrator identity. Edit $la/dacs.conf and add the
following text in the Jurisdiction section for dodgers.dacstest.dss.ca (but
not within the Auth section):
As you might assume, this confers special privileges to LA:sandy.
Authenticate as sandy using the login page and then try this link again
(it should work this time):
If you signout[45] as sandy, then authenticate as don, and try
http://dodgers.dacstest.dss.ca:18123/cgi-bin/dacs/dacs_conf again, you
should be denied access.
ADMIN_IDENTITY "LA:sandy"
7.In an earlier step, you created an ACL
($la/acls/acl-prenv.0) that grants access to dacs_prenv to any user,
whether authenticated or not. Edit that rule and replace:
with:
Try invoking dacs_prenv[46] when you are not authenticated - you should
be denied access. Now authenticate and try dacs_prenv[46] again - it
should work. Edit the rule again and replace:
with:
Now you should only be granted access if you've authenticated as the DACS
username LA:don.
user("any")
user("auth")
user("auth")
user("LA:don")
Step 9: DACS-wrapping a web service¶
To use DACS to control access to a resource, there are just a few things you need to do:•Make the URL space in which the
resource lies within the scope of a Location[47] directive for the
VirtualHost that corresponds to the DACS jurisdiction responsible for
the resource.
•Make an appropriate DACS access
control rule for the jurisdiction responsible for the URL space in which the
resource lies.
Step 10: What's next?¶
Having successfully completed all of the previous steps, you should have a feel for some of the things that you can do with DACS. Of course, there's much more to DACS than what we've covered. You should be capable of using the system you've configured to this point to try some things on your own. Here are a few ideas (in order of increasing difficulty):•Add a DACS-wrapped resource and
experiment with access control rules. It might be a static web page or a CGI
program. Remember that by default, your site-specific ACLs for the
jurisdiction LA are files in the $la/acls directory. Review
dacs.acls(5)[49] before beginning.
•Assign a few roles to DACS user
sandy and modify an access control rule to consider roles when granting or
denying access. Roles provide a convenient way to classify users so that
access control rules can be concisely written to grant (or deny) access to a
set of users that are related in some way. For example, you might assign some
users to "students", some to "staff", and some to
"faculty", and then write rules that reference those roles rather
than individual DACS usernames. Roles only have meaning with respect to
how they are used in ACLs, so you can make up any syntactically valid words
you want.
Here are some hints to get you started. You'll need to do two things: assign
roles to users and enable roles. Once enabled, your DACS will look for
roles in the file $la/roles. Each line of that file assigns roles to a user
and consists of the username, a colon, and a comma-separated list of roles.
For example:
The other thing you'll need is some DACS configuration to enable roles.
Add the following to the Jurisdiction section of dacs.conf:
Now you can create rules that depend on the user making the request having
certain roles. For example, a rule can be written to grant access to a
resource only if the user making the request has the role "pitchers"
by using the predicate (see dacs.exprs(5)[50]):
Or you can create a rule that will grant access only if the user has the roles
"active-players" and "pitchers"; use the predicate:
sandy:pitchers,retired-players don:pitchers,retired-players eric:pitchers,active-players cesar:infielders,active-players
<Roles id="roles"> URL "http://dodgers.dacstest.dss.ca:18123/cgi-bin/dacs/local_roles" </Roles>
user("%LA:pitchers")
user("%LA:pitchers") and user("%LA:active-players")
•If you create a DACS account for
a username that corresponds to a user on your system, you can configure
DACS to assign roles to that user based on the Unix groups that she
belongs to. This is very easy to do: instead of using local_roles as in
the example above, use local_unix_roles instead. If you create a
DACS account for alice, for example, and the account "alice"
has group membership on your system (see group(5)), then alice would
authenticate using her DACS password and be assigned roles from her
Unix group membership.
Instead of using a DACS account to authenticate alice, you can easily
configure DACS to use alice's Unix password. The DACS module
local_unix_authenticate, which must be installed set-uid root so that
it can access passwords, provides this functionality.
•Add a DACS jurisdiction named NY
(yankees.dacstest.dss.ca) on the same host where you configured
dodgers.dacstest.dss.ca. You do not have to configure authentication at the
new jurisdiction. Notice that you can authenticate at dodgers.dacstest.dss.ca
and then access resources at yankees.dacstest.dss.ca. This is "single
sign-on".
•Run DACS on an additional host.
The procedure is basically the same as what you already did in this tutorial.
Name the jurisdiction BOSTON and assign it the domain name
redsox.dacstest.dss.ca. You won't be able to use the IP address 127.0.0.1 for
this; you'll have to alias the domain names to the IP addresses of real
interfaces and make the same changes to /etc/hosts on both hosts. You'll also
have to use the identical federation_keyfile on both hosts (simply copy the
file you've already made).
•Configure a different (or additional)
authentication method for your jurisdiction. See
dacs_authenticate(8)[51]. For the password style of authentication, you
might try the NTLM authentication method. For a bit more of a challenge, see
if you can make the expr or cert style of authentication work.
Step 11: Clean up¶
If you are done, you may want to do some clean up now. First, stop Apache:% /usr/local/apache-dacs/bin/apachectl stop
Troubleshooting¶
The first thing to do if you encounter a problem is to check that you've got the latest version of DACS; a newer version might fix your problem. Also, visit the Post-Release Notes[52] area for your release in case a newer edition of this document is available or a bug fix has been posted. By default, the DACS log files are put in the /usr/local/dacs/logs directory. If you encounter any problems or just want to see what's going on, examine the log files in that directory. Depending on the DACS LOG_LEVEL[53] and LOG_FILTER[54] directives in effect, log files can quickly become big. It is safe to delete them or truncate them at any time. In the event of problems, you should also take a look at the Apache logs (in /usr/local/apache-dacs/logs). There are five main sources of problems: 1.Typos (you got the spelling or punctuation
incorrect),
2.File permissions are incorrect (DACS
cannot read or write its files or directories),
3.You didn't follow the instructions
correctly (you skipped something or misunderstood something),
4.You ran into unexpected platform
dependencies, or
5.We goofed.
SEE ALSO¶
AUTHOR¶
Distributed Systems Software ( www.dss.ca[56])COPYING¶
Copyright2003-2012 Distributed Systems Software. See the LICENSE[57] file that accompanies the distribution for licensing information.NOTES¶
- 1.
- FAQ
- 2.
- manual pages
- 5.
- an Apache configuration task
- 6.
- contact us
- 7.
- Apache
- 8.
- OpenSSL
- 9.
- Expat
- 10.
- VirtualHost
- 11.
- Directory
- 12.
- Alias
- 13.
- DocumentRoot
- 14.
- netstat(1)
- 15.
- sockstat(1)
- 16.
- Listen
- 17.
- User
- 18.
- mod_suexec
- 19.
- Group
- 20.
- group(5)
- 21.
- mod_auth_dacs
- 22.
- httpd.conf
- 23.
- LoadModule
- 25.
- dacs.conf(5)
- 26.
- dacsinit(1)
- 27.
- Initial Configuration
- 28.
- SECURE_MODE
- 29.
- dacs.groups(5)
- 30.
- dacsconf(1)
- 31.
- dacskey(1)
- 32.
- dacs_acs(8)
- 33.
- dacs_acs(8)
- 34.
- dacs_version(8)
- 36.
- dacs.acls(5)
- 37.
- dacs.exprs(5)
- 38.
- dacspasswd(1)
- 39.
- htpasswd
- 40.
- Stephen Root
- 42.
- dacs_current_credentials
- 43.
- dacs_signout(8)
- 44.
- invoke dacs_signout directly
- 45.
- signout
- 46.
- dacs_prenv
- 47.
- Location
- 48.
- Virtual Hosts
- 49.
- dacs.acls(5)
- 50.
- dacs.exprs(5)
- 52.
- Post-Release Notes
- 53.
- LOG_LEVEL
- 54.
- LOG_FILTER
- 55.
- dacs(1)
- 56.
- www.dss.ca
- 57.
- LICENSE
10/22/2012 | DACS 1.4.27b |