• auth.as / Поддержка / Описание работы с API сервиса auth.as по https

    Описание работы с API сервиса auth.as по https

    Для интеграции со сторонними сервисами, системами и веб-приложениями наш сервис предлагает простой и гибкий API для взаимодействия с несколькими функциями: проверки одноразового пароля для конкретного пользователя, авторизации пользователя для дальнейшего управления своим доменом, управления пользователями и токенами. Каждая функция возвращает код ответа от сервера в случае успеха или ошибки.

    Обращаем ваше внимание, что запросы к API необходимо передавать только по шифрованному SSL-соединению на 443 порт (https). Не используйте http!

    Полный список всех функций API


    Функции валидации и аутентификации: Check_code, Authenticate.


    Функция check_code

    Данная функция служит для валидации одноразового пароля, сгенерированного токеном, и/или пароля для указанного пользователя.. В случае, когда у домена установлен флаг “Отправляет пароль”, происходит также валидация пароля пользователя.

    Обработка запросов функции check_code происходит по адресу: https://console.auth.as/api/v1.0/check_code, рассмотрим набор аргументов для её использования.

    Техническое описание

    Функция check_code принимает три обязательных параметра: API Key домена, email пользователя и одноразовый пароль(пароль пользователя также может быть проверен). Кроме этого доступен необязательный параметр: format.

    Тип обрабатываемого HTTP-запроса: POST.

    • Параметр api_key [Строка] - Значение API_KEY домена для данного пользователя.
    • Параметр email [Строка] - В параметре email вам необходимо передавать электронный адрес пользователя. Обращаем внимание, что для Standart-доменов электронный адрес может использоваться совершенно любой, а не только привязанный к вашему домену. Для ActiveDirectory-доменов используется электронный адрес из профиля пользователя.
    • Параметр code [Строка] - В данном параметре необходимо передать пароль пользователя и/или одноразовый пароль - шестизначный числовой код, сгенерированный в мобильном приложении или физическом носителе. Возможны несколько вариантов заполнения поля code:
    • Параметр format [Строка], необязательный - Если передать значение "json", то ответы от сервера будут приходить в расширенном формате.
      • Если пользователь не имеет токена в системе auth.as, но в его домене установлен флаг “Отправляет пароль”, то тут необходимо передать просто пароль пользователя.
      • Если пользователь имеет токен в системе auth.as, а в его домене флаг “Отправляет пароль” не установлен, то тут необходимо передать 6-значный одноразовый пароль.
      • Если пользователь имеет токен в системе auth.as, а также, в его домене установлен флаг “Отправляет пароль”, то тут необходимо передать строку, состоящую из пароля пользователя + 6-значный одноразовый пароль. Допустим пароль пользователя в auth.as “password” и его мобильный токен сгенерировал одноразовый код “123456”, тогда параметр code = “password123456”

    Внимание! Если у пользователя нет назначенного токена в системе auth.as, а также, в его домене флаг “Отправляет пароль” не установлен, система никак не сможет такого пользователя авторизовать.

    Пример запроса к API через curl

    Обращаем ваше внимание, что все параметры вымышленные, домена с таким API Key и пользователя с такой учётной записью не существует. Примеры демонстрируют ответы сервера в тех или иных ситуациях.


    Попробуем запросить ответ в JSON от функции для некорректного пароля:

    $ curl -X POST "https://console.auth.as/api/v1.0/check_code" \
    -d 'api_key=319660cf33a044b11231dab823284cc64c86f423' \
    -d 'email=firstname.lastname@domain.tld' \
    -d 'code=091572' \
    -d 'format=json'

    Ответ от сервера:

    {"response_code":401,"message":"Wrong token code for TimeBased algorithm"}

    Ответ от сервера для корректного кода:

    {"response_code":200,"message":"200"}

    Если же мы не будем передавать параметр format, то в ответ придёт только код ответа 200 или 401 в зависимости от результата запроса.


    Пример тестирования через MS PowerShell

    Открываем PowerShell и вставляем код приведенный ниже в окно скрипта.

    Обращаем внимание, что переменные $email и $api_key должны быть заполнены теми значениями, которые мы хотим протестировать.

    $email = "testuser1@testrcntec1.com"
    $api_key = "26d19660c5189044b111dab823284cc64c86f423"
    $code = Read-Host 'Please, enter your one-time password'
    $response = "0"

    $body = @{
           api_key = $api_key;
           email = $email;
           code = $code;}

    $response = Invoke-RestMethod -uri https://console.auth.as/api/v1.0/check_code -Method Post -Body $body
    echo $response

    Затем, запускаем скрипт на выполнение, вводим код ОТП, и получаем результат в виде сообщения консоли.

    назад к содержанию


    Функция authenticate

    Данная функция служит для аутентификации пользователя в системе auth.as с целью выполнения дальнейших запросов через api-интерфейс. В отличие от других функций, результатом выполнения данной функции является сеансовый ключ, который действует в течение следующих 24 часов, либо до первого изменения учетной записи аутентифицировавшегося пользователя.

    Обработка запросов функции authenticate происходит по адресу: https://console.auth.as/api/v1.0/authenticate, рассмотрим набор аргументов для её использования.

    Техническое описание

    Функция authenticate принимает три обязательных параметра: email пользователя, пароль пользователя и одноразовый код приложения.

    Тип обрабатываемого HTTP-запроса: POST.

    • Параметр email [Строка] - электронный адрес пользователя, так, как он заведен в системе auth.as.
    • Параметр password [Строка], необязательный - пароль пользователя, принимается только в случае, если у домена этого пользователя установлена опция “Отправляет пароль”.
    • Параметр code [Строка], необязательный - одноразовый код, принимается только в случае, если данному пользователю назначен токен в системе auth.as.
    Пример использования функции и успешного ответа от сервера.

    Попробуем запросить ответ от функции для корректного пользователя, для домена которого флаг “Отправляет пароль” не установлен:

    $ curl -X POST "https://console.auth.as/api/v1.0/authenticate" \
    -d 'email=firstname.lastname@domain.tld' \
    -d 'code=091572'

    Ответ от сервера:

    HTTP/1.1 200 OK
    4790bbe4-6c34-11e5-b853-77b5a2252bc2

    В данном ответе, сеансовый ключ 4790bbe4-6c34-11e5-b853-77b5a2252bc2 должен быть зафиксирован и использован в дальнейшем при работе с API в части управления пользователями и токенами.

    назад к содержанию


    Функции управления пользователями: Create, Delete, Lock, Unlock.


    Функция Users/Create

    Данная функция служит для создания нового пользователя в системе auth.as. Доступна для выполнения только для пользователей с ролью “Администратор домена”. Необходимо предварительное получение сеансового ключа, с помощью функции “authenticate”.

    Обработка запросов функции users/create происходит по адресу: https://console.auth.as/api/v1.0/users/create, рассмотрим набор аргументов для её использования.

    Техническое описание

    Функция users/create принимает заголовок и три параметра. В заголовке передается сеансовый ключ, полученный предварительно с помощью функции “authenticate”. Параметры: upn пользователя, email пользователя и пароль пользователя.

    Тип обрабатываемого HTTP-запроса: POST.

    • Заголовок x-auth-token [Строка] - сеансовый ключ, который передается для идентификации отправителя запроса.
    • Параметр upn [Строка], необязательный - используется при создании пользователя из ActiveDirectory домена. По переданному UPN (User Principal Name) ищется соответствующий пользователь в каталоге AD, и создается в auth.as с найденным email. Пароль для таких пользователей в auth.as не хранится.
    • Параметр email [Строка], необязательный - адрес электронной почты нового пользователя, передается только для пользователей Standard доменов.
    • Параметр password [Строка], необязательный - Пароль для нового пользователя, принимается только для пользователей Standard доменов.
    Пример использования функции и успешного ответа от сервера.

    Попробуем запросить ответ от функции для нового пользователя, стандартного домена, предварительно получив сеансовый ключ для администратора этого домена:

    $ curl -X POST "https://console.auth.as/api/v1.0/users/create" \
    -d 'email=foobar@example.com' \
    -d 'password=foobar' \
    --header "X-AUTH-TOKEN:4790bbe4-6c34-11e5-b853-77b5a2252bc2"

    Ответ от сервера:

    HTTP/1.1 200 OK
    { "company": "example", "domain": "example.com", "username": "foobar@example.com", "login": "foobar", "email": "foobar@example.com", "phone": null, "is_domain_admin": false, }

    назад к содержанию


    Функция Users/Delete

    Данная функция служит для удаления пользователя из системы auth.as. Доступна для выполнения только для пользователей с ролью “Администратор домена”. Необходимо предварительное получение сеансового ключа, с помощью функции “authenticate”.

    Обработка запросов функции users/delete происходит по адресу: https://console.auth.as/api/v1.0/users/delete, рассмотрим набор аргументов для её использования.

    Техническое описание

    Функция users/delete принимает заголовок и один параметр. В заголовке передается сеансовый ключ, полученный предварительно с помощью функции “authenticate”. Параметр: email пользователя.

    Тип обрабатываемого HTTP-запроса: DELETE.

    • Заголовок x-auth-token [Строка] - сеансовый ключ, который передается для идентификации отправителя запроса.
    • Параметр username [Строка] - адрес электронной почты удаляемого пользователя.
    Пример использования функции и успешного ответа от сервера.

    Попробуем запросить ответ от функции для нового пользователя, стандартного домена, предварительно получив сеансовый ключ для администратора этого домена:

    $ curl -X DELETE "https://console.auth.as/api/v1.0/users/delete" \
    -d 'username=foobar@example.com' \
    --header "X-AUTH-TOKEN:4790bbe4-6c34-11e5-b853-77b5a2252bc2"

    Ответ от сервера:

    HTTP/1.1 200 OK

    назад к содержанию


    Функция Users/Lock

    Данная функция служит для блокировки пользователя в системе auth.as. Доступна для выполнения только для пользователей с ролью “Администратор домена”. Необходимо предварительное получение сеансового ключа, с помощью функции “authenticate”.

    Обработка запросов функции users/lock происходит по адресу: https://console.auth.as/api/v1.0/users/lock, рассмотрим набор аргументов для её использования.

    Техническое описание

    Функция users/lock принимает заголовок и один параметр. В заголовке передается сеансовый ключ, полученный предварительно с помощью функции “authenticate”. Параметр: username пользователя.

    Тип обрабатываемого HTTP-запроса: PUT.

    • Заголовок x-auth-token [Строка] - сеансовый ключ, который передается для идентификации отправителя запроса.
    • Параметр username [Строка] - адрес электронной почты блокируемого пользователя.
    Пример использования функции и успешного ответа от сервера.

    Попробуем запросить ответ от функции для нового пользователя, стандартного домена, предварительно получив сеансовый ключ для администратора этого домена:

    $ curl -X PUT "https://console.auth.as/api/v1.0/users/lock" \
    -d 'username=foobar@example.com' \
    --header "X-AUTH-TOKEN:4790bbe4-6c34-11e5-b853-77b5a2252bc2"

    Ответ от сервера:

    HTTP/1.1 200 OK
    { "company": "example", "domain": "example.com", "username": "foobar@corp.example.com", "is_active": "false" }

    назад к содержанию


    Функция Users/Unlock

    Данная функция служит для разблокировки пользователя в системе auth.as. Доступна для выполнения только для пользователей с ролью “Администратор домена”. Необходимо предварительное получение сеансового ключа, с помощью функции “authenticate”.

    Обработка запросов функции users/unlock происходит по адресу: https://console.auth.as/api/v1.0/users/unlock, рассмотрим набор аргументов для её использования.

    Техническое описание

    Функция users/unlock принимает заголовок и один параметр. В заголовке передается сеансовый ключ, полученный предварительно с помощью функции “authenticate”. Параметр: username пользователя.

    Тип обрабатываемого HTTP-запроса: PUT.

    • Заголовок x-auth-token [Строка] - сеансовый ключ, который передается для идентификации отправителя запроса.
    • Параметр username [Строка] - адрес электронной почты разблокируемого пользователя.
    Пример использования функции и успешного ответа от сервера.

    Попробуем запросить ответ от функции для нового пользователя, стандартного домена, предварительно получив сеансовый ключ для администратора этого домена:

    $ curl -X PUT "https://console.auth.as/api/v1.0/users/unlock" \
    -d 'username=foobar@example.com' \
    --header "X-AUTH-TOKEN:4790bbe4-6c34-11e5-b853-77b5a2252bc2"

    Ответ от сервера:

    HTTP/1.1 200 OK
    { "company": "example", "domain": "example.com", "username": "foobar@corp.example.com", "is_active": "true" }

    назад к содержанию


    Функции управления токенами: Create, Delete, Send_qr.


    Функция Tokens/Create

    Данная функция служит для создания нового мобильного time-based токена в системе auth.as. Новый токен должен быть сразу же привязан к пользователю. У пользователя может быть только 1 токен. Доступна для выполнения только для пользователей с ролью “Администратор домена”. Необходимо предварительное получение сеансового ключа, с помощью функции “authenticate”.

    Обработка запросов функции tokens/create происходит по адресу: https://console.auth.as/api/v1.0/tokens/create, рассмотрим набор аргументов для её использования.

    Техническое описание

    Функция tokens/create принимает заголовок и один параметр. В заголовке передается сеансовый ключ, полученный предварительно с помощью функции “authenticate”. Параметр: email пользователя, для которого создается токен.

    Тип обрабатываемого HTTP-запроса: POST.

    • Заголовок x-auth-token [Строка] - сеансовый ключ, который передается для идентификации отправителя запроса.
    • Параметр email [Строка] - адрес электронной почты пользователя, для которого создается токен.
    Пример использования функции и успешного ответа от сервера.

    Попробуем запросить ответ от функции для нового пользователя, стандартного домена, предварительно получив сеансовый ключ для администратора этого домена:

    $ curl -X POST "https://console.auth.as/api/v1.0/tokens/create" \
    -d 'email=foobar@example.com' \
    --header "X-AUTH-TOKEN:4790bbe4-6c34-11e5-b853-77b5a2252bc2"

    Ответ от сервера:

    HTTP/1.1 200 OK

    назад к содержанию


    Функция Tokens/Delete

    Данная функция служит для удаления токена из системы auth.as. Доступна для выполнения только для пользователей с ролью “Администратор домена”. Необходимо предварительное получение сеансового ключа, с помощью функции “authenticate”.

    Обработка запросов функции tokens/delete происходит по адресу: https://console.auth.as/api/v1.0/tokens/delete, рассмотрим набор аргументов для её использования.

    Техническое описание

    Функция tokens/delete принимает заголовок и один параметр. В заголовке передается сеансовый ключ, полученный предварительно с помощью функции “authenticate”. Параметр: email пользователя.

    Тип обрабатываемого HTTP-запроса: DELETE.

    • Заголовок x-auth-token [Строка] - сеансовый ключ, который передается для идентификации отправителя запроса.
    • Параметр email [Строка] - адрес электронной почты пользователя, у которого нужно удалить токен.
    Пример использования функции и успешного ответа от сервера.

    Попробуем запросить ответ от функции для нового пользователя, стандартного домена, предварительно получив сеансовый ключ для администратора этого домена:

    $ curl -X DELETE "https://console.auth.as/api/v1.0/tokens/delete" \
    -d 'email=foobar@example.com' \
    --header "X-AUTH-TOKEN:4790bbe4-6c34-11e5-b853-77b5a2252bc2"

    Ответ от сервера:

    HTTP/1.1 200 OK

    назад к содержанию


    Функция Tokens/Send_qr

    Данная функция служит для создания временной web-страницы с qr-кодом токена и отправки ссылки на эту страницу на электронную почту пользователя. Ссылка будет доступна 24 часа после отправки. После первого успешного перехода по ссылке, она удаляется через 10 минут. Функция доступна для выполнения только для пользователей с ролью “Администратор домена”. Необходимо предварительное получение сеансового ключа, с помощью функции “authenticate”.

    Обработка запросов функции tokens/send_qr происходит по адресу: https://console.auth.as/api/v1.0/tokens/send_qr, рассмотрим набор аргументов для её использования.

    Техническое описание

    Функция tokens/send_qr принимает заголовок и один параметр. В заголовке передается сеансовый ключ, полученный предварительно с помощью функции “authenticate”. Параметр: email пользователя.

    Тип обрабатываемого HTTP-запроса: PUT.

    • Заголовок x-auth-token [Строка] - сеансовый ключ, который передается для идентификации отправителя запроса.
    • Параметр email [Строка] - адрес электронной почты пользователя, для которого создается страница с QR кодом.
    Пример использования функции и успешного ответа от сервера.

    Попробуем запросить ответ от функции для нового пользователя, стандартного домена, предварительно получив сеансовый ключ для администратора этого домена:

    $ curl -X PUT "https://console.auth.as/api/v1.0/tokens/send_qr" \
    -d 'email=foobar@example.com' \
    --header "X-AUTH-TOKEN:4790bbe4-6c34-11e5-b853-77b5a2252bc2"

    Ответ от сервера:

    HTTP/1.1 200 OK
    https://console.auth.as/api/v1.0/qr?hash=ba0aadb1fdba836c98013e2952017de589324494

    Открыв данную ссылку в браузере, можно увидеть QR-код токена, для сканирования мобильным приложением auth.as: token.

    назад к содержанию


    Ответы сервера

    Сервер возвращает два типа ответа в зависимости от успешности любой из операций любого из шагов, описанных в предыдущем разделе этой инструкции.

    Статус 200 возвращается только в случае переданных всех корректных значений: API Key домена, email пользователя и одноразовый пароль (код приложения или физического устройства).

    Статус 401 возвращается в случае любой из ошибок:

    • Не переданы все обязательные параметры;
    • Не найден домен по API Key;
    • Не найден пользователь в домене;
    • Пользователю не назначен токен;
    • Домен, пользователь или токен заблокированы;
    • Передан некорректный код, который не мог быть рассчитан алгоритмом токена;
    • Любая другая ошибка или ситуация, не описанная в этом списке.
     
    Формат ответов

    В зависимости от значения параметра format в POST-запросе к функции API возвращается ответ в том или ином формате. По-умолчанию используется ответ в виде text/plain, проще говоря — обычный текст. В теле ответа придёт статус 200 или 401, который точно скажет — успешно выполнена функция или же нет.

    В случае использования format = “plain” HTTP Status Code всегда возвращается равным 200, но в теле документа придёт результат 200 или 401.

    Если передано значение format = “json”, тогда ответ сервера будет в виде  application/json с подробным описанием ошибки, в случае её появления и HTTP Status Code будет 200 или 401, в зависимости от успешности выполнения функции.

    Значение параметра format влияет на тип возвращаемого ответа. В json он более развёрнутый и содержит дополнительную информацию для вызывающей стороны.

    назад к содержанию