Calling web services in Nintex Workflow and different authentication mechanisms


With the rise of claims based authentication in SharePoint we’ve faced new challenges in how to interact with web services hosted on those environments. Claims based authentication allows many different scenario’s with a mixture of Windows, Forms and SAML Authentication.

image

When you’re working with Nintex Workflow you’re faced with authentication in Actions such as “Call Web Service” or “Web Request”.

If you’re just using Windows Authentication (NTLM, Kerberos, Basic) on your site then Nintex will handle that authentication just fine for you and use the credentials you specified (manually entered or stored credentials).

imageimage

However you might have to deal with different or multiple authentication mechanisms such as Forms Based Authentication, ADFS or a combination. In such cases you’ll get a 403 FORBIDDEN regardless of the credentials you enter.

image

Overcoming this hurdle can be challenging.

  1. Use a different URL zone (with windows authentication) to make the call
  2. Pass an authentication cookie along with the request

Use a different URL zone (with windows authentication) to make the call

Nintex Actions execute on the server, not on your -already authenticated- client. The connection information you’ve entered (URL, username, password) is used to construct a connection and execute the operation. Since the Action executes locally on the server it can make use of a different URL to do the call. It is a best practice/requirement to have the Default Zone of your Web Application configured with -just- Windows Authentication in order to get things like Search to work properly. Why not make use of this and use that URL in your Actions?

imageimage

Define a set of credentials that can be used in “Call web service” or “Web Request” Actions and have it execute against the URL that has Windows Authentication. If this option is available to you it probably is the preferred way of working.

Pass an authentication cookie along with the request

If the above is no option for you things get trickier and “specific”, meaning it is specific to a certain scenario but might not be possible for yours.

In MY case I have a SharePoint 2013 on-prem environment with “mixed” authentication (Windows and Forms Based). SharePoint issues a FedAuth cookie when the user successfully authenticates. If you send this cookie along with the web request it will work just fine. Note that the “Call web service” action does NOT allow you to specify additional headers so the “Web Request” Action becomes your new best friend here.

Using the “Web Request” Actions allows for much more flexibility, but you’ll have to build the request message yourself. I our case that means the SOAP message.

image

Once you have all of that in place the “Web Request” will happily call out to the web service. See it here working with the FedAuth cookie I “borrowed”.

imageimage

Getting the FedAuth cookie

The base premise is that you need to ‘replay’ the authentication mechanism in code to get the FedAuth cookie. Once you have this you can send it along with future requests from Nintex Workflow. Again this is really specific to my case and may not be possible for you because of additional security or complex authentication schemes.

For my SharePoint 2013 on-prem environment with “mixed” authentication (Windows and Forms Based) I force the call to do Windows Authentication:

public static class AuthHelper
{
    public static Cookie GetFedAuthCookie(Uri uri, ICredentials credentials)
    {
        Cookie result = null;

        // Emulate the authentication via a request to the /_windows/default.aspx page using the provided credentials
        HttpWebRequest request = WebRequest.Create(uri.GetLeftPart(UriPartial.Authority) + "/_windows/default.aspx?ReturnUrl=%2f_layouts%2fAuthenticate.aspx%3fSource%3d%252FDefault%252Easpx&Source=%2FDefault.aspx") as HttpWebRequest;
        request.Credentials = credentials ?? CredentialCache.DefaultNetworkCredentials;
        request.Method = "GET";
        request.CookieContainer = new CookieContainer();
        request.AllowAutoRedirect = false;

        // Execute the HTTP request 
        HttpWebResponse response = request.GetResponse() as HttpWebResponse;
        if (null != response)
        {
            result = response.Cookies["FedAuth"];
        }

        return result;
    }
}

I actually made this available as a Web Service so that it can be called from with a Nintex Workflow.

public class AuthService : IAuthService
{
    public string GetFedAuthCookie(string requestUrl, string userName, string password)
    {
        string result = null;

        try
        {
            NetworkCredential credential = !String.IsNullOrEmpty(userName) ? new NetworkCredential(userName, password) : null;
            Cookie cookie = AuthHelper.GetFedAuthCookie(new Uri(requestUrl), credential);

            if (cookie != null)
            {
                result = cookie.Value;
            }
        }
        catch (Exception ex)
        {
            result = null;
        }

        return result;
    }
 }

And now I can call my Authentication service prior to the other services.

image

Door #3

It feels like it must be possible to use access tokens that can be passed along similar to the FedAuth cookie. Considering this is how the App model works in SharePoint 2013, there has to be a way to leverage this for what we’re trying to accomplish. But that’s for another post.

 


Links to this post

Comments

Monday, 1 Dec 2014 08:08 by Gord
Hi Steve, Very good post. I am trying to do something very similar, except I cannot use the _windows path like you indicated. Long story short, I can capture the FedAuth token. I am trying the PageRequest action in Nintex and get it to work on a non-ADFS site without any issues. My problem is that when I try to get it to work with the ADFS site it fails and tells me: "Unexpected error occurred while making the request." I am passing in a valid FedAuth token that was generated just seconds earlier before I test. I try with/without the username/password filled out. I have also tried including more of the cookie like when it expires etc (and with just the value). Nothing works where I can get connected. I am generating the token from another machine, that is the only thing that I can think of that might be causing the issue. That or maybe I am using the wrong syntax for adding the header. For that, I set Name to "Cookie" and for Value it is: FedAuth=77u/PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0idXRmLTgiPz48U1A+MGUudHxhZGZzMjB8dmVuZG9yX2htYXJ0aW5AdGV4YXNyb2FkaG91c2UubG9jYWwsMGUudHxhZGZzMjB8dmVuZG9yX2htYXJ0aW5AdGV4YXNyb2FkaG91c2UubG9jYWwsMTMwNjIzMjE4ODY5MzYyMDM4LFRydWUsVWx2YXljbjdDQXVoMkxXaHNPRkF6TmQ1N1I3d3RPUTNMY2tHOUs0RXhGNkh4eG5YSUo4c0pGNkJzWG90czRiL2lzazdndmQ0NzJLV0NkOEpIRWZlMi9sOEhZcUxWbkZ2cm9YMkN0WkI4cGJPbXlrWjZBb0RQemdEUnRuTkZJbE9mTW55aUk4LzN4RVlQdE0rWG5RYy8yVEgrNkwrb3pGUHVQZ1NHWktYWWZXL2N0dElnc1Mvc2EySWpFNytFYW5UdXJlV2EwZzRGRXlVR01Idy80cHordVN0cVkvU3hacGtodWFKdzIraXM0WWFVMlM4VmM1RTFneDhNVDg3Z1pqQVljbE45SzVFVTljeld3c3I4SnBhY0x1a0t2QnE4QWxXTTh3ZGZZNG5pd0hXcFdpeGN2Q2psU2RJWjZaZjBqem9qSjhIS0N6dlBiUmZwYm1UQjU2R2VnPT0saHR0cHM6Ly9kZXZ0ZWFtcy50ZXhhc3JvYWRob3VzZS5jb20vPC9TUD4= Any thoughts/help would be greatly appreciated. Regards, Gord

Thursday, 4 Dec 2014 11:35 by Steven Van de Craen
Gord, I've sent you an email as follow up. Kind regards, Steven

Wednesday, 22 Feb 2017 08:59 by Pooja
Hi .. Thanks for writing this blog. It was very useful. Do you know if we can call the Nintex SOAP service from outsite or not ?

Wednesday, 22 Feb 2017 09:04 by Steven Van de Craen
Hi Pooja, that depends on whether the environment running Nintex is accessible from outside? Also additional security such as a firewall or 2FA may make it difficult to consume the web service over the internet, but in many cases it may work.

Tuesday, 7 Mar 2017 10:25 by Andy
Hi Steve, great post! Iti is very useful. One question in which package is the interface IAuthService. I cannot find the namespace....

Tuesday, 7 Mar 2017 11:09 by Steven Van de Craen
Hi Andy, thanks! IAuthService is the WCF Service interface for that method. You can easily create it yourself using the method definition of "string GetFedAuthCookie(string requestUrl, string userName, string password)"

Tuesday, 25 Apr 2017 04:35 by Tapas
Hi Steven, It is a nice post, I have a similar kind of issue where a site uses OKTA for SSO and due to that Nintex response a 403 forbidden error when I try to call a web service. I need to use AddUserToGroup method to add some user to a particular group is there any alternate that I can use for this?

Tuesday, 25 Apr 2017 06:10 by Steven Van de Craen
Hi Tapas, You can test this by logging in into the browser, getting the FedAuth cookie value using Fiddler and using that inside your code. But generally I think this should work. Is this for Office 365 (SharePoint Online) or an on-premises environment?

Tuesday, 16 May 2017 08:05 by Yogesh B.
Awesome post. I was looking for this functionality for a log time !!

CAPTCHA Image Validation