You can restrict access to your published web services to control the users allowed to invoke them. You can use your web server to control access to the directories containing your web services, or you can use ColdFusion security in the same way that you would to control access to any ColdFusion page.

Controlling access to component CFC files

To browse the HTML description of a CFC file, you request the file by specifying a URL to the file in your browser. By default, ColdFusion secures access to all URLs that directly reference a CFC file, and prompts you to enter a password upon the request. Use the ColdFusion RDS password to view the file.

To disable security on CFC file browsing, use the ColdFusion Administrator to disable the RDS password.

For more information, see Building and Using ColdFusion Components.

Using your web server to control access

Most web servers, including IIS and Apache, implement directory access protection using the basic HTTP authentication mechanism. When a client attempts to access one of the resources under a protected directory, and has not properly authenticated, the web server automatically sends back an authentication challenge, typically an HTTP Error 401 Access Denied error.

In response, the client's browser opens a login prompt containing a user name and password field. When the user submits this information, the browser sends it back to the web server. If authentication passes, the web server allows access to the directory. The browser also caches the authentication data as long as it is open, so subsequent requests automatically include the authentication data.

Web service clients can also pass the user name and password information as part of the request. The cfinvoke tag includes the user name and password attributes that let you pass login information to a web server using HTTP basic authentication. You can include these attributes when invoking a web service, as the following example shows:

<cfinvoke 
    webservice = "http://some.cfc?wsdl"
    returnVariable = "foo"
    ...
    username="aName"
    password="aPassword">
<cfoutput>#foo#</cfoutput>

ColdFusion inserts the user name/password string in the authorization request header as a base64 binary encoded string, with a colon separating the user name and password. This method of passing the user name/password is compatible with the HTTP basic authentication mechanism used by web servers.

The ColdFusion Administrator lets you predefine web services. As part of defining the web service, you can specify the user name and password that ColdFusion includes as part of the request to the web service. Therefore, you do not have to encode this information using the cfinvoke tag. For information on defining a web service in the ColdFusion Administrator, see Configuring web services in the ColdFusion Administrator.

Using ColdFusion to control access

Instead of letting the web server control access to your web services, you can handle the user name/password string in your Application.cfc or Application.cfm file as part of your own security mechanism. In this case, you use the cflogin tag to retrieve the user name/password information from the authorization header, decode the binary string, and extract the user name and password, as the following excerpt from an Application.cfc onRequestStart method shows:

<cflogin>
    <cfset isAuthorized = false>

    <cfif isDefined("cflogin")
        <!--- Verify user name from cflogin.name and password from 
    cflogin.password using your authentication mechanism. --->
        >
        <cfset isAuthorized = true> 
    </cfif>
</cflogin>

<cfif not isAuthorized>
    <!--- If the user does not pass a user name/password, return a 401 error. 
        The browser then prompts the user for a user name/password. --->
    <cfheader statuscode="401">
    <cfheader name="WWW-Authenticate" value="Basic realm=""Test""">
    <cfabort>
</cfif>

This example does not show how to perform user verification. For more information on verification, see Securing Applications.