This tag is used to carry out user authorization for ColdFusion templates. It is used in templates that are located in access-restricted web directories, where users have already been authenticated by the web server. Developers use the web-based authorization system administrator to create groups and associate them with policies, or to select predefined groups and policies.

A policy defines what kind of access one or more groups have. Each policy is given an ID number in the authorization system administrator. For example, policy 10 could specify normal access for the AllStaff group and Administrator access for the Webmaster group.

If you are having trouble using CF_GUAuthorizeUser, please see our troubleshooting guide.

Attributes

• Policy -- Required. Must be the ID number of a policy defined in the authorization system administrator.
• ErrorURL -- Optional. If present, the URL in this attribute overrides the URL specified in the authorization system administrator as the error page for the policy specified in the Policy attribute. This attribute has no effect if this tag is used as a tag pair.
• Cache -- Optional. Acceptable values are Yes or No; default is Yes. See below for more information on caching.

Usage

Use this tag in any ColdFusion template in which there is content (including CFML code) that only some users are authorized to access. The current user is considered to be authorized if:

• The template is located in an access-restricted web directory,
• The policy identified by the Policy attribute is defined in the authorization system administrator and there is at least one group linked to the policy,
• The current user (identified by the read-only environment variable CGI.REMOTE_USER) is a member of one of the groups linked to the policy, and
• The policy state is set to Up, or the policy state is set to Admin and the user is a member of a group that is linked to the Policy as Administrator.

If this tag is used as a single tag and the user fails the authorization test, he or she is redirected to the URL specified in the ErrorURL attribute (if present) or in the policy's error URL field in the authorization system administrator. If the user is authorized, there is no effect (the template executes normally). For example:

<CF_GUAuthorizeUser Policy="110" ErrorURL="http://www.georgetown.edu/">

If the user is not authorized under policy number 110, the user will see the Georgetown University home page instead of this text.

If this tag is used as a tag pair and the user fails the authorization test, only the content enclosed by the tag pair is not executed or displayed. If the user is authorized, there is no effect (the content of the tag pair executes or displays normally). For example:

<CF_GUAuthorizeUser Policy="110">

If the user is not authorized under policy number 110, the user will not see this text.

</CF_GUAuthorizeUser>

However, the user will see this text regardless.

Multiple instances of this tag and multiple policies may be used in one template. Thus, a template can contain several blocks of content that do or don't appear to different users.

When used as a single tag, this tag can be placed in an Application.cfm file, where it will provide authorization for all templates to which the Application.cfm file applies. The same principle applies to index.cfm files in applications using the FuseBox technique.

In addition to performing authorization, the tag also returns a boolean variable called Administrator. The value of Administrator is True if the current user is a member of a group that is linked to the policy specified in the tag as Administrator. Otherwise, the value of Administrator is False. For example:

<CF_GUAuthorizeUser Policy="110">

The user will see this text if he or she is authorized under policy number 110.

<cfif Administrator>

The user will only see this text if he or she is part of a group that is an Administrator for this policy.

</cfif>

</CF_GUAuthorizeUser>

The user will see this text regardless.

<cfif Administrator>

The user will only see this text if he or she is part of a group that is an Administrator for the policy specified in the last CF_GUAuthorizeUser tag (in this case, policy 110).

</cfif>

The performance of this tag is improved if caching is enabled (the default setting). When caching is enabled, the tag does not re-query the authorization database when the same user encounters the same policy. However, this means that changes made in the authorization system administrator (such as group membership and policy state) will have no effect on the template where the tag is used until the cache expires (after one hour). The cache is specific to each policy but not to each user or tag; thus, when a user encounters a tag with caching disabled, caching is reset for that policy for all users.

It is important for developers to note that this tag can only protect content contained in the ColdFusion template(s) that call this tag. This tag cannot prevent web users from downloading HTML files, images, or data files from a public web directory. However, this tag can be used in conjunction with the CFCONTENT tag to control access to content stored in a non-web-accessible repository.