Cadoles/bouncer
Cadoles
/
bouncer
10
0
Fork 0
Code Issues 1 Pull Requests Projects Releases 3 Wiki Activity
bouncer/doc/fr/references/admin_api.md

8.7 KiB
Raw Permalink Blame History

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 valeurs reader ou writer correspondant 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
        }
      }
    ]
  }
}