Skip to main content

Attenuators

What biscuit attenuators are ?​

One of Biscuit's core strengths is its ability to attenuate tokens by appending blocks with specific checks, effectively restricting their scope of use.

This allows developers to tailor token permissions to suit different use cases.

See this article to integrate your attenuator entity to your route's plugins.

Attenuator Example​

{
  "enabled": true,
  "id": "biscuit_attenuator_0a8d24de-426a-4baf-9b53-e9e70f38d933",
  "keypair_ref": "biscuit-keypair_dev_d25612c6-b4d0-43ed-a711-16b6c09a5155",
  "name": "New Biscuit Attenuator",
  "description": "New Biscuit Attenuator",
  "tags": [],
  "metadata": {},
  "config": {
    "checks": [
      "check if role(\"dev\")"
    ]
  }
}

Create a Biscuit Attenuator from command line​

curl -X POST \
-H 'Content-Type: application/json' \
-H 'Otoroshi-Client-Id: admin-api-apikey-id' \
-H 'Otoroshi-Client-Secret: admin-api-apikey-secret' \
'http://otoroshi-api.oto.tools:8080/apis/biscuit.extensions.cloud-apim.com/v1/biscuit-attenuators' \
-d '{
  "enabled": true,
  "id": "biscuit_attenuator_0a8d24de-426a-4baf-9b53-e9e70f38d933",
  "keypair_ref": "biscuit-keypair_dev_d25612c6-b4d0-43ed-a711-16b6c09a5155",
  "name": "New Biscuit Attenuator",
  "description": "New Biscuit Attenuator",
  "tags": [],
  "metadata": {},
  "config": {
    "checks": [
      "check if role(\"dev\")"
    ]
  }
}'

Demo - attenuating a token​

curl -X POST \
-H 'Content-Type: application/json' \
-H 'Otoroshi-Client-Id: admin-api-apikey-id' \
-H 'Otoroshi-Client-Secret: admin-api-apikey-secret' \
"http://otoroshi-api.oto.tools:8080/apis/proxy.otoroshi.io/v1/routes" \
-d '{
  "_loc" : {
    "tenant" : "default",
    "teams" : [ "default" ]
  },
  "id" : "e9336a7b-4780-4343-866b-e9005faf3115",
  "name" : "test attenuator route",
  "description" : "test attenuator route",
  "tags" : [ ],
  "metadata" : { },
  "enabled" : true,
  "groups" : [ "default" ],
  "bound_listeners" : [ ],
  "frontend" : {
    "domains" : [ "biscuit-attenuator.oto.tools" ],
    "strip_path" : true,
    "exact" : false,
    "headers" : { },
    "query" : { },
    "methods" : [ ]
  },
  "backend" : {
    "targets" : [ {
      "id" : "www.otoroshi.io",
      "hostname" : "www.otoroshi.io",
      "port" : 443,
      "tls" : true,
      "weight" : 1,
      "predicate" : {
        "type" : "AlwaysMatch"
      },
      "protocol" : "HTTP/1.1",
      "ip_address" : null,
      "tls_config" : {
        "certs" : [ ],
        "trusted_certs" : [ ],
        "enabled" : false,
        "loose" : false,
        "trust_all" : false
      }
    } ],
    "root" : "/",
    "rewrite" : false,
    "load_balancing" : {
      "type" : "RoundRobin"
    }
  },
  "backend_ref" : null,
  "plugins" : [ 
      {
      "enabled" : true,
      "debug" : false,
      "plugin" : "cp:otoroshi.next.plugins.EchoBackend",
      "include" : [ ],
      "exclude" : [ ],
      "config" : {
        "limit": 524288
      },
      "bound_listeners" : [ ]
    },
    {
      "enabled" : true,
      "debug" : false,
      "plugin" : "cp:otoroshi_plugins.com.cloud.apim.otoroshi.extensions.biscuit.plugins.BiscuitTokenAttenuator",
      "include" : [ ],
      "exclude" : [ ],
      "config" : {
        "attenuator_ref": "biscuit_attenuator_0a8d24de-426a-4baf-9b53-e9e70f38d933",
        "extractor_type": "header",
        "extractor_name": "Authorization",
        "token_replace_loc": "header",
        "token_replace_name": "attenuated-token"
      },
      "bound_listeners" : [ ]
    } 
  ]
}'

Now we can call the route with our token in Authorization header.

curl -X POST \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Biscuit: Eo0BCiMKBDEyMzQYAyIJCgcIChIDGIAIMg4KDAoCCBsSBggDEgIYABIkCAASIPCKFpXk1RhZiJoXZ0BHvsic65rH5MDSWZJt-8Rn1_XBGkDGK2CcUBcIdt7p3XmDCAEvYrFpB8w6nVPYz9vYFLUQ8M1wTSNaoP7M1UdD5S6AkA0ZJAaVkWsUHdcOgwNpiPwMIiIKIMHFnoE_nPPkAxIDCZ102kwX3z3SoXHp2xQCKik_38Fd' \
  "http://biscuit-attenuator.oto.tools:8080"

You should obtain a new attenuated token in your response's headers attenuated-token.