399 lines
8.7 KiB
Markdown
399 lines
8.7 KiB
Markdown
# 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](https://datatracker.ietf.org/doc/html/rfc7519) 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:
|
|
|
|
```shell
|
|
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
|
|
|
|
```json
|
|
{
|
|
"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
|
|
|
|
```json
|
|
{
|
|
"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()`](../../../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
|
|
|
|
```json
|
|
{
|
|
"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()`](../../../internal/admin/proxy_route.go#getProxy)
|
|
|
|
### `PUT /api/v1/proxies/{proxyName}`
|
|
|
|
Modifier un proxy
|
|
|
|
#### Exemple de corps de requête
|
|
|
|
```json
|
|
{
|
|
"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
|
|
|
|
```json
|
|
{
|
|
"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()`](../../../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
|
|
|
|
```json
|
|
{
|
|
"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()`](../../../internal/admin/proxy_route.go#queryProxy)
|
|
|
|
## `DELETE /api/v1/proxies/{proxyName}`
|
|
|
|
Supprimer le proxy
|
|
|
|
#### Paramètres
|
|
|
|
- `{proxyName}` - Nom du proxy
|
|
|
|
#### Exemple de résultat
|
|
|
|
```json
|
|
{
|
|
"data": {
|
|
"proxyName": "myproxy"
|
|
}
|
|
}
|
|
```
|
|
|
|
#### Source
|
|
|
|
Voir [`internal/admin/proxy_route.go#deleteProxy()`](../../../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
|
|
|
|
```json
|
|
{
|
|
"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
|
|
|
|
```json
|
|
{
|
|
"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()`](../../../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
|
|
|
|
```json
|
|
{
|
|
"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()`](../../../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
|
|
|
|
```json
|
|
{
|
|
"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
|
|
|
|
```json
|
|
{
|
|
"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()`](../../../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
|
|
|
|
```json
|
|
{
|
|
"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()`](../../../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
|
|
|
|
```json
|
|
{
|
|
"data": {
|
|
"layerName": "mylayer"
|
|
}
|
|
}
|
|
```
|
|
|
|
#### Source
|
|
|
|
Voir [`internal/admin/layer_route.go#deleteLayer()`](../../../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
|
|
|
|
```json
|
|
{
|
|
"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
|
|
}
|
|
}
|
|
]
|
|
}
|
|
}
|
|
```
|