Le Wiki Koumbit
API
AlternC a une API qui permet la gestion scriptée des comptes. Il faut installer le package de l'API, alternc-api pour que ça soit disponible.
L'état du code de l'API est ... "pas fini" .. et donc il y a des bugs qui empêchent le bon fonctionnement qu'il faut patcher upstream. Aussi, plusieurs détails seraient à corriger avant de considérer qu'on a une version 1.0 de cette API là (comme la structure des deux tables de base de données à réviser et des fonctionnalités manquantes). Aussi, l'API n'a pas vraiment de bonne documentation qui permettrait de l'utiliser facilement.
Donc dans l'état actuel des choses (2020-06), on ne souhaite pas publiciser l'existance de l'API à nos utilisatrices.teurs.
Ça reste un outil intéressant pour automatiser certaines choses quand l'API est semi-fonctionnelle.
Cette page sert donc à documenter comment on peut utiliser l'API.
Gestion des accès via l'API
Shared secret
L'API d'AlternC ajoute le concept d'un "shared secret". C'est en pratique un 2ème type de mot de passe pour le compte, qui donne accès à toutes les mêmes choses que l'interface web (en théorie. il manque p-e quelques foncitonnalités et certaines sont p-e brisées).
Le "shared secret" d'AlternC c'est ce que tous les autres APIs appellent "token". Par contre le "shared secret" n'a pas d'expiration, ce qui est problématique en soit!
Pour accéder à l'API il faut donc d'abord créer un "shared secret", mais AlternC n'a pas encore d'interface web pour la gestion de cette information. Donc il faut qu'on l'injecte manuellement dans la base de données.
Premièrement, sur votre ordinateur, générez un nouveau mot de passe de 32 caractères de long qui ne contient que des lettres et des numéros:
python3 -c "import random; import string; print(''.join(random.choice(string.ascii_letters + string.digits) for i in range(32)))"
Maintenant connectez vous à la base de données d'alternc. On va commencer par identifier le uid du compte:
SELECT uid FROM membres WHERE login='nomducompte';
et insérez maintenant le mot de passe "shared secret":
INSERT INTO sharedsecret (uid, secret) VALUES ('$UIDDUCOMPTE', '$LEMOTDEPASSE');
Tokens d'authentification
Une fois qu'on a un "shared secret", les personnes qui ont ce compte pourront maintenant l'utiliser, comme on le verra plus bas, pour s'authentifier et obtenir un "token".
Les "token" sont un troisième type de mot de passe qui encore une fois donne accès à toutes les fonctionnalités du compte. Cette fois-ci AlternC a décidé de doter celui-ci d'une date d'expiration. Par contre AlternC ne vérifie pas la date d'expiration et donc ceux-ci restent valides à l'infini!
Les tokens sont générés automatiquement lorsqu'on s'authentifie avec le "shared secret" et sont retournés dans la réponse HTTP.
C'est avec un token qu'on pourra faire des requêtes directement sur les "end points" de l'API pour prendre différentes actions sur le compte.
Requêtes POST
Tous les exemples plus bas utilisent des requêtes GET pour simplifier les exemples. Par contre, comme les requêtes GET sont logguées au complet, pas mal d'information sensible va se retrouver dans les logs. Donc si on automatise les modifications sur des comptes, l'utilisation de requêtes POST est recommandée.
Pour faire des requêtes POST à la place, on peut faire une requête de type POST sur la même URL -- donc par exemple https://instance-alternc.koumbit.net/api/rest/mail/delete pour effacer une mailbox -- et passer les valeurs dans le format "normal" d'une requête POST. donc par exemple avec curl ça donnerait qqch comme ça:
curl -d 'token=tokendelogin&dom_id=3' 'https://instance-alternc.koumbit.net/api/rest/mail/delete'
Actions
Authentification (login)
Avant de faire quoi que ce soit avec l'API, il faut obtenir un token d'authentification.
Le login fonctionne seulement avec shared secret dans l'API (et encore.. il faut patcher le code pour que ça fonctionne).
curl 'https://instance-alternc.koumbit.net/api/auth/sharedsecret?login=username&secret=thesupersharedsecret'
- récupérer le token dans la réponse. la réponse est formattée en json. l'élément du tableau s'appelle "token".
- par défaut un token est valide pour 1 mois.
- c'est une période beaucoup trop longue qu'il faudra probablement corriger.
Domaines
Trouver l'ID d'un nom de domaine
Pour faire la majorité des opérations sur les mailboxes, il faut connaître l'ID du nom de domaine dans lequel on gère les mailboxes. On peut demander à l'API de nous donner le numéro.
curl 'https://instance-alternc.koumbit.net/api/rest/domain/find?token=thetokenfromauth'
La réponse contiendra encore une entrée "code" qui indique une erreur si ça n'est pas null et "message" qui est le message d'erreur dans ce cas là. L'entrée "content" est ce qui nous intéresse. C'est une structure JSON qui associe un nom de domaine (clef) avec son information comme valeur.
Un exemple de réponse (formatté avec jq pour être lisible):
{
"code": null,
"message": null,
"content": {
"example.com": {
"id": "3",
"compte": "2003",
"domaine": "example.com",
"gesdns": "1",
"gesmx": "1",
"noerase": "0",
"dns_action": "OK",
"dns_result": "0",
"zonettl": "86400"
}
},
"metadata": null
}
donc on peut extraire l'ID du domaine en extrayant l'entrée (syntaxe jq pour parcourir la structure) .content["example.com"]["id"]
Emails
Créer une mailbox
Pour créer une mailbox, on doit faire trois actions une après l'autre.
curl 'https://instance-alternc.koumbit.net/api/rest/mail/create?token=tokenfromlogin&dom_id=3&mail=test'
note: on spécifie déjà le # de domaine donc le nom de la mailbox doit être sans @domain.tld
- important: le uid de la mailbox est retourné dans le champs "content" de la réponse de l'API. On pourra réutiliser cet ID de mailbox là pour les appels subséquent.
- ici pour l'exemple, on suppose que l'API nous aurait retourné "7" comme ID de mailbox.
après la création il faut rouler aussi un call à la fonction update sinon la mailbox n'existe pas:
curl 'https://instance-alternc.koumbit.net/api/rest/mail/update?token=tokendelogin&mail_id=7&islocal=true"amb=0&recipients='
après ça il faut faire également un appel à un changement de mot de passe pour configurer le mdp de la box. (voir #Changer_le_mot_de_passe_d.27une_mailbox).
Trouver l'ID d'une mailbox
Pour toutes les opérations sauf pour la création d'une nouvelle mailbox, on doit en premier lieu trouver c'est quoi l'ID de la mailbox pour pouvoir l'utiliser dans les appels d'API nécessaires.
curl 'https://instance-alternc.koumbit.net/api/rest/mail/getAll?token=tokendulogin&dom_id=3&search=nomdelamailbox'
dans la réponse, il faudra fouiller sous l'élément content qui sera un tableau d'arrays, et trouver l'élément qui a address avec la valeur qu'on cherche. sous cet élément là, l'élément id contient l'ID de la mailbox. Un exemple visuel vaut mille mots; voici un exemple de réponse à une recherche (formatté avec jq pour que ça soit lisible):
{
"code": null,
"message": null,
"content": [
{
"id": "6",
"0": "6",
"address": "test",
"1": "test",
"password": null,
"2": null,
"enabled": "1",
"3": "1",
"mail_action": "OK",
"4": "OK",
"domain": "example.com",
"5": "example.com",
"quota": "0",
"6": "0",
"quotabytes": "0",
"7": "0",
"used": null,
"8": null,
"islocal": "1",
"9": "1",
"type": "",
"10": "",
"recipients": null,
"11": null,
"lastlogin": "0000-00-00 00:00:00",
"12": "0000-00-00 00:00:00",
"domain_id": "3",
"13": "3"
}
],
"metadata": null
}
Changer le mot de passe d'une mailbox
curl 'https://instance-alternc.koumbit.net/api/rest/mail/passwd?token=tokendelogin&mail_id=7&password=superpasword'
Activer/Désactiver une mailbox
Activer:
curl 'https://instance-alternc.koumbit.net/api/rest/mail/enable?token=tokendelogin&mail_id=7'
Désactiver:
curl 'https://instance-alternc.koumbit.net/api/rest/mail/disable?token=tokendelogin&mail_id=7'
Détruire une mailbox
curl 'https://instance-alternc.koumbit.net/api/rest/mail/delete?token=tokendelogin&mail_id=7'