Using the cfimpersonate Tag

The cfimpersonate tag gives ColdFusion developers a way to execute a segment of code in a secure manner. This tag is useful when you want to briefly grant a type of access that you would normally withhold. Suppose you are an internet service provider (ISP) who hosts ColdFusion development services. You provide a set of custom tags that let your customers add features such as hit counters, guest books, and message boards to the ColdFusion applications they create. To provide this type of functionality, you must also provide access to some resources that you might prefer to protect. Using cfimpersonate provides access to these resources in a safe manner by wrapping the functionality in a custom tag.

For example, as an ISP, you definitely do not want your customers to access the cffile tag on your servers. However, if you provide your customers with a hit counter, you must let them read specific, system-maintained files, in this case, the file that contains number of hits to the customer's home page. You can provide the hit-counter in a custom tag that uses the cffile tag. To ensure that the custom tag can access the cffile tag, it needs a way to impersonate a trusted user while the tag is executing and then to revert back to the nontrusted user after the trusted piece of code executes.

The cfimpersonate tag has the following required attributes:

securitycontext Describes which security context to use for authentication and authorization. This name matches the security context as defined on the Advanced Security page of the ColdFusion Administrator.
username The username of the user to impersonate.
password The password of the user to impersonate.
type Indicates the type of impersonation to implement, CF for application level or OS for operating system level. Application-level impersonation lets you assume the rights assigned to a ColdFusion user by a specified security context. Operating-system-level impersonation lets you assume the rights assigned to a Windows NT user by a specified Windows NT domain. Operating-system-level impersonation is not currently available for UNIX.

In addition, cfimpersonate has one optional attribute:

throwOnFailure Indicates whether ColdFusion throws an exception of type Security if authentication fails. Default is Yes.

Example

The following example reads a protected file because the ColdFusion user pfoley has been granted access to the file by the security context MyContext. If the user cannot be authenticated, ColdFusion throws a Security exception.

<cfimpersonate securitycontext="MyContext"

    username="pfoley"

    password="admin"

    type= "CF"

    throwonfailure= "Yes">



  <cffile file="#readFile#" action="read" variable="text"> 

  <cfoutput>

    The file contains the following text:<br>#text#<br>

  </cfoutput>



</cfimpersonate>

Developing ColdFusion Applications
Application Security