Problem

You want to validate usernames and passwords for Salesforce.com against your corporate user database or another client application rather than having separate user passwords managed by Salesforce.com.

Solution

Delegated Authentication

Federated Authentication using SAML

When delegated authentication is enabled, salesforce.com does not validate a user's password. Instead, salesforce.com makes a Web services call to your organization to establish authentication credentials for the user.

Simple passwords

Tokens

Mixed

To enable delegated authentication for your organization, build your delegated authentication Web service, and then configure your Salesforce.com organization to enable the Web service.

1. In Salesforce.com, click Setup | Develop | API | Download Delegated Authentication WSDL to download the Web Services Description Language (WSDL) file, AuthenticationService.wsdl.

   The WSDL describes the delegated authentication service and can be used to automatically generate a server-side stub to which you can add your specific implementation. For example, in the WSDL2Java tool from Apache Axis, you can use the --server-side switch. In the wsdl.exe tool from .NET, you can use the /server switch.

   A simple C# implementation of delegated authentication is shown below. The sample uses Microsoft .NET v1.1 and works with IIS6 on a Windows 2003 server. See wiki.developerforce.com/index.php/How_to_Implement_Single_Sign-On_with_Force.com for a more complex sample that demonstrates a solution using an authentication token.

   using System;
   using System.DirectoryServices;
   
   namespace samples.sforce.com
   {
   	/// <summary>  
       
   	/// This is a very basic implemention of an  
       
   	/// authentication service for illustration purposes.  
       
   	/// This sample should only be used  
       
   	/// with a HTTPS Delegated Gateway URL.  
       
   	/// It simply connects to your Active Directory  
       
   	/// server using the credentials that are passed in.  
       
   	/// If there is a bad username/password combination,  
       
   	/// it throws an exception and returns false;  
       
   	/// otherwise the credentials are ok  
       
   	/// and it returns true.  
       
   	/// Note that DirectoryEntry might not connect to  
       
   	/// Active Directory until we do something  
       
   	/// that actually requires it.  
       
   	/// That's why we read a property from the  
       
   	/// created DirectoryEntry object.  
       
   	/// </summary>  
       
   	public class SimpleAdAuth : System.Web.Services.WebService
   	{
   		[System.Web.Services.WebMethodAttribute()]
   		[System.Web.Services.Protocols.SoapDocumentMethodAttribute(
   			"",
   			RequestNamespace = "urn:authentication.soap.sforce.com",
   			ResponseElementName = "AuthenticateResult",
   			ResponseNamespace = "urn:authentication.soap.sforce.com",
   			Use = System.Web.Services.Description.SoapBindingUse.Literal,
   			ParameterStyle = System.Web.Services.Protocols.SoapParameterStyle.Wrapped)]
   		[return: System.Xml.Serialization.XmlElementAttribute("Authenticated")]
   		public bool Authenticate (
   			string username, string password, string sourceIp,
   			[System.Xml.Serialization.XmlAnyElementAttribute()] 
   				System.Xml.XmlElement[] Any)
   		{
   			if(username.IndexOf("@")==-1)
   				return false;
   
   			// Attempt to bind to an Active Directory entry.  
       
   			// This will authenticate the username and password.  
       
   			// TODO: you'll need to change this to match  
       
   			// your Active Directory name  
       
   			const string root = "LDAP://DC=sample,DC=org";
   			try
   			{
   				DirectoryEntry de
   					 = new DirectoryEntry(root, username, password);
   				// retrieve a property  
       
   				string tempName = de.Name;
   				return true;
   			}
   			catch(Exception)
   			{
   				return false;
   			}
   		}
   	}
   }
   

   As part of the delegated authentication process, a salesforce.com server makes a SOAP 1.1 request to authenticate the user who is passing in the credentials. An example of this type of request is shown below.

   <?xml version="1.0" encoding="UTF-8" ?> 
   <soapenv:Envelope 
   xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"> 
    <soapenv:Body> 
      <Authenticate xmlns="urn:authentication.soap.sforce.com"> 
        <username>sampleuser@sample.org</username>  
        <password>myPassword99</password>  
        <sourceIp>1.2.3.4</sourceIp>  
      </Authenticate> 
    </soapenv:Body> 
   </soapenv:Envelope>
   

   Your delegated authentication service needs to accept this request, process it, and return a true or false response. A sample response is shown below.

   <?xml version="1.0" encoding="UTF-8"?> 
   <soapenv:Envelope 
   xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"> 
   <soapenv:Body> 
    <AuthenticateResponse 
   xmlns="urn:authentication.soap.sforce.com"> 
     <Authenticated>true</Authenticated> 
    </AuthenticateResponse> 
   </soapenv:Body> 
   </soapenv:Envelope>
2. Add a link to your corporate intranet or other internally-accessible site that takes the authenticated user’s credentials and passes them using an HTTPS POST to the Salesforce.com login page. For security reasons, you should make your service available by SSL only. This ensures that a password, if it is included, is not sent unencrypted. You must use an SSL certificate from a trusted provider, such as Verisign or Thawte.

   Because Salesforce.com does not use the password field other than to pass it back to you, you do not need to send a password in this field. Instead, you could pass another authentication token, such as a Kerberos Ticket, so that your actual corporate passwords are not passed to or from Salesforce.com.

   You can configure the Salesforce.com-delegated authentication authority to allow only tokens, or to accept either tokens or passwords. If the authority only accepts tokens, a Salesforce.com user cannot log in to Salesforce.com directly, because they cannot create a valid token; however, many companies choose to allow both tokens and passwords. In this environment, a user can still log in to Salesforce.com through the login page.

   When the salesforce.com server passes these credentials back to you in the Authenticate message, verify them, and the user will gain access to the application.

• 80: This port only accepts HTTP connections.
• 443: This port only accepts HTTPS connections.
• 7000-10000 (inclusive): These ports accept HTTP or HTTPS connections.

Finally, modify your user profiles to enable the Is Single Sign-On Enabled user permission. In Salesforce.com, click Setup | Manage Users | Profiles to add or edit profiles.

Discussion

The actual implementation of delegated authentication is transparent to users, but involves a number of steps behind the scenes. When you configure Salesforce.com for delegated authentication, you are allowing a delegated authority to control authentication. When a user first logs onto their network environment, they are initially authenticated by this authority. When the user attempts to log on to subsequent protected applications, instead of passing a username and password to the application, the user requests a token from a token generator. (On Windows, this token request can use the NTLM protocol.) The received token is passed to the application, which verifies that the token properly identifies the user, and then allows the user access to the application.

Salesforce.com can use this method, since the password field is simply used to exchange information with the client, rather than specifying a particular data type. This flexibility means that Salesforce.com can accept a token, which is then used with the delegated authentication authority to verify the user. If the verification succeeds, the user is logged on to Salesforce.com. If the verification fails, the user receives an error. The process flow for Salesforce.com delegated authentication is shown in the figure below.