Skip to main content

Forges

The "forge" entity is a central component of the extension, specifically designed for the creation of "Biscuit" tokens. This generation process relies on the use of a pre-existing cryptographic key pair, thus guaranteeing the authenticity and security of the produced Biscuits.

Beyond simple generation, the forge offers capabilities for enriching and customizing Biscuits. It is possible to integrate a set of "facts," which are attributes or data associated with the Biscuit. These facts can be added manually by an operator or automatically via a "remote facts loader." The latter allows information to be retrieved from external sources, automating and standardizing the addition of contextual data to Biscuits.

Furthermore, the forge allows for the definition and application of "rules" and "checks." Rules are conditional logics that can influence the generation or validity of Biscuits, for example, by imposing certain conditions on the facts included. Checks, on the other hand, are mechanisms that ensure the conformity of the generated Biscuits with predefined criteria. They can relate to data integrity, the presence of specific facts, or compliance with certain security policies. The integration of these rules and checks directly within the forge ensures that each Biscuit produced is not only valid but also compliant with the operational and security requirements of the application.

Prerequisites​

  • A Biscuit KeyPair

  • A datalog :

    • An array of biscuit Facts (could be empty)
    • An array of biscuit Checks (could be empty)
    • An array of biscuit Resources (could be empty)
    • An array of biscuit Rules (could be empty)

Entity Configuration​

{
  "id": "biscuit-forge_5e704d23-3d25-47ec-ad53-54aebbd6121e",
  "name": "New biscuit forge",
  "description": "New biscuit forge",
  "metadata": {},
  "keypair_ref": "",
  "config": {
    "checks": [],
    "facts": [],
    "resources": [],
    "rules": [],
    "enable_ttl": true, // Boolean
    "ttl": 3600000 // Applied if enable_ttl is true
  },
  "tags": [],
  "remote_facts_ref": null
}

Demo​

Firstly, let's create a new KeyPair.

If you follow the guide to create a Keypair entity we will reuse the same entity with ID biscuit-keypair_dev_d25612c6-b4d0-43ed-a711-16b6c09a5155.

If you didn't create a keypair let's create one :

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-keypairs" \
  -d '{
  "id" : "biscuit-keypair_dev_d25612c6-b4d0-43ed-a711-16b6c09a5155",
  "name" : "New Biscuit Key Pair",
  "description" : "New biscuit KeyPair",
  "metadata" : { },
  "is_public": false,
  "pubKey" : "771F9E7FE62784502FE34CE862220586D3DB637D6A5ABAD254F7330369D3B357",
  "privKey" : "4379BE5B9AFA1A84F59D2417C20020EF1E47E0805945535B45616209D8867E50",
  "tags" : [ ]
}'

Then, we can create our new Forge entity.

The forge will use our keypair entity biscuit-keypair_dev_d25612c6-b4d0-43ed-a711-16b6c09a5155 as a reference in order to get the Public and the Private keys to generate new Eclipse Biscuit tokens.

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-forges" \
  -d '{
    "id": "biscuit-forge_dev_5e704d23-3d25-47ec-ad53-54aebbd6121e",
    "name": "New biscuit forge",
    "description": "New biscuit forge",
    "metadata": {},
    "keypair_ref": "biscuit-keypair_dev_d25612c6-b4d0-43ed-a711-16b6c09a5155",
    "config": {
      "checks": [
        "check if operation(\"read\")"
      ],
      "facts": [
        "user(\"1234\")"
      ],
      "resources": [],
      "rules": [],
      "enable_ttl": false,
      "ttl": 3600000
    },
    "tags": [],
    "remote_facts_ref": null
}'

To generate our tokens we need to call our Otoroshi API endpoint as following :

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/api/extensions/biscuit/biscuit-forges/biscuit-forge_dev_5e704d23-3d25-47ec-ad53-54aebbd6121e/_generate"

Result :

{
  "token": "Eo0BCiMKBDEyMzQYAyIJCgcIChIDGIAIMg4KDAoCCBsSBggDEgIYABIkCAASIPCKFpXk1RhZiJoXZ0BHvsic65rH5MDSWZJt-8Rn1_XBGkDGK2CcUBcIdt7p3XmDCAEvYrFpB8w6nVPYz9vYFLUQ8M1wTSNaoP7M1UdD5S6AkA0ZJAaVkWsUHdcOgwNpiPwMIiIKIMHFnoE_nPPkAxIDCZ102kwX3z3SoXHp2xQCKik_38Fd"
}

Congratulations ! You've created your first tokens forge and you will be able to reuse it as many times as you need.