Authentication of external requests

Introduction

All external requests to Creatio web services must be authenticated.

We have the following authentication types in Creatio:

• Anonymous authentication
• Basic authentication
• Forms authentication (Cookie based)

The “Forms authentication” is a best practice for integration with the application.

To perform the “Forms authentication”, Creatio uses a separate “AuthService.svc” web service.

Starting with version 7.10, authentication is protected from CSRF attacks.

You need to perform authentication using the “AuthService.svc” service when integrating with third party applications. After you successfully authenticate, AuthService returns the authentic cookie that must be added to your request. It also returns a cookie containing the CSRF token. This token must be placed in the request header. You can find examples of an authentic cookie below and in the "Integration via OData protocol" and "DataService” articles.

AuthService.svc request

POST /ServiceModel/AuthService.svc/Login HTTP/1.1
Host: http://myserver.com/CreatioWebApp
Content-Type: application/json
ForceUseSession: true
{
 "UserName":"Supervisor",
 "UserPassword":"Supervisor"
}

Web service request structure:

• query string;
• request headers;
• request body.

Query string

To perform authentication, call the “Login “ AuthService.svc. method.

Query string structure

http(s)://[Creatio application address]/ServiceModel/AuthService.svc/Login

Example of a query string

https://myserver.com/CreatioWebApp/ServiceModel/AuthService.svc/Login

Request headers

Content-Type

Content-Type: application/json

Encoding and resource type passed in the request body.

---

ForceUseSession

ForceUseSession: true

The “ForceUseSession” header accounts for using the existing session.

---

Request body

The request body must pass the Creatio user credentials. The credentials are passed as a JSON object.

Properties of the JSON object with credentials

UserName

The user name of a Creatio user.

---

UserPassword

The password of a Creatio user.

---

Example of a request body:

{
    "UserName":"Supervisor",
    "UserPassword":"Supervisor"
}

AuthService.svc response

Structural elements of the request response:

• HTTP status code;
• response headers;
• response body.

HTTP status code

As a request response, the server returns an HTTP status code encrypted in 3 digits. The first digit specifies the status class. The second and the third digits determine the response ordinal number.

When executing the authentication request, the server returns the following status codes:

Response headers

The response to a POST request contains authentication cookies. You need to save these cookies on the side of the client or on the client computer to use them in your further Creatio web service queries.

Response body

{
 "Code": 0,
 "Message": "",
 "Exception": null,
 "PasswordChangeUrl": null,
 "RedirectUrl": null
}

The response body will contain a JSON object of the authentication status.

The primary properties of the JSON object:

Code

Authentication status code

If the code contains a “0” value, the authentication is successful. Othewise, it is failed.

---

Message

The message notifying of an unsuccessful authentication.

---

Exception

The object that contains a detailed description of the exception connected with the unsuccessful authentication.

---

Example of a software implementation of the authentication

Create a C# console application in Visual Studio and give it a name, e.g., RequestAuthentification. You can download the full code with case implementation using the following link.

// Sends a request to the authentication service and processes the response.
public void TryLogin() {
    var authData = @"{
        ""UserName"":""" + _userName + @""",
        ""UserPassword"":""" + _userPassword + @"""
    }";
    var request = CreateRequest(_authServiceUrl, authData);
    _authCookie = new CookieContainer();
    request.CookieContainer = _authCookie;
    // Upon successful authentication, we save authentication cookies for
    // further use in requests to Creatio. In case of failure
    // authentication application console displays a message about the reason
    // of the mistake.
    using (var response = (HttpWebResponse)request.GetResponse())
    {
        if (response.StatusCode == HttpStatusCode.OK)
        {
            using (var reader = new StreamReader(response.GetResponseStream()))
            {
                var responseMessage = reader.ReadToEnd();
                Console.WriteLine(responseMessage);
                if (responseMessage.Contains("\"Code\":1"))
                {
                    throw new UnauthorizedAccessException($"Unauthorized {_userName} for {_appUrl}");
                }
            }
            string authName = ".ASPXAUTH";
            string authCookeValue = response.Cookies[authName].Value;
            _authCookie.Add(new Uri(_appUrl), new Cookie(authName, authCookeValue));
        }
    }
}
// Create request to the authentication service.
private HttpWebRequest CreateRequest(string url, string requestData = null)
        {
            HttpWebRequest request = (HttpWebRequest)WebRequest.Create(url);
            request.ContentType = "application/json";
            request.Method = "POST";
            request.KeepAlive = true;
            if (!string.IsNullOrEmpty(requestData))
            {
                using (var requestStream = request.GetRequestStream())
                {
                    using (var writer = new StreamWriter(requestStream))
                    {
                        writer.Write(requestData);
                    }
                }
            }
            return request;
        }
// Method realizes protection from CSRF attacks: copies cookie, which contents CSRF-token 
// and pass it to the header of the next request.
private void AddCsrfToken(HttpWebRequest request) {
    var cookie = request.CookieContainer.GetCookies(new Uri(_appUrl))["BPMCSRF"];
    if (cookie != null) {
        request.Headers.Add("BPMCSRF", cookie.Value);
    }
}

Disabling the CSRF protection

In Creatio, you can disable the CSRF protection both for the whole application or for separate services and methods.

1. Disabling the CSRF protection for all application services
   In the .\Web.Config and .\Terrasoft.WebApp\Web.Config files, disable the UseCsrfToken setting:
   

   <add value="false" key="UseCsrfToken" />
   

2. Disabling the CSRF protection for one application service
   Use the DisableCsrfTokenValidationForPaths setting in the .\Web.Config file:
   

   <add key="DisableCsrfTokenValidationForPaths" value="/ServiceModel/ MsgUtilService.svc" />
   

3. Disabling the CSRF protection for several methods of different services
   You can do it using the same DisableCsrfTokenValidationForPaths setting in the .\Web.Config file.
   

   <add key="DisableCsrfTokenValidationForPaths" value="/MsgUtilService.svc/Ping,/AuthService.svc/Login" />