8.7 KiB
8.7 KiB
API d'administration
Authentification
L'ensemble des appels aux APIs HTTP du service bouncer-admin sont authentifiées via l'utilisation d'un jeton JWT signé par la clé privée du serveur.
Le jeton d'accès doit être transmis avec l'ensemble des appels aux points d'entrée via l'entête HTTP Authorization en respectant la forme suivante:
Authorization: Bearer <jwt>
Génération d'un jeton d'authentification
La génération d'un jeton d'authentification s'effectue via la commande suivante:
bouncer auth create-token --subject "<subject>" --role "<role>"
Où:
"<subject>"est une chaîne de caractère arbitraire ayant pour objectif d'identifier de manière unique l'utilisateur associé au jeton;"<role>"peut prendre une des deux valeursreaderouwritercorrespondant aux droits suivants respectifs:- droit en lecture sur l'ensemble des entités (proxy, layer);
- droit en lecture ET en écriture sur l'ensemble des entités.
Points d'entrée
POST /api/v1/proxies
Créer un nouveau proxy
Exemple de corps de requête
{
"name": "myproxy", // OBLIGATOIRE - Nom du proxy
"to": "https://www.cadoles.com", // OBLIGATOIRE - Site distant ciblé par le proxy
"from": ["*"] // OPTIONNEL - Liste de patrons de filtrage associés au proxy
}
Exemple de résultat
{
"data": {
"proxy": {
"name": "myproxy",
"weight": 0,
"enabled": false,
"to": "https://www.cadoles.com",
"from": ["*"],
"createdAt": "2018-12-10T13:45:00.000Z",
"updatedAt": "2018-12-10T13:45:00.000Z"
}
}
}
Source
Voir internal/admin/proxy_route.go#createProxy()
GET /api/v1/proxies/{proxyName}
Récupérer les informations complètes sur un proxy
Paramètres
{proxyName}- Nom du proxy
Exemple de résultat
{
"data": {
"proxy": {
"name": "myproxy",
"weight": 0,
"enabled": false,
"to": "https://www.cadoles.com",
"from": ["*"],
"createdAt": "2018-12-10T13:45:00.000Z",
"updatedAt": "2018-12-10T13:45:00.000Z"
}
}
}
Source
Voir internal/admin/proxy_route.go#getProxy()
PUT /api/v1/proxies/{proxyName}
Modifier un proxy
Exemple de corps de requête
{
"to": "https://www.cadoles.com", // OPTIONNEL - Site distant ciblé par le proxy
"from": ["mylocalproxydomain:*"], // OPTIONNEL - Liste de patrons de filtrage associés au proxy
"weight": 100, // OPTIONNEL - Poids à associer au proxy
"enabled": true // OPTIONNEL - Activer/désactiver le proxy
}
Exemple de résultat
{
"data": {
"proxy": {
"name": "myproxy",
"weight": 100,
"enabled": true,
"to": "https://www.cadoles.com",
"from": ["mylocalproxydomain:*"],
"createdAt": "2018-12-10T13:45:00.000Z",
"updatedAt": "2020-10-02T15:09:00.000Z"
}
}
}
Source
Voir internal/admin/proxy_route.go#updateProxy()
GET /api/v1/proxies?names={name1,name2,...}
Lister les proxies existants
Paramètres
{names}- Optionnel - Liste des noms de proxy à appliquer en tant que filtre
Exemple de résultat
{
"data": {
"proxies": [
{
"name": "myproxy",
"weight": 0,
"enabled": false,
"createdAt": "2018-12-10T13:45:00.000Z",
"updatedAt": "2018-12-10T13:45:00.000Z"
}
]
}
}
Source
Voir internal/admin/proxy_route.go#queryProxy()
DELETE /api/v1/proxies/{proxyName}
Supprimer le proxy
Paramètres
{proxyName}- Nom du proxy
Exemple de résultat
{
"data": {
"proxyName": "myproxy"
}
}
Source
Voir internal/admin/proxy_route.go#deleteProxy()
POST /api/v1/proxies/{proxyName}/layers
Créer un nouveau layer pour un proxy donné
Paramètres
{proxyName}- Nom du proxy sur lequel créer le layer
Exemple de corps de requête
{
"name": "mylayer", // OBLIGATOIRE - Nom du layer
"type": "<layer_type>", // OBLIGATOIRE - Type du layer, voir doc/fr/references/layers
"options": {} // OPTIONNEL - Options associées au layer, voir doc/fr/references/layers
}
Exemple de résultat
{
"data": {
"layer": {
"name": "mylayer",
"type": "<layer_type>",
"enabled": false,
"weight": 0,
"options": {},
"createdAt": "2018-12-10T13:45:00.000Z",
"updatedAt": "2018-12-10T13:45:00.000Z"
}
}
}
Source
Voir internal/admin/layer_route.go#createLayer()
GET /api/v1/proxies/{proxyName}/layers/{layerName}
Récupérer les informations complètes sur un layer
Paramètres
{proxyName}- Nom du proxy parent{layerName}- Nom du layer
Exemple de résultat
{
"data": {
"layer": {
"name": "mylayer",
"type": "<layer_type>",
"enabled": false,
"weight": 0,
"options": {},
"createdAt": "2018-12-10T13:45:00.000Z",
"updatedAt": "2018-12-10T13:45:00.000Z"
}
}
}
Source
Voir internal/admin/layer_route.go#getLayer()
PUT /api/v1/proxies/{proxyName}/layers/{layerName}
Modifier un layer
Paramètres
{proxyName}- Nom du proxy parent{layerName}- Nom du layer
Exemple de corps de requête
{
"weight": 100, // OPTIONNEL - Poids à associer au layer
"enabled": true, // OPTIONNEL - Activer/désactiver le layer
"options": {} // OPTIONNEL - Modifier les options associées au layer, voir doc/fr/references/layers
}
Exemple de résultat
{
"data": {
"layer": {
"name": "mylayer",
"type": "<layer_type>",
"enabled": false,
"weight": 0,
"options": {},
"createdAt": "2018-12-10T13:45:00.000Z",
"updatedAt": "2018-12-10T13:45:00.000Z"
}
}
}
Source
Voir internal/admin/layer_route.go#updateLayer()
GET /api/v1/proxies/{proxyName}/layers?names={name1,name2,...}
Lister les layers existants
Paramètres
{proxyName}- Nom du proxy parent{names}- Optionnel - Liste des noms de proxy à appliquer en tant que filtre
Exemple de résultat
{
"data": {
"layers": [
{
"name": "mylayer",
"weight": 0,
"enabled": false,
"createdAt": "2018-12-10T13:45:00.000Z",
"updatedAt": "2018-12-10T13:45:00.000Z"
}
]
}
}
Source
Voir internal/admin/layer_route.go#queryLayers()
DELETE /api/v1/proxies/{proxyName}/layers/{layerName}
Supprimer le layer
Paramètres
{proxyName}- Nom du proxy parent{layerName}- Nom du layer
Exemple de résultat
{
"data": {
"layerName": "mylayer"
}
}
Source
Voir internal/admin/layer_route.go#deleteLayer()
GET /api/v1/definitions/layers?types={type1,type2,...}
Lister les définitions des types de layer disponibles.
Paramètres
{types}- Optionnel - Liste des types de layer à appliquer en tant que filtre
Exemple de résultat
{
"data": {
"definitions": [
{
"type": "queue",
"options": {
"type": "object",
"properties": {
"capacity": {
"title": "Capacité d'accueil de la file d'attente",
"default": 1000,
"type": "number",
"minimum": 0
},
"keepAlive": {
"title": "Temps de vie d'une session utilisateur sans activité",
"description": "Durée sous forme de chaîne de caractères. Voir https://pkg.go.dev/time#ParseDuration pour plus d'informations.",
"default": "1m",
"type": "string"
},
"matchURLs": {
"title": "Liste de filtrage des URLs sur lesquelles le layer est actif",
"description": "Par exemple, si vous souhaitez limiter votre layer à l'ensemble d'une section '`/blog`' d'un site, vous pouvez déclarer la valeur `['*/blog*']`. Les autres URLs du site ne seront pas affectées par ce layer.",
"default": ["*"],
"type": "array",
"items": {
"type": "string"
}
}
},
"additionalProperties": false
}
}
]
}
}