Authentication and authorization
The Nintex Workflow for Office 365 REST API requires that you have both a subscription to the REST API and authorization to use the REST API on a specified SharePoint site.
Note: You need to request your API key from Nintex. The API key authorizes you to invoke the REST resources included with the REST API. Contact your Nintex representative to request an API key for the REST API.
Authenticating operations for SharePoint Online
The Nintex Workflow for Office 365 REST API takes advantage of Office 365 passive authentication capabilities, using SharePoint Online credentials and Windows Azure Active Directory to authorize an operation on a specified SharePoint site. An authorization cookie, retrieved from SharePoint Online, that represents a valid credential for the specified site must be provided to authorize the invocation of operations included with the REST API.
You must include the Authorization request header with every operation. The request header must contain a cookie that uses the following format, replacing <site> with the SharePoint site URL and <authcookie> with a valid SharePoint SPOIDCRL or FedAuth authentication cookie for the specified site, as needed, to authenticate the request with SharePoint.
cookie <site> <authcookie>
Required SharePoint permissions
Before retrieving an authentication cookie, ensure that the credential to be used for the specified SharePoint site has the ability to perform all administration tasks for the Web site and manage website content. In other words, the credential must belong to a role in SharePoint that has the Manage Web permission for the specified SharePoint site; otherwise, an error occurs when the authentication cookie is used to invoke a REST API operation.
Obtaining an authentication cookie
You can use the GetAuthenticationCookie operation of the SharePointOnlineCredentials object, in the Microsoft.SharePoint.Client namespace, to obtain a SPOIDCRL authentication cookie for use with the Nintex Workflow for Office 365 REST API.
The Microsoft.SharePoint.Client namespace is included with the SharePoint Online Client Side Object Model (CSOM). You can add a reference to the SharePoint Online CSOM to your Visual Studio 2013 project as a NuGet package, provided by the Office Developer Platform Team on NuGet.
Visual C#
The following Visual C# method demonstrates how to use the GetAuthenticationCookie method to get an authentication cookie for a specified SharePoint site, using a specified username and password.
/// <summary>
/// Gets a SharePoint Online authentication cookie from the specified site, using
/// the specified username and password.
/// </summary>
/// <param name="siteUrl">The site with which to authenticate.</param>
/// <param name="username">The username of the credentials to authenticate.</param>
/// <param name="password">The password of the credentials to authenticate.</param>
/// <returns>If successful, a SharePoint Online authentication cookie;
/// otherwise, an empty string.</returns>
static public string GetSPOCookie(string siteUrl, string username, string password)
{
// If successful, this variable contains an authentication cookie;
// otherwise, an empty string.
string result = String.Empty;
try
{
// Construct a secure string from the provided password.
// NOTE: For sample purposes only.
var securePassword = new SecureString();
foreach (char c in password) { securePassword.AppendChar(c); }
// Instantiate a new SharePointOnlineCredentials object, using the
// specified username and password.
var spoCredential = new SharePointOnlineCredentials(username, securePassword);
// If successful, try to authenticate the credentials for the
// specified site.
if (spoCredential == null)
{
// Credentials could not be created.
result = String.Empty;
}
else
{
// Credentials exist, so attempt to get the authentication cookie
// from the specified site.
result = spoCredential.GetAuthenticationCookie(new Uri(siteUrl));
}
}
catch (Exception ex)
{
// An exception occurred while either creating the credentials or
// getting an authentication cookie from the specified site.
Console.WriteLine(ex.ToString());
result = String.Empty;
}
// Return the result.
return result;
}
Windows PowerShell
The following Windows PowerShell script example demonstrates how to use the GetAuthenticationCookie method to get an authentication cookie for a specified SharePoint site, using a specified credential. The PSCredential object can provides an interactive interface, if needed, in which a credential can be supplied by the user, or you can pipe a valid PSCredential object directly to the Windows PowerShell script at invocation.
<#
.SYNOPSIS
Retrieves a SharePoint Online authentication cookie for the specified SharePoint URI and credential.
.DESCRIPTION
.PARAMETER SiteURI
Required. A System.Uri object that represents the SharePoint site for the authentication cookie.
.PARAMETER Credential
Required. A PSCredential object that represents the credential for the authentication cookie.
.EXAMPLE
Get-SPOCookie -SiteURI "https://crestan.sharepoint.com" -Credential "spowner@crestan.com"
#>
[CmdletBinding()]
param (
[Parameter(Mandatory=$true)]
[System.Uri]$SiteURI,
[Parameter(Mandatory=$true)]
[PSCredential]$Credential
)
# Load the SharePoint client assemblies into the PowerShell session.
# If needed, change the paths to match the location of the SharePoint 2013 client assemblies. The paths provided
# below are the default locations for the SharePoint 2013 client assemblies.
Add-Type -Path "C:\Program Files\Common Files\Microsoft Shared\Web Server Extensions\15\ISAPI\Microsoft.SharePoint.Client.dll"
Add-Type -Path "C:\Program Files\Common Files\Microsoft Shared\Web Server Extensions\15\ISAPI\Microsoft.SharePoint.Client.Runtime.dll"
# Create a new SharePointOnlineCredentials object, using the specified credential.
$SPOCred = New-Object -TypeName Microsoft.SharePoint.Client.SharePointOnlineCredentials -ArgumentList $Credential.UserName, $Credential.Password
# Return the authentication cookie from the SharePointOnlineCredentials object,
# using the specified SharePoint site.
$SPOCred.GetAuthenticationCookie($SiteURI)
Authorizing operations for the Nintex Workflow for Office 365 REST API
The Nintex Workflow for Office 365 REST API requires an API key, issued by Nintex, to authorize the invocation of operations included in the REST API. You must include the API key in the Api-Key request header included with every operation.
Obtaining an API key
You need to request your API key from Nintex. The API key authorizes you to invoke the REST resources included with the REST API. Contact your Nintex representative to request an API key for the REST API.