What to do first

CF_GUAuthorizerUser can't work properly until you have taken certain steps. Before going further make sure that you:

1. Requested and obtained a folder on the web server that is restricted to all NetID users, using the access restriction request form.
2. Used the authorization system administrator to create one or more policies and, if necessary, one or more groups.
3. Placed the CF_GUAuthorizerUser custom tag in a ColdFusion template (.cfm file) located in your access restricted folder, using the attributes specified in the custom tag documentation.

When everything works

The use of CF_GUAuthorizeUser involves interaction between your web browser, the web server, CGI, the ColdFusion application server, and your application. To troubleshoot problems using CF_GUAuthorizeUser, we must first understand what happens when CF_GUAuthorizeUser works properly.

In normal operation, the following steps take place the first time you browse to a ColdFusion template that contains CF_GUAuthorizeUser:

1. Your browser requests the page from the web server.
2. The web server determines that the page is in a directory that is restricted to users who have a NetID login. The web server requests a login (NetID and password) from your browser.
3. Your web browser requests a login from you, you provide it, and your browser sends it back to the web server.
4. The web server connects to the University's LDAP directory server and verifies that you provided a valid NetID and matching password.
5. If your login is valid, your username (but not your password) is stored by the web server in a CGI environment variable named REMOTE_USER.
6. The web server determines that the page you requested is a ColdFusion template and passes it to the ColdFusion application server to be processed.
7. The ColdFusion application server process the template and processes whatever is in the template until it reaches the CF_GUAuthorizeUser custom tag.
8. The ColdFusion application server processes the CF_GUAuthorizeUser custom tag, which does the following:
   1. The tag looks up the policy specified in the Policy attribute and determines which groups are authorized to view the page according to the policy.
   2. The tag determines if the current user (identified by the REMOTE_USER environment variable) is a member of any of the authorized groups.
   3. The authorized groups may include dynamic groups such as "all faculty" or "all students." If any of the authorized groups are dynamic groups, the tag connects to the University's LDAP directory server and looks up the current user to determine if the user is a faculty member, student, etc.
   4. If the current user is a member of an authorized group that is listed in the policy as "administrator," the tag sets the Administrator variable to True.
   5. If the current user is a member of any authorized group, the tag returns control to the template.
9. The ColdFusion application server finishes processing whatever else is in the template and returns a web page to the web server.
10. The web server returns the completed web page to your browser for you to view.
11. Since your login was successful, your browser stores it. If you return to the same directory in the future, step 3 takes place automatically. Your browser stores your login until you close it.  

In the above process, steps 2 through 5 include both authentication and authorization. The web server uses your login to determine that you are who you say and that you are authorized to access files in the specified directory. Step 8 is a further authorization stage, in which CF_GUAuthorizeUser determines that you are allowed to use the page you requested.

What could possibly go wrong?

The above process contains a number of decision points that can prevent the process from completing successfully:

• In step 2: If your template is not located in a directory that is access restricted, the web server will not request a login and CF_GUAuthorizeUser will assume that you are not authorized. 
• In steps 4 and 8c: If the University's LDAP server is not available, the web server and CF_GUAuthorizeUser will not be able to 
• In step 4: If your login is not valid, the web server will return an error message saying that you are Unauthorized.
• In step 6: If the file you are browsing to is not a ColdFusion file (ending in .cfm or .cfml), it will not be processed by the ColdFusion application server, CF_GUAuthorizeUser will not be invoked, and the file will be returned to your web browser whether you are authorized or not (as long as you were able to log in to the directory).
• In step 8e: If you are not a member of a group authorized by the specified policy, CF_GUAuthorizeUser aborts the processing of the template and forwards you to an error page.

A common scenario is for the CF_GUAuthorizeUser custom tag to be placed in the Application.cfm file, in which case it is processed as part of any ColdFusion template in the same directory or in a subdirectory that does not have its own Application.cfm file.

Troubleshooting guide

The following table outlines possible solutions if CF_GUAuthorizeUser doesn't seem to work normally when you or another user request a ColdFusion template: