Tutorial

Current:Tutorial Previous:kshAuth Home Page kshAuth Installation Change Top Dir Look and Feel

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.