API:Authentification
| Cette page fait partie de la documentation de l'API MediaWiki Action. |
Il est possible que l'API MediaWiki demande à votre application ou au client de fournir les certificats d'authentification de l'utilisateur et de se connecter pour: (a) des demandes d'informations ou des actions de modification de données, (b) ou faire des requêtes plus larges avec une limite plus élevée du nombre de résultats par requête.
Deux méthodes pour authentifier
Il y a deux manières de s'authentifier auprès de l'API action de MediaWiki : en utilisant action=login ou action=clientlogin.
Méthode 1. action=login
Les robots et les autres application non interactives doivent utiliser les consommateurs OAuth des auteurs seulement si disponibles car il sont davantage sécurisés.
S'ils ne sont pas disponibles, ou ne peuvent s'appliquer au client, vous pouvez utiliser l'action login avec les mots de passe des robots.
Documentation de l'API
Exemple
Requête POST
lgtoken dans la requête ci-dessus est récupéré de API:Tokens
Réponse
{
"login": {
"lguserid": 21,
"result": "Success",
"lgusername": "William"
}
}
Exemple de code
MediaWiki JS
/*
login.js
MediaWiki API Demos
Demo of `Login` module: Sending request to login
MIT License
*/
var api = new mw.Api();
api.login( 'your_bot_username', 'your_bot_password' ).done( function ( data ) {
console.log( 'You are logged in as ' + data.login.lgusername );
} );
JavaScript
/*
edit.js
MediaWiki API Demos
Demo of `Login` module: Sending post request to login
MIT license
*/
var request = require( 'request' ).defaults( { jar: true } ),
url = 'https://test.wikipedia.org/w/api.php';
// Step 1: GET request to fetch login token
function getLoginToken() {
var params = {
action: 'query',
meta: 'tokens',
type: 'login',
format: 'json'
};
request.get( { url: url, qs: params }, function ( error, res, body ) {
var data;
if ( error ) {
return;
}
data = JSON.parse( body );
loginRequest( data.query.tokens.logintoken );
} );
}
// Step 2: POST request to log in.
// Use of main account for login is not
// supported. Obtain credentials via Special:BotPasswords
// (https://www.mediawiki.org/wiki/Special:BotPasswords) for lgname & lgpassword
function loginRequest( loginToken ) {
var params = {
action: 'login',
lgname: 'bot_username',
lgpassword: 'bot_password',
lgtoken: loginToken,
format: 'json'
};
request.post( { url: url, form: params }, function ( error, res, body ) {
if ( error ) {
return;
}
console.log( body );
} );
}
// Start From Step 1
getLoginToken();
PHP
<?php
/*
login.php
MediaWiki API Demos
Demo of `Login` module: Sending post request to login
MIT license
*/
$endPoint = "https://test.wikipedia.org/w/api.php";
$login_Token = getLoginToken(); // Step 1
loginRequest( $login_Token ); // Step 2
// Step 1: GET request to fetch login token
function getLoginToken() {
global $endPoint;
$params1 = [
"action" => "query",
"meta" => "tokens",
"type" => "login",
"format" => "json"
];
$url = $endPoint . "?" . http_build_query( $params1 );
$ch = curl_init( $url );
curl_setopt( $ch, CURLOPT_RETURNTRANSFER, true );
curl_setopt( $ch, CURLOPT_COOKIEJAR, "/tmp/cookie.txt" );
curl_setopt( $ch, CURLOPT_COOKIEFILE, "/tmp/cookie.txt" );
$output = curl_exec( $ch );
curl_close( $ch );
$result = json_decode( $output, true );
return $result["query"]["tokens"]["logintoken"];
}
// Step 2: POST request to log in. Use of main account for login is not
// supported. Obtain credentials via Special:BotPasswords
// (https://www.mediawiki.org/wiki/Special:BotPasswords) for lgname & lgpassword
function loginRequest( $logintoken ) {
global $endPoint;
$params2 = [
"action" => "login",
"lgname" => "your_bot_username",
"lgpassword" => "your_bot_password",
"lgtoken" => $logintoken,
"format" => "json"
];
$ch = curl_init();
curl_setopt( $ch, CURLOPT_URL, $endPoint );
curl_setopt( $ch, CURLOPT_POST, true );
curl_setopt( $ch, CURLOPT_POSTFIELDS, http_build_query( $params2 ) );
curl_setopt( $ch, CURLOPT_RETURNTRANSFER, true );
curl_setopt( $ch, CURLOPT_COOKIEJAR, "/tmp/cookie.txt" );
curl_setopt( $ch, CURLOPT_COOKIEFILE, "/tmp/cookie.txt" );
$output = curl_exec( $ch );
curl_close( $ch );
echo( $output );
}
Python
#!/usr/bin/python3
"""
login.py
MediaWiki API Demos
Demo of `Login` module: Sending post request to login
MIT license
"""
import requests
USERNAME = "your_bot_username"
PASSWORD = "your_bot_password"
S = requests.Session()
URL = "https://www.mediawiki.org/w/api.php"
# Retrieve login token first
PARAMS_0 = {
'action':"query",
'meta':"tokens",
'type':"login",
'format':"json"
}
R = S.get(url=URL, params=PARAMS_0)
DATA = R.json()
LOGIN_TOKEN = DATA['query']['tokens']['logintoken']
print(LOGIN_TOKEN)
# Send a post request to login. Using the main account for login is not
# supported. Obtain credentials via Special:BotPasswords
# (https://www.mediawiki.org/wiki/Special:BotPasswords) for lgname & lgpassword
PARAMS_1 = {
'action': "login",
'lgname': USERNAME,
'lgpassword': PASSWORD,
'lgtoken': LOGIN_TOKEN,
'format': "json"
}
R = S.post(URL, data=PARAMS_1)
DATA = R.json()
print(DATA)
assert DATA['login']['result'] == 'Success'
Comme dans MediaWiki 1.27, l'utilistion du compte principal pour se connecter n'est pas prise en charge. Obtenir les certificats via Special:BotPasswords ou utiliser la méthode
clientlogin . Se connecter et rester connecter nécessite que le client gère correctement les cookies pour toutes les requêtes. Dans l'exemple ci-dessus on montre comment un objet session requests.Session() permet aux cookies de persister.
Erreurs possibles
| Code | Informations |
|---|---|
| Failed | L'authentification entrée, identifiant ou mot de passe, est incorrecte. Merci de bien vouloir réessayer. |
| Failed | Impossible de continuer la connexion. Votre session vient vraisemblablement d'expirer (ou vous ne gérez pas correctement les cookies). |
| WrongToken | Le jeton fourni est non valide |
| NeedToken | `lgtoken` non fourni |
| Aborted | connexion utilisant le mot de passe du compte principal plutôt que les mots de passe des robots |
| mustpostparams | Le paramètre suivant a été trouvé dans la chaîne de requête, mais doit figurer dans le corps de la requête POST : $1. |
Méthode 2. action=clientlogin
Doivent utiliser l'action clientlogin : (a) les applications interactives comme les éditeurs personnalisés ou les applications qui patrouillent fournissant un service sans avoir l'intention de se substituer complètement au site web, (b) les applications mobile qui ont pour but de remplacer complètement l'accès à l'interface utilisateur basé sur le web.
Néanmoins, on peut préférer utiliser OAuth s'il est disponible pour authentifier l'outil, car il est plus facile et davantage sécurisé.
Ce module est disponible depuis MediaWiki 1.27.
Documentation de l'API
Exemple 21: processus pour un wiki sans extensions particulières d'authentification
Requête POST
api.php?
Obtenir un jeton en se connectant dans la requête ci-dessus via API:Tokens.
Réponse
{
"clientlogin":{
"status":"PASS",
"username":"William"
}
}
Exemple de code
| clientlogin.py |
|---|
#!/usr/bin/python3
"""
clientlogin.py
MediaWiki Action API Code Samples
Demo of `clientlogin` module: Sending post request to login
This demo app uses Flask (a Python web development framework).
MIT license
"""
import requests
from flask import Flask, render_template, flash, request
S = requests.Session()
URL = "https://en.wikipedia.org/w/api.php"
# App config.
DEBUG = True
APP = Flask(__name__)
APP.config.from_object(__name__)
APP.config['SECRET_KEY'] = 'enter_your_secret_key'
@APP.route("/", methods=['GET', 'POST'])
def show_form():
""" Render form template and handle form submission request """
if request.method == 'POST':
username = request.form['username']
password = request.form['password']
start_client_login(username, password)
return render_template('clientlogin_form.html')
def start_client_login(username, password):
""" Send a post request along with login token, user information
and return URL to the API to log in on a wiki """
login_token = fetch_login_token()
response = S.post(url=URL, data={
'action': "clientlogin",
'username': username,
'password': password,
'loginreturnurl': 'http://127.0.0.1:5000/',
'logintoken': login_token,
'format': "json"
})
data = response.json()
if data['clientlogin']['status'] == 'PASS':
flash('Login success! Welcome, ' + data['clientlogin']['username'] + '!')
else:
flash('Oops! Something went wrong -- ' + data['clientlogin']['messagecode'])
def fetch_login_token():
""" Fetch login token via `tokens` module """
response = S.get(
url=URL,
params={
'action': "query",
'meta': "tokens",
'type': "login",
'format': "json"})
data = response.json()
return data['query']['tokens']['logintoken']
if __name__ == "__main__":
APP.run()
|
| form.html |
|---|
<!DOCTYPE html>
<title>MediaWiki Log in</title>
<link rel="stylesheet" href="static/bootstrap/css/bootstrap.min.css">
<div class="container">
<h2>MediaWiki Log in</h2>
<form action="" method="post" role="form">
<div class="form-group">
<div class="form-field">
<div class="label-field">Username</div>
<input name="username">
</div>
<div class="form-field">
<div class="label-field">Password</div>
<input type="password" name="password">
</div>
</div>
<button type="submit" class="btn btn-success">Log in</button>
</form>
<br>
{% with messages = get_flashed_messages(with_categories=true) %}
{% if messages %}
{% for message in messages %}
<div class="alert alert-info">
{{ message[1] }}
</div>
{% endfor %}
{% endif %}
{% endwith %}
</div>
<br>
</div>
</div>
|
Exemple 22: processus pour un wiki ayant des extensions d'authentification spéciales
Un wiki avec des extensions d'authentification spéciales telles que ConfirmEdit (les captchas), OpenID Connect, OATHAuth (l'authentification à deux facteurs), peuvent avoir un processus d'authentication plus compliqué. Des champs spécifiques peuvent aussi être obligatoires dans ce cas; leur description peut être récupérée par la requête API:Authmanagerinfo.
Etape 1: répondre au Captcha et sélectionner l'authentification OpenID
Cette documentation est un exemple et ne reflète pas le comportement d'une extension OpenID spécifique actuellement disponible.
Il est attendu que le client redirige le navigateur de l'utilisateur vers la
redirecttarget fournie. Le fournisseur OpenID va authentifier, et rediriger vers Special:OpenIDConnectReturn sur le wiki, ce qui va valider la réponse OpenID et ensuite rediriger vers la loginreturnurl fournie dans le premier POST fait à l'API en y ajoutant les paramètres code et state. Le client obtient de nouveau le contrôle du processus à ce point et envoie ses requêtes suivantes à l'API.| Réponse |
|---|
{
"clientlogin": {
"status": "REDIRECT",
"redirecttarget": "https://openid.example.net/openid-auth.php?scope=openid&response_type=code&client_id=ABC&redirect_uri=https://wiki.example.org/wiki/Special:OpenIDConnectReturn&state=XYZ123",
"requests": [
{
"id": "OpenIdConnectResponseAuthenticationRequest",
"metadata": {},
"required": "required",
"provider": "OpenID Connect at example.net",
"account": "",
"fields": {
"code": {
"type": "string",
"label": "OpenID Code",
"help": "OpenID Connect code response"
},
"state": {
"type": "string",
"label": "OpenID State",
"help": "OpenID Connect state response"
},
}
}
]
}
}
|
Etape 2: retour de OpenID
Maintenant le client a besoin de demander à l'utilisateur de vérifer sont application d'authentification à deux facteurs pour le code actuel, et de le renvoyer au serveur pour continuer le processus d'authentification.
| Réponse |
|---|
{
"clientlogin": {
"status": "UI",
"message": "Two-factor authentication",
"requests": [
{
"id": "TwoFactorAuthenticationRequest",
"metadata": {},
"required": "required",
"provider": "",
"account": "",
"fields": {
"code": {
"type": "string",
"label": "Code",
"help": "Two-factor authentication code"
}
}
}
]
}
}
|
Etape 3: authentification à deux facteurs
Dans certains cas il est possible de recevoir une réponse
RESTART, par exemple si l'extension OpenID Connect ne trouve pas de correspondance du compte OpenID avec un utilisateur local. Dans ce cas le client pourrait recommencer le processus de connexion depuis le début ou passer à la création de compte dans les autres cas, en passant les paramètres loginpreservestate ou createpreservestate afin de préserver un certain état.| Réponse |
|---|
{
"clientlogin": {
"status": "PASS",
"username": "Alice"
}
}
|
Notes additionnelles
- 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é
- Il est recommandé de créer un compte utilisateur séparé pour votre application. Ceci est particulièrement important si votre application prend en charge la modification automatique ou si elle fait des requêtes dont la taille est grande ou qui demandent des performances intenses. Avec cela, il est facile de suivre les modifications faites par l'application et appliquer des droits spéciaux au compte de l'application.
- Si vous envoyez une requête qui doit être faite par un utilisateur connecté, ajoutez le paramètre
assert=userà la requête que vous envoyez, pour vérifier si elle provient bien d'un utilisateur connecté. Si l'utilisateur n'est pas connecté, un code d'erreurassertuserfailedsera retourné. Voir API:Assert pour les détails. - Pour vérifier si un compte possède des droits de robot, ajoutez le paramètre
assert=botà la requête. Si le compte ne possède pas les droits des robots, un code d'erreurassertbotfailedsera retourné. Voir API:Assert pour les détails.
Voir également
- API:Déconnexion
- API:Userinfo - Renvoie les informations concernant l'utilisateur actuellement connecté
- Connexion interactive avec action=clientlogin de mwapi