If you want your .NET 4.5 applications to connect to the Salesforce REST API, then you can use the newly released Force.com Toolkit for .NET. The toolkit currently supports two OAuth 2.0 web server authentication flows: Username-Password and Web-Server.
The Username-Password flow requires that your .NET application manage and protect user credentials. The Force.com documentation recommends that you only use this flow in situations where a user cannot enter these credentials themselves. Therefore it is best suited for highly privileged or proof of concept applications.
The web-server flow, which is what most web applications will use, allows users to enter their own credentials, but does require the application to manage and store the consumer key and secret for a Force.com Connected App. This article will examine some of the sample code from an MVC 5 application that uses the web-server flow to authenticate users.
How does the OAuth 2.0 Web-Server Flow Work?
The web-server authentication flow will obtain an access token on behalf of the user and grant the client application an authorization code. The client application will only have access to areas of Force.com that were configured when setting up a Connected App.
The process begins when the user requests some service from the application (see Figure 1). The user will be redirected to a Salesforce Authorization endpoint (login.salesforce.com) and asked to enter their credentials. Once they are logged in, the user is asked whether they want to grant access to the client. If they approve, then the client application is sent an authorization code. The approved client application can now use the token to make data requests to the resource server (na1.Salesforce.com).
The important thing to remember is that the client application never has access to the user’s credentials. This is what makes the web-server flow so attractive. However, the client application will still have access to the consumer key and secret for the connected app, so they must store these values as securely as possible.
Figure 1: Diagram depicting the Web-Server Authentication Flow (Image available at https://developer.salesforce.com/page/File:OAuthWebServerFlow.png)
Setting up a Connected App
Before downloading the sample application, you will need to create and configure a new Connected App in your Sandbox or Developer org. From Setup, this is done by clicking Create | Apps and New. Make sure you select the Enable OAuth Settings checkbox (see Figure 2) and that you enter the following callback URL: http://localhost:6054/api/callback. This URL must match the one already specified in the web.config file for the sample application. You will also need to add an oAuth scope, which specifies the access that will be granted. For this sample, you can just grant full access, but most real-world applications should use a more restrictive access scope.
Figure 2: Connected App settings for WebServerOAuthFlow sample application
Downloading and Configuring the Sample Application
The WebServerOAuthFlow sample application is available for download from the samples area of the Force.com Toolkit GitHub Repository. Once downloaded, you will need to open up the Visual Studio 2013 solution and make changes to the Web.config file. You only need to enter values for the ConsumerKey and ConsumerSecret app settings. But, if your connected app was created in a Sandbox environment, you will also need to change the first part of the URL in the AuthorizationEndpointUrl and TokenRequestEndpointUrl settings. By default, these are set to login.salesforce.com, but if authenticating to a sandbox, they must be changed to test.salesforce.com.
The sample application already has the necessary NuGet packages installed, but if you are using an Express version of Visual Studio 2013, then you may need to update the client version of NuGet. The DeveloperForce.com Toolkit requires NuGet client version 2.8.1 or above and this can be updated by going to Project | Manage NuGet Packages and selecting Updates and Update All Packages.
Running the Sample Application
Make sure the solution builds successfully by right-clicking the solution in Solution Explorer and clicking Rebuild Solution. Hit F5 to start debugging. Once loaded the sample application will provide you with a link to Login to Salesforce. Click the link and you should be redirected to the Salesforce login page. Enter the credentials used to create the connected app and click the Log in to Salesforce button.
The first time you execute the app, you will be brought to a page that asks you whether you want to approve or deny the requested access (see Figure 3). Click Allow to be brought back to the home page for the client application. This page displays the access token, api version and instance url returned from the authentication process. These values will be used for any additional requests the application makes, such as clicking the link to Get Accounts.
Figure 3: Page to grant authorization to the WebServerOAuthFlow sample application
The next time you execute the application, you will not need to grant access. This should only be done once. If there is ever a need to deny access to the client application, the user can simply log in to their org and from Setup, go to Manage Apps and Connected Apps OAuth Usage. From here they can block access by clicking the Block button next to the connected app.
Exploring the Sample Code
To examine the code used for the login process, open the HomeController.cs file in the Controllers folder. The login() method is initiated when the user clicks the first Login link. The method contains code used to format a url with the authorization endpoint url, consumer key, and callback url. It then redirects the user to that url, as seen below:
Once the user enters their credentials and grants the application access, they are redirected back to the callback url and the following code from the CallbackController.cs file is executed:
In this code, the access token and other values that were returned from the WebServerAsync call are extracted and passed back to the calling page as url parameters. They will then be stored in the ViewBag and used when performing additional queries.
The OAuth 2.0 Web-Server authentication flow offers a simple but secure solution for authorizing remote applications that does not require the client application to store a users login credentials. The Force.com Toolkit provides an easy way to incorporate this type of authentication into your .NET 4.5 applications. The sample application provided with the toolkit should give application developers a good starting point for building their own oAuth secured applications.