Аутентификация внешних запросов

Общие сведения

Все внешние запросы к веб-сервисам Creatio должны быть аутентифицированы.

В Creatio поддерживаются следующие виды аутентификации внешних запросов:

• Анонимная аутентификация (Anonymous).
• Базовая аутентификация (Basic-аутентификация).
• Аутентификация на основе Cookies (Forms-аутентификация).

Оптимальным способом аутентификации для интеграции с приложением является Forms-аутентификация.

Для Forms-аутентификации в Creatio предназначен веб-сервис AuthService.svc.

Начиная с версии 7.10 в приложении реализована защита от CSRF-атак.

При интеграции Creatio со сторонними приложениями необходимо пройти аутентификацию с помощью сервиса AuthService.svc. После удачного прохождения аутентификации AuthService возвращает аутентификационный cookie, который необходимо добавлять к запросу, а также cookie, содержащий CSRF-токен, который необходимо поместить в заголовок запроса. Пример использования аутентификационного куки приведен ниже, а также в статьях разделов "Интеграция по протоколу OData" и "Веб-служба DataService".

Запрос к сервису AuthService.svc

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

Структура запроса к веб-сервису:

• строка запроса;
• заголовки запроса;
• тело запроса.

Строка запроса

Для прохождения аутентификации необходимо вызвать метод Login сервиса AuthService.svc.

Структура строки запроса

http(s)://[Адрес приложения Creatio]/ServiceModel/AuthService.svc/Login

Пример строки запроса

https://mycreatio.com/ServiceModel/AuthService.svc/Login

Заголовки запроса

Content-Type

Content-Type: application/json

Кодировка и тип ресурса, который передается в теле запроса.

---

ForceUseSession

ForceUseSession: true

Заголовок ForceUseSession отвечает за принудительное использование уже существующей сессии.

---

Тело запроса

В теле запроса должны передаваться учетные данные пользователя Creatio. Учетные данные передаются в формате JSON-объекта.

Свойства JSON-объекта с учетными данными

UserName

Имя пользователя Creatio.

---

UserPassword

Пароль пользователя Creatio.

---

Пример тела запроса:

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

Ответ сервиса AuthService.svc

Структурные элементы ответа на запрос:

• код состояния HTTP;
• заголовки ответа;
• тело ответа.

Код состояния HTTP

В ответе на запрос сервер возвращает код состояния HTTP, который зашифрован в 3-х цифрах. Первая цифра указывает на класс состояния. Вторая и третья цифры — порядковый номер ответа.

При выполнении запроса на аутентификацию сервер возвращает следующие коды состояния:

Заголовки ответа

В заголовках ответа на POST-запрос будут содержаться аутентификационные cookies, которые необходимо сохранить на стороне клиента или клиентском компьютере и в дальнейшем использовать в запросах к веб-сервисам Creatio.

Тело ответа

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

В теле ответа будет содержаться JSON-объект состояния аутентификации.

Основные свойства возвращаемого JSON-объекта:

Code

Код состояния аутентификации.

Если содержит значение 0, то аутентификация успешна. Иначе — неудачная.

---

Message

Сообщение о причине неудачной аутентификации.

---

Exception

Объект, содержащий детальное описание исключения, связанного с неудачной аутентификацией.

---

Пример программной реализации аутентификации

Для реализации примера необходимо в Visual Studio создать обычное консольное приложение C#, назвав его, например, RequestAuthentification. Полный код примера можно скачать по ссылке.

// Отправляет запрос сервису аутентификации и обрабатывает ответ
public void TryLogin() {
    var authData = @"{
        ""UserName"":""" + _userName + @""",
        ""UserPassword"":""" + _userPassword + @"""
    }";
    var request = CreateRequest(_authServiceUrl, authData);
    _authCookie = new CookieContainer();
    request.CookieContainer = _authCookie;
    // При успешной аутентификации сохраняем аутентификационные куки для
    // дальнейшего использования в запросах к Creatio.  В случае неудачной 
    // аутентификации в консоль приложения выводится сообщение о причине
    // ошибки
    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));
        }
    }
}
// Создает запрос к сервису аутентификации
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;
        }
// Метод реализует защиту от CSRF-атак: копирует cookie, содержащий CSRF-токен 
// и помещает его в заголовок следующего запроса
private void AddCsrfToken(HttpWebRequest request) {
    var cookie = request.CookieContainer.GetCookies(new Uri(_appUrl))["BPMCSRF"];
    if (cookie != null) {
        request.Headers.Add("BPMCSRF", cookie.Value);
    }
}

Отключение защиты от CSRF-атак

В Creatio существует возможность отключить защиту от CSRF-атак как для всего приложения, так и для отдельных сервисов и методов.

1. Отключение защиты от CSRF-атак для всех сервисов приложения
   Чтобы отключить защиту от CSRF-атак, необходимо в файлах .\Web.Config и .\Terrasoft.WebApp\Web.Config отключить настройку UseCsrfToken:
   

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

2. Отключение защиты от CSRF-атак для одного сервиса приложения
   Для этого предназначена настройка DisableCsrfTokenValidationForPaths в файле .\Web.Config
   

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

3. Отключение защиты от CSRF-атак для нескольких методов разных сервисов
   Это можно сделать, используя ту же настройку DisableCsrfTokenValidationForPaths в файле .\Web.Config
   

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