Blackfire Security Model

Security is a first class feature of Blackfire. Being production-ready means having precise control over who is allowed to profile your applications.

If you already configured Blackfire locally, you must have read about server and clientcredentials. But what are they useful for?

Let’s look at how the security mechanism works. Step by step, here is what happens when you ask for a profile:

1. Your client credentials (id + token) are first used to fetch a signed token from the API. The signed token proves that you are allowed to profile for a set of server ids;
2. The signed token is presented to the PHP engine, using either an ENV variable or an HTTP header;
3. The PHP engine connects to the agent and forwards the signed token to it;
4. The Blackfire Agent verifies the signature of the token and rejects the request if it does not match. Since anyone with a Blackfire account can create a valid signed token, this only proves that the signed data can be trusted;
5. The Blackfire Agent then verifies that its server_id setting is in the server ids list bundled in the token. This is the proof that enables profiling;
6. In case you did configure the blackfire.server_id setting in php.ini, the PHP engine can handle steps 4. and 5. itself;
7. If the Blackfire Agent confirms that the signed token is valid for its server credentials, then profiling is enabled;
8. When the Blackfire Agent receives the final sample of profiling data, it connects to the Agent API of blackfire.io using its server credentials (id + token), then pushes the data;
9. After accepting the server credentials provided by the Agent, the API then verifies again the signed token, using the same process as in steps 4 and 5;
10. Every hour, the Blackfire Agent also connects to the blackfire.io Agent API to fetch the fresh public keys that should be used to check token signatures.

Tokens are signed using ED25519 cryptography. This gives us short signatures that are easily embedded in HTTP headers while ensuring state-of-the-art security and performance.

This security model is very flexible. It allows many authorization schemes and you already know two of them: using one account for one server (or set of servers if all of them are configured with the same server credentials); or several user accounts for one single server.

So, how secret should your credentials be?

Your client credentials allow fetching signed authorization tokens. Leaking them would allow anyone to profile any of your servers. You should keep them safe. The token-part especially must be kept secret. If you leaked it by mistake, you can and should regenerate it.

Your server credentials do not need to be secret. The Agent API is a very restricted area were credentials must match a signed token. Your application server is safe since it also requires such a signed token to trigger profiling. If you leak your server credentials, someone else can only grant you profiling access on their servers, no big deal.

Happy safe profiling!