Authenticating the REST API with SharePoint 2010
This topic looks at authentication for SharePoint 2010.
Nintex Forms 2010 provides a set of Representational State Transfer (REST) methods with which you can retrieve, publish, and delete forms in SharePoint 2010. However, SharePoint 2010 only implements Simple Object Access Protocol (SOAP) service operations, and so you must first invoke a SOAP service operation from SharePoint 2010 to obtain authentication before you can invoke the REST methods from Forms 2010.
Retrieving a form digest from SharePoint 2010
You must first obtain a form digest from SharePoint, used to authenticate your Forms 2010 REST method requests. A form digest is a client-side token provided by SharePoint 2010 that authenticates a credential to perform operations on a specific SharePoint site collection or site. The form digest remains valid for a limited time, depending on how SharePoint is configured.
Obtaining a form digest value is relatively easy when invoking service operations from a SharePoint context, such as a SharePoint webpage, because the value is automatically available within the context and easily accessible from JavaScript code. Obtaining a form digest value is a bit more complex when invoking service operations from other contexts, requiring a separate SOAP service operation to retrieve the relevant form digest value.
The GetUpdatedFormDigest SOAP service operation, provided by the Sites web service included with Windows SharePoint Services (WSS) 3.0 in SharePoint 2010, returns a new or updated form digest for a specified credential and SharePoint site collection or site. The service operation is invoked on the desired SharePoint site collection or site, and the SOAP envelope includes the credential for which authorization is requested. For more information about the GetUpdatedFormDigest service operation in SharePoint 2010, see Sites.GetUpdatedFormDigest Method.
The body of the SOAP envelope returned by the service operation, if successful, contains the form digest value in the GetUpdatedFormDigestResult element. The form digest value includes the form digest timeout date and time, appended to the form digest value and delimited by a comma (,) character.
The NintexFormsPublishExample sample implements the GetUpdatedFormDigest service operation in the FormDigest2010 class, derived from the FormDigest class. The sample supports both Nintex Forms 2010 and Nintex Forms 2013, and the FormDigest class represents a form digest value.
The following code represents the entirety of the FormDigest2010 class. The constructor for this class invokes the GetUpdatedFormDigest service operation, constructing a SOAP request envelope that contains the SharePoint site URL and credentials to be used when invoking Nintex Forms 2010 REST methods. The form digest value is parsed from the response, and stored by the class so that the sample can use it when invoking the REST methods.
/// <summary>
/// Represents the form digest for the Nintex Forms service endpoint on SharePoint 2010.
/// </summary>
class FormDigest2010 : FormDigest
{
/// <summary>
/// Creates a new instance for the specified URL and credentials.
/// </summary>
/// <param name="webUrl">The URL of the SharePoint site.</param>
/// <param name="credentials">The credentials to use.</param>
/// <remarks>The class invokes the GetUpdatedFormDigest SOAP method,
/// provided by the Sites service from SharePoint 2010,
/// to retreive the appropriate form digest value.</remarks>
public FormDigest2010(string webUrl, ICredentials credentials)
{
// The SOAP envelope used to get an updated form digest from the Nintex Forms service endpoint.
const string body = "<?xml version='1.0' encoding='utf-8'?>"
+ "<soap:Envelope xmlns:soap='http://schemas.xmlsoap.org/soap/envelope/' "
+ "xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance' xmlns:xsd='http://www.w3.org/2001/XMLSchema'>"
+ "<soap:Body>"
+ "<GetUpdatedFormDigest xmlns='http://schemas.microsoft.com/sharepoint/soap/' />"
+ "</soap:Body>"
+ "</soap:Envelope>";
// Validate input.
if (String.IsNullOrEmpty(webUrl)) return;
// Create the request URL for the specified site URL.
var soapRequest = (HttpWebRequest) WebRequest.Create(new Uri(webUrl + "/_vti_bin/sites.asmx"));
// Configure the request as a SOAP action.
soapRequest.Headers.Add("SOAPAction", "http://schemas.microsoft.com/sharepoint/soap/GetUpdatedFormDigest");
soapRequest.UseDefaultCredentials = false;
soapRequest.PreAuthenticate = true;
soapRequest.Credentials = credentials;
soapRequest.ContentType = "text/xml;charset=\"utf-8\"";
soapRequest.Accept = "text/xml";
soapRequest.Method = "POST";
// Encode and write the SOAP envelope into the request stream.
Stream stream = soapRequest.GetRequestStream();
byte[] byteArray = Encoding.UTF8.GetBytes(body);
stream.Write(byteArray, 0, byteArray.Length);
stream.Close();
// Send the request and parse the value of the form digest from the response.
using (var restResponse = (HttpWebResponse)soapRequest.GetResponse())
{
using (var respStream = restResponse.GetResponseStream())
{
if (respStream == null) return;
var doc = XDocument.Parse(new StreamReader(respStream).ReadToEnd());
XNamespace ns1 = "http://schemas.microsoft.com/sharepoint/soap/";
FormDigestValue = doc.Descendants(ns1 + "GetUpdatedFormDigestResult").First().Value;
}
}
}
}
Invoking methods from the REST API