Authenticating the REST API with NintexForms 2013
This topic looks at authentication for SharePoint 2013.
NintexForms 2013 also provides a set of Representational State Transfer (REST) methods with which you can retrieve, publish, and delete forms in SharePoint 2013. As with earlier versions of SharePoint, you must first obtain authentication from SharePoint 2013 before you can invoke the REST methods from Forms 2013. However, SharePoint 2013 provides a set of REST resources for this purpose, so Simple Object Access Protocol (SOAP) implementation is not required.
Retrieving a form digest from SharePoint 2013
You must first obtain a form digest from SharePoint, used to authenticate your Forms 2013 REST method requests. A form digest is a client-side token provided by SharePoint 2013 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 resources 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 resources from other contexts, requiring a separate REST method to retrieve the relevant form digest value.
The contextinfo REST endpoint, provided by SharePoint 2013, returns a new or updated form digest for a specified credential and SharePoint site collection or site. The resource is invoked on the desired SharePoint site collection or site, and the request header includes the credential for which authorization is requested. For more information about the contextinfo REST endpoint in SharePoint 2013, see Complete basic operations using SharePoint 2013 REST endpoints.
The response for the REST endpoint, if successful, contains a serialized ContextWebInformation object. The FormDigestValue scalar property from that object, in turn, contains the form digest value. The form digest value includes the form digest timeout date and time, appended to the form digest value and delimited by a comma (,) character.
Tip: If you need to determine the duration of the form digest value for implementation purposes without parsing the form digest value itself, the FormDigestTimeoutSeconds property from the ContextWebInformation object provides the duration, in seconds, of the form digest value. For more information about the ContextWebInformation object, see Microsoft.SharePoint.Client.ContextWebInformation.
The NintexFormsPublishExample sample implements the contextinfo endpoint in the FormDigest2013 class, derived from the FormDigest class. The sample supports both NintexForms 2010 and NintexForms 2013, and the FormDigest class represents a form digest value.
The following code represents the entirety of the FormDigest2013 class. The constructor for this class uses the contextinfo REST endpoint, constructing a POST request containing the SharePoint site URL and credentials to be used when invoking NintexForms 2013 REST methods. The form digest value is parsed from the element for the FormDigestValue property, from the serialized ContextWebInformation object returned in 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 2013.
/// </summary>
class FormDigest2013 : 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 ContextInfo REST operation,
/// provided by the REST service from SharePoint 2013,
/// to retreive the appropriate form digest value.</remarks>
public FormDigest2013(string webUrl, ICredentials credentials)
{
// Validate input.
if (String.IsNullOrEmpty(webUrl)) return;
// Create the request URL for the specified site URL.
var restRequest = (HttpWebRequest)WebRequest.Create(new Uri(webUrl + "/_api/contextinfo"));
// Configure the request as a REST request.
restRequest.UseDefaultCredentials = false;
restRequest.PreAuthenticate = true;
restRequest.Credentials = credentials;
restRequest.Method = "POST";
restRequest.ContentLength = 0;
// Send the request and parse the value of the form digest from the response.
using (var restResponse = (HttpWebResponse)restRequest.GetResponse())
{
using (var respStream = restResponse.GetResponseStream())
{
if (respStream == null) return;
var doc = XDocument.Parse(new StreamReader(respStream).ReadToEnd());
XNamespace d = "http://schemas.microsoft.com/ado/2007/08/dataservices";
FormDigestValue = doc.Descendants(d + "FormDigestValue").First().Value;
}
}
}
}
Invoking methods from the REST API