Creatio development guide
PDF
Это документация Creatio версии 7.15.0. Мы рекомендуем использовать новую версию документации.

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

Glossary Item Box

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

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

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

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

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

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

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

К СВЕДЕНИЮ

CSRF (англ. Сross Site Request Forgery — «межсайтовая подделка запроса») — вид атак на посетителей веб-сайтов, использующий недостатки протокола HTTP.

При интеграции 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-х цифрах. Первая цифра указывает на класс состояния. Вторая и третья цифры — порядковый номер ответа.

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

200 OK  Запрос успешно завершен и значение ресурса не равно нулю. В этом случае, тело ответа должно содержать код состояния аутентификации. Если содержит значение 0, то аутентификация успешна. В случае неудачной аутентификации код состояния будет равен 1 и тело запроса будет содержать сообщение о причине неудачной аутентификации.  
403 Forbidden  Сервер не может предоставить доступ к ресурсу, указанному в запросе (например, в случае ошибки в имени метода). Дополнительная информация может содержаться в теле ответа.  

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

В заголовках ответа на 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-атак

ВАЖНО

Отключение защиты от CSRF-атак рекомендуется использовать только в случае применения basic-аутентификации.

В 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" />
    

 

© Terrasoft 2002-2020.

Был ли данный материал полезен?

Как можно улучшить эту статью?