Working with security credentials inside Nintex for Office 365 (RequestDigest, FedAuth, rtFa)
Table of contents:
Recently I started playing around with the Nintex O365 Workflow REST API (http://help.nintex.com/en-us/sdks/sdko365/). Although not everything is possible (as saving new workflows), because web request action does not support passing of binary strings and cuts off null bytes (0x00), so the passed file is found by the API as incorrect BUT first thing I faced during my exercise was: HOW TO OBTAIN FedAuth security cookie?
I read articles, reviewed Stackverflow forums and similar looking for an answer how to achieve it using JavaScript. I was a bit upset with the results but then I found this precious article: Remote authentication in SharePoint Online | … And All That JS and everything went clear on how to obtain the cookie inside Nintex Workflow.
The following post is showing how to obtain 3 important security variables, that SharePoint requires from requester to “trust”:
- fedAuth cookie
- rtFa cookie
- RequestDigest token
Security Cookies
First, the cookies. To get them I must simulate authentication process. The authentication sequence, from Nintex Workflow, should be the following:
- Create a variable holding SAML Request Security Token message:
<s:Envelope xmlns:s="http://www.w3.org/2003/05/soap-envelope" xmlns:a="http://www.w3.org/2005/08/addressing" xmlns:u="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd"> <s:Header> <a:Action s:mustUnderstand="1">http://schemas.xmlsoap.org/ws/2005/02/trust/RST/Issue</a:Action> <a:ReplyTo> <a:Address>http://www.w3.org/2005/08/addressing/anonymous</a:Address> </a:ReplyTo> <a:To s:mustUnderstand="1">https://login.microsoftonline.com/extSTS.srf</a:To> <o:Security s:mustUnderstand="1" xmlns:o="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd"> <o:UsernameToken> <o:Username>[LOGIN]</o:Username> <o:Password>[PASSWORD]</o:Password> </o:UsernameToken> </o:Security> </s:Header> <s:Body> <t:RequestSecurityToken xmlns:t="http://schemas.xmlsoap.org/ws/2005/02/trust"> <wsp:AppliesTo xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy"> <a:EndpointReference> <a:Address>[TENANT ADDRESS]</a:Address> </a:EndpointReference> </wsp:AppliesTo> <t:KeyType>http://schemas.xmlsoap.org/ws/2005/05/identity/NoProofKey</t:KeyType> <t:RequestType>http://schemas.xmlsoap.org/ws/2005/02/trust/Issue</t:RequestType> <t:TokenType>urn:oasis:names:tc:SAML:1.0:assertion</t:TokenType> </t:RequestSecurityToken> </s:Body> </s:Envelope>
Be sure, that you don’t have any new lines in the string, when you paste it to the variable.
Also – replace [LOGIN] and [PASSWORD] with credentials of the user who has enough permissions to execute the method/ operation for which you are obtaining the cookies. For example, if you want them to manipulate data on lists, user has to have permissions for that list.
If you want to call Nintex REST API then user must be at least Site Collection admin and you MUST provide an account from the *@*.onmicrosoft.com domain! - Now we must make a “Web request” POST call to the https://login.microsoftonline.com/extSTS.srf sending my SAML Security Token Message:
Store the response in a text variable. - Now we must extract the Binary Security Token value. We do it using “Query XML” action, and the following regular expression for extraction:
(?<=(\<wsse\:BinarySecurityToken Id\=\"Compact0\"\>))t\=(.+)(?=(\&\;p\=))
- As there is only one element in the collection I then use “Join Items in Collection” action to flatten it so that I have a plain text BinarySecurityToken string.
- Next we must send the token to the SharePoint Online tenant, from which we want to obtain security cookies. We must make a POST Web Request to the address: https://[TENANT ADDRESS]/_forms/default.aspx?apr=1&wa=wsignin1.0 putting Binary Security Token in the request’s body:
- The “Cookie” response header is the 6th element in the collection. Now we must retrieve this string:
- After we do that we must extract FedAuth and rtFa cookies from the string. We must use “Regular Expression” action to extract values. Extracted value must be put in a “collection” variable. Use the following regular expressions for extraction:
- Now I’m again merging the collections, because there are only one elements in each, so that after “Joining items in collection” I get the plain text cookie value.
And that is simply it! fedAuth and rtFa cookies are yours. They look like this (Base64 encoded string):
FedAuth:
77u/PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0idXRmLTgiPz48U1A+VjIsMGguZnxtZW1iZXJzaGlwfDEwMDM3ZmZlOWNjMDg0ZmVAbGl2ZS5jb20sMCMuZnxtZW1iZXJzaGlwfGFkbWluQG1vZDc0Mzc0Ni5vbm1pY3Jvc29mdC5jb20sMTMxMzExMDIzNDEwMDAwMDAwLDEzMTI3NjExNjg5MDAwMDAwMCwxMzEzMTUzNDM3MTM1NjU0NjgsMC4wLjAuMCwyLDM3Nzc5NjFmLWY3YmEtNDY1Ni05ZTA5LTU5ZDk5ZjIwYmU0OSwsVjIhMTAwMzdGRkU5Q0MwODRGRSExMzEzMTEwMjM0MSw3YTQyZDM5ZC0xMGQ0LTMwMDAtYWEwZS1hNDYxYmJhYTgwODksN2E0MmQzOWQtMTBkNC0zMDAwLWFhMGUtYTQ2MWJiYWE4MDg5LGFaV1dJck5MYVFzcE9MMFV5ci9yZ1BXYlEvZmdUNDFCaHlSL1pZUXpYZnQ5Ny9Uei9ZNmovRFZtaUM3Mk80SmxkNithV1RhNVFMb2tIYndmOWZSVHRybjdUM2tqSjFtcjZ6aDlCcDNGajdUUnhJK3V3bG4vZC80M094QVBCL3NHYkUxSlNBbUV3aHgrdCtWNmNhUDUwYUtBa3kvMTROZ096R1pWQUpkbFlBVjlkRUcveXVuN2VvU1ZCazNIbFNTenNKVVY5NFNpekNFVm1ER0JyL3VxcWx0Qlp3bzR0TU5XOUtrSFdXUjcxeExBVW13TjlRQi92cFBFMEhjWFhiZ3VOZHdhVi94Tk44VllaRE9lZFNKVUQ0SitGTTdEZXRwUVJzNVVYYlNSUksxdWJ3Y3F2bVlaNElqZ2tCeW5OUHA0V2RaMnBENmgxUnZQQVF3SkVLK2lsQT09PC9TUD4=
rtFa:
7nXEhB0SmoQCQ0E2wWyjp30PoKW1AwXSpsqBXxJhXCA9QsIhkgcoMisuElVa4vEwr5gU6L+iQolckAAS5Plkqx0Xb6T9LujKOJ9gEpId4fUJRWhlwXczFIHYTNRpoS5TRRhnlriRv9CIXO6iS9WcL6L/elAifHoMkM5iq0leFXOIfRqTVT8c5b0scDkkh/3HzMqyjzwyi+mP4F3LZndD9b5zit7yZUP6xYWiHkox9JhUu2V8J/cNIqdpKLOycXHvXuKbhvpiiR1qys1E+/RPjMLxahiKgs8l3jVKp5HvVDpCSUbm6Jw6iSHiHPbK4z9RkJdj9M3ktdzVKfOIhDDmTUSqWeLB/yrZfVFa1bkv9AcpxlnmHvETlui3nn4sxHAmIAAAAA==
Form Request Digest token
Caroline Jung had already made an article about that on the Nintex Connect forum (How to execute a SP2013 REST API request with Nintex Workflow ) however when it is valid for the current tenant. When trying to get the token from a different tenant security cookies must be included. The process in that case is the following:
- POST “Web request” to the “ContextInfo” of the site for which you want the token: https://[TENANT ADDRESS]/_api/contextinfo including the cookie in the header. It has to have the following structure:
FedAuth={Variable:FedAuth_Cookie};rtFa={Variable:rtFa_Cookie}
Write any string in the “Body” of the request (it is mandatory )
Store the “response content” in a Text variable.
- Then, as Caroline wrote, we the token must be extracted from the received XML. Use this xPath query:
//*[local-name()='FormDigestValue']
and store results in a text variable:
Voilla! Now you have also the Form Request Digest token. It should be similar to the:
0x0E07BB747A8A51DF739E090592B3AADB293A16E73CE9C9D6451B5478B1EEA7514CF7527C890EAB40539C8A49E38C8C92AF73257A3972531E0F566086E12AC01D,09 Feb 2017 08:26:47 -0000
Where can I use them?
Well, especially security tokens can be used when trying to manipulate external tenant’s data from your tenant Nintex Workflow (and for some reason not doing this by “Office 365” set of actions). Or to call methods from Nintex O365 Workflow REST API from within your workflow. Just remember, you always have to combine FedAuth with rtFa as the “Cookie” header value
FedAuth={Variable:FedAuth_Cookie};rtFa={Variable:rtFa_Cookie}
I hope you can make use of this knowledge!
Best regards,
Tomasz