API:Login/ru

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

Боты и прочие неинтерактивные приложения, когда это возможно, должны использовать owner-only OAuth consumers для аутентификации, как более безопасный метод. Однако в действии  можно использовать и пароли для ботов, как описано ниже на этой странице.

Интерактивные приложения, такие как пользовательские редакторы или приложения для патрулирования, которые работают, не заменяя веб-сайт полностью, обычно также используют OAuth для аутентификации программы, т.к. это проще и безопаснее, однако  может быть использован, если это недоступно.

Интерактивные приложения, такие как мобильные приложения, которые стремятся полностью заменить веб-сайт, должны использовать  для аутентификации.

Как войти в учётную запись
Вашей программе потребуется авторизоваться MediaWiki, если:


 * ему нужно получить информацию или исполнить действие, разрешённое только участникам с определёнными правами
 * он выполняет большие запросы поиска, которые были бы неэффективны без использования доступным только привилегированным участникам бОльших пределов на количество результатов за запрос

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

Если ваш клиент написан на исполняемом в браузере пользователя JavaScript, он обычно работает с учетными данными использующего его пользователя, и поэтому не требует авторизации сам по себе. В этом случае вам не потребуется входить в учётную запись через API сетевых служб: вам всего лишь потребуется убедиться, что пользователь вошёл в учётную запись через веб-интерфейс.

Если ваш клиент использует OAuth или подобный механизм, ему не нужно явно входить в учётную запись, так как все OAuth запросы автоматически аутентифицированы.

Учетные записи приложений
Если вы не хотите, чтобы ваше приложение входило в вашу учётную запись, вы можете создать отдельную учётную запись специально для вашего приложения. Это особенно важно, если ваше приложение:


 * выполняет автоматизированные правки или другие операции в большом количестве.
 * вызывает большие или ресурсозатратные информационные запросы.

При наличии отдельной учётной записи, изменения, произведённые вашим приложением, легко отследить, а к учётной записи приложения можно применить особые группы прав (обычно группу ботов). Некоторые вики устанавливают внутреннюю политику автоматического редактирования и/или процедуру обработки запросов присвоения прав бота.

Как проверить, авторизованы ли вы
Механизм логина обычно использует cookies, чтобы отслеживать статус сессии. Однако клиенты должны непосредственно проверять, залогинены ли они, а не пытаться определить это, проверяя cookies или логинясь вслепую, вне зависимости от того, требуется ли это.

Рекоммендованный способ убедиться, что запросы исполняются от вошедшего в систему клиента — использовать параметр assert=user, который принимается при любом API-вызове. При использовании этого параметра, если пользователь незалогинен, будет возвращена ошибка assertuserfailed.

Чтобы непосредственно проверить, под каким пользователем вы залогинены (и залогинены ли вообще), используйте модуль запросов.

Как войти в учётную запись
В MediaWiki до версии 1.27 присутствовало только действие, и все клиенты должны были пользоваться им. Начиная с версии 1.27, действие  должно использоваться только в комбинации с паролями ботов, а интерактивные приложения должны использовать.

Учтите, что процедура логина и поддержание статуса "залогинен" требует корректной обработки HTTP-cookies вашим клиентом при каждом запросе. Как правило, фреймворки и библиотеки для HTTP-запросов делают это за вас.

Действие
Чтобы успешно войти в учётную запись, сначала необходимо получить токен login. В MediaWiki 1.27 и последующих версиях этот токен следует получить, используя запрос с параметром. В более ранних версиях вместо этого нужен POST-запрос с действием.

В ответ могут быть включены другие поля, однако, они считаются устаревшими, и если они и есть, их следует игнорировать.

Когда токен был получен, процесс входа в учётную запись может перейти на следующий этап.

В ответ могут быть включены другие поля, однако, они считаются устаревшими, и если они и есть, их следует игнорировать.

Поле result в выводе указывает на то, был ли успешным вход в учётную запись. В случае неуспешного входа результатом могут быть следующие значения:


 * NeedToken if the lgtoken parameter was not provided or no session was active (e.g. your cookie handling is broken).
 * WrongToken if the supplied token was not a valid token.
 * Failed (since 1.27) if the login failed. A reason field will exist in the response containing and explanation of the failure.
 * Aborted (since 1.27) if the login using the main account password (rather than a bot password) cannot proceed because user interaction is required. The  action should be used instead.
 * NoName (before 1.27) if no lgname was provided.
 * Illegal (before 1.27) if the lgname is not a valid user name.
 * NotExists (before 1.27) if supplied user does not exist.
 * EmptyPass (before 1.27) if the supplied password is empty.
 * WrongPass or WrongPluginPass (before 1.27) if the password is incorrect.
 * CreateBlocked (before 1.27) if auto-creation of the account is required but is not possible.
 * Throttled (before 1.27) if login attempts from your IP have been throttled.
 * Blocked (before 1.27) if the user being logged in to is blocked and blocks prevent login on the wiki.
 * Aborted (before 1.27) if the login was aborted by an extension without further detail. A reason field may be present.

Действие
Это действие реализует интерактивный процесс входа в учётную запись, в котором могут быть задействованы CAPTCHA, взаимодействия со сторонними службами аутентификациями, двухфакторная аутентификация, и не только. Поэтому то, какие конкретно поля требуются, зависит от конфигурации вики. Описание требуемых полей следует получить посредством запроса.

На вики без каких-либо особых расширений аутентификации необходимые поля могут включать username, password , и, возможно, rememberMe , так что запрос на вход в учётную запись будет выглядеть примерно так:

С другой стороны, на вики с расширением для CAPTCHA, расширением для аутентификации посредством OpenID Connect, а также расширением для двухфакторной аутентификации, может потребоваться более сложный процесс аутентификации.

От клиента будет ожидаться перенаправление браузера пользователя на предоставленную цель redirecttarget. Провайдер OpenID произведёт аутентификацию и перенаправит на расположенную на вики страницу Special:OpenIDConnectReturn, которая произведёт валидацию ответа OpenID и перенаправит на адрес loginreturnurl, указанный в первом POST-запросе к API, и к этому адресу будут добавлены параметры code и state. В этот момент клиент снова получает контроль над процессом и выполняет следующий запрос к API.

Теперь клиенту нужно сначала попросить пользователя найти текущий код в своём приложении для двухфакторной аутентификации, а затем отправить введённый код на сервер, чтобы продолжить процесс аутентификации.

Процесс аутентификации теперь успешно завершён.

Если же на каком-либо этапе аутентификация оказывается неуспешной, в ответе будет статус FAIL и сообщение в значении message, которое следует показать пользователю.

В некоторых случаях возможно получить ответ RESTART, например если в расширении OpenID Connect у этой учётной записи OpenID не было привязки ни к какому локальному пользователю. В этом случае клиент может или начать процесс входа сначала, или перейти в режим создания учётной записи, в обоих случаях передавая параметр loginpreservestate или createpreservestate, чтобы сохранить состояние процесса.