API:Login/fr

Vous devrez probablement faire en sorte d'authentifier votre application ou votre client en utilisant un service d'API MédiaWiki. Cela implique de sousmettre une requête d'authentification (login), de créer un cookie, et de confirmer l'authentification en revoyant la requête avec le jeton de confirmation renvoyé par l'API.

Quand m'authentifier ?
Votre client doit s'identifier si:


 * il doit obtenir des information ou effectuer des actions qui nécessitent des droits d'accès particuliers
 * il fait des requêtes de grandes tailles, et serait inefficace sans bénéficier des limites plus hautes qu'ont les comptes avec certains droits

Sur les wikis qui authorisent les modifications anonymes, il est possible d'éditer par l'API sans s'authentifier, mais il est fortement recommandé de le faire tout de même. Sur les wikis privés, vous devez vous identifier pour utiliser l'API, quelle que soit la fonctionnalité

Si votre client est écrit en JavaScript et tourne dans le navigateur, il bénéficie des droits associés à l'utilisateur pour ce navigateur. Dans ce cas, il n'est pas nécessaire de s'identifier en utilisant l'API dédiée -- vous devez seulement vous assurez que l'utilisateur est identifié sur l'interface web.

Comptes utilisateurs dédiés à une application
Plutôt que d'avoir votre application identifiée comme vous même, vous pourriez vouloir lui créer un compte utilisateur. Ceci est particulièrement important si votre application:


 * effectuera des modifications automatisées ou une autre sorte d'opérations de masses.
 * fait effectuer des requêtes de grandes tailles ou qui requièrent beaucoup de puissance de calcul

Avec un compte utilisateur dédié, les changement effectués par votre appli peuvent être facilement trouvés, et des droits spéciaux (généralement ceux d'un groupe "bot") pourront lui être attribués. Some wikis have a policy related to automated editing, and/or a procedure for dealing with "bot" user group requests.

Login gets several tokens that are needed by the server to recognize the logged-in user. In every call to api.php, the cookie set by this request must be passed. The cookies last for around a month and you should check that you need to log in based on detecting that you're not logged in (rather than logging once per session, for example). You can check this on any request using the  generic parameter.

How to log in
Logging in through the API requires submitting a login query and constructing a cookie (many frameworks will construct the cookie automatically). In MediaWiki 1.15.3+, you must confirm the login by resubmitting the login request with the token returned.

Structure of login request
The body of the POST can be empty. This request will also return a session cookie in the HTTP header that you have to return for the second request if your framework does not do this automatically. The sessionid parameter was added in MediaWiki 1.17 and later.

You might need to add the query parameter, containing your domain name for authentication, if you're using an authentication plug-in like Extension:LDAP Authentication.

Confirm token
If the response to the above query was  instead of , you can skip this step. (This extra step was added in MediaWiki 1.15.3.) In MediaWiki 1.15.4, first phase of login in ApiLogin.php is broken, so login/sessionid parameter is not returned, thus token confirmation is impossible. Apply ApiLogin.php file from MediaWiki 1.15.5 to your installation as a quick workaround while you plan your upgrade to 1.15.5. ApiLogin.php from MediaWiki 1.16+ is incompatible with MediaWiki 1.15.3+.

Handle cookies
A successful  request will set cookies needed to be considered logged in. Many frameworks will handle these cookies automatically (such as the cookiejar in cURL). If so, by all means take advantage of this. If not, the most reliable method is to parse them from the HTTP response's Set-Cookie headers.

If this is not possible either, it is possible to construct the appropriate cookies from the various values returned by the  call, but this is not recommended as the necessary cookies may be changed without warning (e.g. something as simple as changing  would require changes to your manual cookie creation code).

When CentralAuth is enabled, as on Wikimedia wikis, the example above will not only log you in to a single domain, but also provide you with three centralauth cookies in the Set-Cookie response headers. To use these, duplicate those cookies (i.e. cookies whose names are prefixed with "centralauth_") and set the domain field of the new cookies to the new domain you'd like to log in at. Once this is done, any GET/POST request to this new domain will (assuming that the user has a SUL/global account) be answered with a reply containing Set-Cookie headers/Cookies specific to that domain.

Errors
Errors are returned in the result field. Possible values include:

Throttling
For security reasons, this module is throttled. By default, you get to login 5 times in 300 seconds, but this may vary from one wiki to another. When you exceed this limit, your login will fail (even if it's otherwise correct) with  and the number of seconds you need to wait in the   field.

Examples

 * Example login codes in PHP:
 * Example login (requires Snoopy)
 * Example login and navigate (using only file_get_contents)
 * Example login (using cURL) - no Snoopy required
 * Example login code in JS (using JQuery)
 * Example login code in Python