Specifying Connections and Credentials for the ReportViewer Web Server Control

To specify a connection from the ReportViewer control to the report server, it helps to know the conditions under which connections are made.

  • At start up when the Web page that contains the ReportViewer control is loaded, the control connects to the report server to establish the report session, get or set report parameter properties, and retrieve the list of rendering extensions that are available on the server.

  • If the control is running with AsyncRendering=true, the HTML for the report is retrieved asynchronously by an IFrame object after the page is rendered.

  • If the report references an external image, the ReportViewer control retrieves the images through separate requests using the ReportViewer HTTP handler, where each request is made under its own connection.

  • After the report is rendered, additional connections can occur if you export a rendered report to a different format. An export request is sent from the browser to the report server using a separate connection.

The success of all of these operations depends on whether the ReportViewer control has valid connection information to the report server. How you specify connection information will vary depending on factors such as whether you are using forms authentication, Windows Authentication, credentials of the current user, or ASP.NET session.

To connect to the server, you can set properties on the ServerReport object or implement interfaces that set the connection and then specify the implementation in the Web.config file. The ReportViewer control always reads the Web.config file first and uses the connection values if they are specified.

If session state is enabled, you can choose whether to set properties on the ServerReport object or specify connection information in the Web.config file. If you specify connection information in Web.config, do not set properties on the ServerReport object.

If session state is turned off, you must implement IReportServerConnection or IReportServerConnection2 and specify the implementation in the Web.config file.

Note Note

The user account under which the connection is made must have a valid role assignment on the report server. Both system and item level role assignments are used to create a comprehensive set of permissions. If you are not familiar with report server role assignments, you can follow a tutorial to learn role assignment fundamentals. For more information, see Tutorial: Setting Permissions in Reporting Services on MSDN.

You can set the report server URL and timeout properties on the ServerReport object when you drag the control onto a Web form at design time.

By default, the ReportViewer Web server control connects to the report server as the ASP.NET thread user.

To connect as a different user (for example, if you want all users to connect to a report server under a single user account), implement IReportServerCredentials on a serializable object and pass an instance of that object to ReportViewer.ServerReport.ReportServerCredentials. Because the ReportViewer control can connect to the report server after the ASP.NET page has finished processing, your object must be serializable for storage if ASP.NET session is stored out of process (for example, in a SQL Server database).

Note that there are two disadvantages to setting the ReportViewer.ServerReport.ReportServerCredentials property directly:

  • ASP.NET session must be enabled.

  • ASP.NET session can become unnecessarily large because the ReportViewer control places an instance of the object in session for each user viewing the page.

You can avoid the above disadvantages by specifying an implementation of IReportServerConnection2 in the Web.config file.

For recommendations on how to specify credentials if session state is turned off, see Guidelines for Storing Credentials if ASP.NET Session is Turned Off in this topic.

When implementing IReportServerConnection or IReportServerConnection2 you must specify your implementation in the application Web.config file. The Web.config file provides the object type that contains connection and credential information.

Note Note

You must specify an implementation of IReportServerConnection2 or IReportServerConnection, and not IReportServerCredentials in the Web.config file. IReportServerConnection2 is derived from IReportServerCredentials and adds additional properties for specifying a report server URL, time-out value, and any custom cookies or HTTP headers that you want to use.

Although IReportServerConnection2 is required if ASP.NET session is turned off, you can use it with ASP.NET session turned on if you want to avoid storing objects in session. For more information and a code example, see the programming reference topic for IReportServerConnection2. For more information about how to add keys in Web.config, see Web.config Settings for ReportViewer.

The following table summarizes the interfaces that provide credentials and connection information.




You can use this interface to specify the credentials that the ServerReport object uses to connect to the report server if you do not want to connect as the current user.

By default, the ReportViewer control connects to the report server as the ASP.NET thread user.

You can specify a different user by setting ReportViewer.ServerReport.ReportServerCredentials to an instance of your own implementation of IReportServerCredentials.


This interface inherits from IReportServerCredentials and provides additional members for specifying the report server URL and time-out properties.


This interface inherits from IReportServerConnection and provides additional members for specifying custom cookies or headers, which is useful if you are using a single sign-on product with your report server.

When implementing IReportServerConnection2, do not store user credentials in the class. If you store credentials in a serializable object, the user name and password will be serialized to the ASP.NET session and stored in a SQL Server database or another state server. While serializing the credentials is not necessarily a security risk, it does increase the surface area of attack by storing credentials as session data.

The following approaches are examples of how to avoid storing credentials alongside other session data:

  • Read stored credentials from a configuration file or some other configuration store. For more information and a code example, see the programming reference topic for IReportServerCredentials.

  • Read an HTTP cookie from the ASP.NET request to provide credentials that vary based on the client.

Note Note

Although you have flexibility in choosing how to store credentials outside of the class, you must ensure that the same credentials are returned for subsequent requests in the same report session.