Перейти к основному содержимому

Authenticate (V3)

warning

Метод устарел. Рекомендуемый способ авторизации описан в инструкции Авторизация.

Авторизует пользователя в Диадоке.

POST /V3/Authenticate

Параметры запроса

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

  • Authorization — данные, необходимые для авторизации. В заголовке нужно передать DiadocAuth ddauth_api_client_id.

Тело запроса

Тело запроса зависит от способа аутентификации. См. описание ниже.

Коды ответа

  • 200 — операция успешно завершена.
  • 400 — данные в запросе имеют неверный формат или отсутствуют обязательные параметры.
  • 401 — в запросе отсутствует HTTP-заголовок Authorization, или в этом заголовке отсутствует параметр ddauth_api_client_id, или переданный в нем ключ разработчика не зарегистрирован в Диадоке.
  • 405 — используется неподходящий HTTP-метод.
  • 500 — при обработке запроса возникла непредвиденная ошибка.

Тело ответа

Тело ответа зависит от способа аутентификации.

В Диадоке существуют следующие способы аутентификации:

Аутентификация по логину и паролю

Чтобы аутентифицироваться по логину и паролю, укажите в качестве параметра запроса type = password.

В теле запроса передайте сериализованный объект в формате JSON или protobuf:

  • Если вы передаете данные в формате JSON, укажите заголовок Content-Type: application/json.

    {
    "login": "login",
    "password": "pass"
    }
  • Если вы передаете данные в формате protobuf, необязательно указывать Content-Type, так как по умолчанию десериализация происходит из protobuf.

    message LoginPassword {
    required string Login = 1;
    required string Password = 2;
    }

В теле ответа метод вернет авторизационный токен.

Пример HTTP-запроса:

POST v3/Authenticate?type=password HTTP/1.1
Host: diadoc-api.kontur.ru
Authorization: DiadocAuth ddauth_api_client_id=testClient-8ee1638deae84c86b8e2069955c2825a
Content-Length: 1252
Connection: Keep-Alive

Пример тела ответа:

HTTP/1.1 200 OK
Content-Length: 598

<Авторизационный токен>

Аутентификация по сертификату

Чтобы аутентифицироваться по сертификату, укажите в качестве параметра запроса type = certificate.

Укажите заголовок Content-Type: application/octet-stream, в теле запроса передайте бинарное содержимое открытого ключа сертификата.

В теле ответа метод вернет зашифрованную строку. Чтобы получить из нее авторизационный токен:

  1. Расшифруйте тело ответа с помощью закрытого ключа сертификата пользователя, используя для этого сервис криптопровайдера. Для упрощения работы с API используйте SDK: он содержит реализацию механизма аутентификации по сертификату.
  2. Полученный после расшифровки массив байтов закодируйте в Base64-строку.
  3. Передайте закодированную строку в метод AuthenticateConfirm (V3), он вернет авторизационный токен.

Пример HTTP-запроса:

POST v3/Authenticate?type=certificate HTTP/1.1
Host: diadoc-api.kontur.ru
Authorization: DiadocAuth ddauth_api_client_id=testClient-8ee1638deae84c86b8e2069955c2825a
Content-Length: 1252
Connection: Keep-Alive

<Двоичное DER-представление X.509-сертификата пользователя>

Пример тела ответа:

HTTP/1.1 200 OK
Content-Length: 598

<Двоичное DER-представление зашифрованного токена>

Аутентификация по auth.sid

Если вы получили идентификатор auth.sid из других сервисов, вы можете использовать его для аутентификации в Диадоке.

Чтобы аутентифицироваться по auth.sid, укажите в качестве параметра запроса type = sid. В теле запроса нужно передавать auth.sid c заголовком Content-Type: text/plain

Примеры использования

Пример кода для получения авторизационного токена (C#):

//URL веб-сервиса Диадок
private const string DefaultApiUrl = "https://diadoc-api.kontur.ru";

//Идентификатор клиента
private const string DefaultClientId = "test-8ee1638deae84c86b8e2069955c2825a";

//Для использования Диадок требуются:
//1. Крипто-API, предоставляемое операционной системой (доступно через класс WinApiCrypt)
//2. Экземпляр класса DiadocApi, проксирующий работу с веб-сервисом Диадок
private static WinApiCrypt Crypt = new WinApiCrypt();
public static readonly DiadocApi Api = new DiadocApi(
DefaultClientId,
DefaultApiUrl,
Crypt);

//Логин для авторизации на сервере Диадок

private const string DefaultLogin = "логин";

//Пароль для авторизации на сервере Диадок
private const string DefaultPassword = "пароль";

//Путь к сертификату для авторизации на сервере Диадок
public const string DefaultPathToCert = "C:\\folder\\subfolder\\cert.cer";

//Для авторизации по сертификату необходимо сертификат преобразовать в массив байтов
public static byte[] ReadCertContent(string pathToCert)
{
var cert = new X509Certificate(pathToCert);
return cert.Export(X509ContentType.Cert);
}

static void Main(string[] args)
{
//Можно использовать либо аутентификацию по логину/паролю, либо по сертификату
var authTokenLogin = Api.Authenticate(DefaultLogin, DefaultPassword); //по паре логин/пароль
var authTokenCert = Api.Authenticate(ReadCertContent(DefaultPathToCert)); //по сертификату
}

См. также

Инструкции:

Методы для аутентификации:

  • Authenticate (V3) — авторизует пользователя в Диадоке
  • AuthenticateConfirm (V3) — возвращает авторизационный токен после аутентификации по сертификату

Оцените материал страницы

Нашли ошибку или столкнулись с проблемой?

СКБ Контурс 1988 года