Authenticate (V3)

Предупреждение

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

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

POST /V3/Authenticate

Query Parameters:

type –
способ аутентификации. Принимает значения:
- password — по логину и паролю,
- certificate — по сертификату,
- sid — по auth.sid.

Request Headers:

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

Request Body:

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

Status Codes:

200 OK – операция успешно завершена.
400 Bad Request – данные в запросе имеют неверный формат или отсутствуют обязательные параметры.
401 Unauthorized – в запросе отсутствует HTTP-заголовок Authorization, или в этом заголовке отсутствует параметр ddauth_api_client_id, или переданный в нем ключ разработчика не зарегистрирован в Диадоке.
405 Method Not Allowed – используется неподходящий HTTP-метод.
500 Internal Server Error – при обработке запроса возникла непредвиденная ошибка.

Response Body:

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

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

по логину и паролю,
по сертификату,
по auth.sid.

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

Чтобы аутентифицироваться по логину и паролю, укажите в качестве параметра запроса 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, в теле запроса передайте бинарное содержимое открытого ключа сертификата.

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

Расшифруйте тело ответа с помощью закрытого ключа сертификата пользователя, используя для этого сервис криптопровайдера. Для упрощения работы с API используйте SDK: он содержит реализацию механизма аутентификации по сертификату.
Полученный после расшифровки массив байтов закодируйте в Base64-строку.
Передайте закодированную строку в метод 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) — возвращает авторизационный токен после аутентификации по сертификату