kshAuth - Authentication and Authorization Interface for Apache
2.2+ Web Server
Version 0.2
Tutorial for kshAuth
This document is a short tutorial on the usage of kshAuth, which is
a set of utilities designed to provide an easy to use web based
interface to the Apache "htpasswd" command. These utilities use the
"htpasswd" command in combination with the "htaccess" file to provide
directory based password protection capabilities.
The original purpose of "kshAuth" was to provide minimal protection
for an internal documentation server. It was not designed for public
access.
This set of utilities provides a web based interface for
implementing password protection for a directory structure made
available by an Apache web server. The Apache utility "htpasswd" is
used to generate and modify passwords, and controlled by the ".htaccess"
file.
The kshAuth distribution contains an example directory structure
already built in the documentation directory. This structure is for
example and tutorial purposes only and may be removed at any time.
Several assumptions are made regarding the installation directory
structure in order to provide a useful description of the activities in
this tutorial.
Those Assumptions are:
The "kshAuth" document directory is at the following location:
/usr/local/apache2/htdocs/kshAuth
The "kshAuth" cgi-bin directory is at the following location:
/usr/local/apache2/cgi-bin/kshAuth
The "kshAuth" authorization structure directory is at the following
location:
/usr/local/apache2/kshAuth
Lesson 1: View the pre-defined directory
structure
Using a web browser, view the top level document at the following
URL:
http://localhost/kshAuth/index.html
Where "localhost" represents the name of the web server where
kshAuth is installed. The remainder of this document will reference
your web server host name as "localhost" and may be replaced by your
actual hostname.
Navigate the directory structure to familiarize yourself with the
documents and the relationships between them. When finished, return to
the top level directory at:
http://localhost/kshAuth/index.html
Lesson 2: The kshAuth Utilities page
Assuming your web browser is open on the page:
http://localhost/kshAuth/index.html
Click on the link labeled "Go to kshAuth Utilities to configure this
directory for authorization." You will be directed to the kshAuth
Utilities page which provides access to all the available tools.
Observe the link-bar at the top of the page provides access to the
following locations:
- Current Working Directory
- kshAuth Utilities
- Authorization Map
- Directory Map
The "Current Working Directory" link will return to the HTML page
associated that directory. "kshAuth Utilities" is the current page you
are now viewing. "Authorization Map" provides a map to all the
authorization levels configured for kshAuth directory administrators and
users. "Directory Map" provides a map of the entire directory structure
under control of kshAuth.
Click on the "Directory Map" link, then select the link "Operating
Systems" at the following directory structure:
/kshAuth/Software/Operating Systems/
This will return you to the "kshAuth Utilities" page with the
directory "/kshAuth/Software/Operating Systems" selected as the "Current
Working Directory".
Whenever modifying the kshAuth authorization structure, be aware of
your current working directory, as it is used to determine which
authorization structure to use for validation of users and directory
administrators.
Now password protect the directory:
/kshAuth/Software/Operating Systems/
On the kshAuth Utilities page, select the link labeled "Enable
Password Protection". You will be prompted to select an administrator
ID and enter a password associated with the ID. Select "admin" and
enter "admin" as the password. If the "admin" password has been
changed, enter the current password. Then click the "submit" button and
the current working directory "/kshAuth/Software/Operating Systems" will
be password protected.
In order to access this directory, you will now need to grant access
to users, which can be performed via the "kshAuth Utilities" page.
Lesson 3: Grant Access to Users
Assuming your web browser is open on the "kshAuth Utilities" page,
click on the link labeled "Authorization Map". Look for the page
section identified with the title "User Authorization Structure". Under
this section you should see the directory previously enabled for
password protection in lesson 2. Click on the "Operating Systems" link
to go to the "kshAuth Utilities" page to grant users access to the
"Operating Systems" directory.
On the "kshAuth Utilities" page, under the section labeled
"Directory Administrator Utilities" the link labeled "Grant Access"
should now be available. Click on this link.
Select the directory administrator "admin" and enter the current
password, the default password is "admin".
In the "User ID" text box, enter one or more user names to which you
want to grant access to the current directory. Check the top of the
page to ensure the current directory is:
/kshAuth/Software/Operating Systems/
Then enter the initial password that you wish to assign to the
user(s). Re-enter the password in the next text box to ensure it was
entered correctly. Then click the "Submit" button to process your
entries.
Lesson 4: Deny Access to Users
Assuming your web browser is open on the "kshAuth Utilities" page,
click on the link labeled "Authorization Map". Look for the page
section identified with the title "User Authorization Structure". Under
this section you should see the directory previously enabled for
password protection in lesson 2. Click on the "Operating Systems" link
to go to the "kshAuth Utilities" page to deny users access to the
"Operating Systems" directory.
On the "kshAuth Utilities" page, under the section labeled
"Directory Administrator Utilities" the link labeled "Deny Access"
should now be available. Click on this link.
Select the directory administrator "admin" and enter the current
password, the default password is "admin".
In the "User ID" select box, select one or more user names for which
you want to deny access to the current directory. Check the top of the
page to ensure the current directory is:
/kshAuth/Software/Operating Systems/
Click the "Submit" button to process your entries.
Lesson 5: Disable Password Protection
Assuming your web browser is open on the "kshAuth Utilities" page,
click on the link labeled "Authorization Map". Look for the page
section identified with the title "User Authorization Structure". Under
this section you should see the directory previously enabled for
password protection in lesson 2. Click on the "Operating Systems" link
to go to the "kshAuth Utilities" page to disable password protection for
the "Operating Systems" directory.
On the "kshAuth Utilities" page, under the section labeled
"Directory Administrator Utilities" the link labeled "Disable Password
Protection" should now be available. Click on this link.
Select the directory administrator "admin" and enter the current
password, the default password is "admin". Check the top of the page to
ensure the current directory is:
/kshAuth/Software/Operating Systems/
Click the "Submit" button to remove password protection from this
directory. This does not remove any existing users, it simply disables
password protection. If you later re-enable password protection, any
users that previously existed will have access to this directory again
without having to re-add them.
Lesson 6: Add a Directory Administrator
Assuming your web browser is open on the "kshAuth Utilities" page,
click on the link labeled "Authorization Map". Look for the page
section identified with the title "Directory Administrator Authorization
Structure". Under this section you should see the directory previously
enabled for password protection in lesson 2. Click on the "kshAuth"
directory link to go to the "kshAuth Utilities" page to add a directory
administrator.
On the "kshAuth Utilities" page, under the section labeled
"Directory Administrator Utilities", click on the link labeled "Add
Directory Administrator".
Select the existing directory administrator "admin" and enter the
current password, the default password is "admin".
In the "New Directory Administrator ID" text box, enter one or more
user names for which you want to make them directory administrator's.
These user names do not need to already exist as a user on the system or
within the kshAuth structure. Check the top of the page to ensure the
current directory is "/".
Then enter the initial password that you wish to assign to the new
directory administrator(s). Re-enter the password in the next text box
to ensure it was entered correctly. Then click the "Submit" button to
process your entries.
Lesson 7: Remove a Directory
Administrator
Assuming your web browser is open on the "kshAuth Utilities" page,
click on the link labeled "Authorization Map". Look for the page
section identified with the title "Directory Administrator Authorization
Structure". Under this section you should see the directory previously
enabled for password protection in lesson 2. Click on the "kshAuth"
directory link to go to the "kshAuth Utilities" page to add a directory
administrator.
On the "kshAuth Utilities" page, under the section labeled
"Directory Administrator Utilities", click on the link labeled "Remove
Directory Administrator".
Select the existing directory administrator "admin" and enter the
current password, the default password is "admin".
In the "Administrator ID's to Remove" select box, select one or more
names for which you want to remove them as directory administrators.
Check the top of the page to ensure the current directory is: "/".
Click the "Submit" button to process your entries.
Lesson 8: Create Administrator Authorization
Level
kshAuth allows a directory administrator to delegate administration
duties to other users on a directory by directory basis. This lesson
describes how to do that.
Assuming your web browser is open on the "kshAuth Utilities" page,
click on the "Directory Map" link near the top of the page, then select
the link "Operating Systems" at the following directory structure:
/kshAuth/Software/Operating Systems/
This will return you to the "kshAuth Utilities" page with the
directory "/kshAuth/Software/Operating Systems" selected as the "Current
Working Directory".
On the kshAuth Utilities page, select the link labeled "Create Admin
Authorization Level".
Observe the "Current Authorization Structure for Administrator: /"
near the top of the page. The administrator user name an password you
will enter is associated with this directory structure. The directory
administrator you create will be subordinate to this.
Select the directory administrator for the "admin" and enter the
current password, the default password is "admin".
Click the "Submit" button to create the new directory administrator
authorization level. View the "Authorization Map" to see that it was
created. By default the "admin" user and password is added to this new
authorization structure.
Lesson 9: Remove Administrator Authorization
Level
Assuming your web browser is open on the "kshAuth Utilities" page,
click on the link labeled "Authorization Map". Look for the page
section identified with the title "Directory Administrator Authorization
Structure", then select the link "Operating Systems" to remove the
previously created structure in lesson 8.
/kshAuth/Software/Operating Systems/
This will return you to the "kshAuth Utilities" page with the
directory "/kshAuth/Software/Operating Systems" selected as the "Current
Working Directory".
Observe the "Parent Administrator Authorization Structure" and the
"Child Administrator Authorization Structure". You will be asked to
select an administrator and enter a password from the Parent structure
to remove the child structure. Only an administrator from the parent
can remove a child.
On the kshAuth Utilities page, select the link labeled "Remove Admin
Authorization Level".
Select the parent directory administrator "admin" and enter the
parent password for this user, the default password is "admin".
Click the "Submit" button to remove the directory administrator
authorization level. View the "Authorization Map" to see that it was
removed.
|
