"BOSS, YOU DON'T GIVE THAT AWAY": 2 things everyone ends up not building: digital certificate login and NIF+name verification with the Spanish Tax Agency
At Iberfácil we work every day with digital identity, certificates, public administrations and data that has to be right. And there are two problems that anyone building software in Spain ends up facing.
At Iberfácil we work every day with digital identity, certificates, public administrations and data that has to be right. And there are two problems that anyone building software in Spain ends up facing.
How do I let someone log in to my application with their digital certificate instead of a password?
How do I automatically check that the NIF (Spanish tax ID) and name a customer gives me are the ones on record with the Spanish Tax Agency?
We needed to solve them, and we did. We have published the solution so that anyone can use it.
We have released eidas-cert-auth and es-aeat-vnif: one lets people log in to your application with their digital certificate, validated against the EU trusted lists, and the other asks the Spanish Tax Agency whether a NIF and a name go together. MIT licence, no API of ours in the middle, no fee, no small print.
I hadn't touched real code in months.
Meetings, quotes, contracts, payroll, customers, suppliers, more meetings. The usual when you build a company: you end up being more of an administrator than anything else. You open the editor on a Tuesday afternoon, the phone rings, and you close it three weeks later.
This year we ran into two problems we had been dodging for a while, and I decided I would do those two myself. Not out of nostalgia. Well, a little.
And when I said that we were also going to publish them as open source, the reaction at home was more or less:
"MARCO, THIS HAS COST US WEEKS. ARE YOU SERIOUSLY GOING TO GIVE IT AWAY?"
Yes. And I'll tell you why at the end of the article. First, what they are.
THE TWO PROBLEMS EVERY DEVELOPER OF WEB APPLICATIONS FOR SPANISH COMPANIES ENDS UP FACING
ONE: knowing who is logging in. Passwords get forgotten, reused and stolen. When an accounting firm, a law firm or a public administration opens a private area, it needs to know whether the person logging in is the customer, someone acting on behalf of a company, or someone trying to impersonate them. A name and a NIF typed into a form prove nothing. A digital certificate does. The problem is that validating it properly takes far more work than it seems: chain of trust, signed European trusted lists, revocation, different profiles depending on the operation… Almost everyone ends up building a half-done version that "works".
TWO: knowing whether that NIF belongs to who they say, and whether the data is correct. A customer's or supplier's details arrive handwritten, copied from an email or dictated over the phone. Before invoicing, onboarding someone or including them in an information return, you want to know that the NIF exists and matches that name, and that the name is correct, complete and properly spelled. Otherwise the error doesn't show up today: it shows up in form 347 or in the SII (the Spanish real-time VAT reporting system), when there is nothing nice you can do about it any more.
We solved them for ourselves. And we have published both under the MIT licence.
First of all, a clarification that saves confusion: they are two different things and neither depends on the other. One authenticates (who is logging in). The other verifies (whether that NIF and that name exist together in the tax register). You can use just one, or both.
EIDAS-CERT-AUTH: DIGITAL CERTIFICATE AUTHENTICATION
In plain language. It lets people log in to your website or application with their digital certificate: FNMT, the Spanish electronic ID card (DNIe) or qualified providers from other EU countries. And it doesn't just read it:
It checks the official, signed EU trusted list to know which authorities and providers are accepted.
It checks that the certificate is valid, that its chain reaches an accepted authority and that it is fit for the operation being requested.
It checks whether it has been revoked. And if it can't check, it denies access by default. That last point looks like a detail and it is half the library.
It extracts the certificate data: name, NIF or equivalent identifier and, when present, the representation of a company.
What it doesn't do: it doesn't perform an electronic signature and it doesn't decide permissions. Your application still decides which account an identity belongs to and whether a declared representation is enough for the specific procedure.
The technical detail. PHP 8.2 or later with curl, dom, libxml and openssl, plus the openssl binary. The core doesn't depend on any framework; it ships a command line and an optional Laravel adapter.
composer require iberfacil/eidas-cert-authThe trusted lists are downloaded and verified automatically into a private store. By default only Spain (ES) is accepted; other countries are added with "countries".
vendor/bin/eidas-cert-auth trust-list:update --store=/path/to/private-data/trust --region=ES --dry-run
vendor/bin/eidas-cert-auth trust-list:update --store=/path/to/private-data/trust --region=ES
vendor/bin/eidas-cert-auth doctor --store=/path/to/private-data/trustValidating a certificate without Laravel, once the validator is built:
$result = $validator->validate($pemFromServerVariable);
if (! $result->valid) {
// Use $result->reason; do not log the PEM or the identity by default.
}And in Laravel, with one profile per route:
Route::post('/sign', $handler)->middleware('eidas.cert:signature');
ES-AEAT-VNIF: VERIFY NIF AND FULL NAME AGAINST THE SPANISH TAX AGENCY: INDIVIDUALS AND COMPANIES
In plain language. The Spanish Tax Agency (AEAT) offers a third-party NIF verification service (VNifV2). This package queries it for you: you give it a NIF and a name or company name, and it tells you whether the NIF exists and matches that name, what the exact name in the register is when yours is approximate or only similar, and whether it is listed as deregistered or revoked. One at a time or in batches.
You need your own electronic certificate —for an individual, for the representative of a legal entity or an entity seal— in .p12 or .pfx. The query goes from your server to the AEAT, under your identity: use it only for your own customers, suppliers and procedures.
What it doesn't do: it doesn't prove that the person giving you the data is who they say they are. It only confirms that the NIF and the name exist together in the register. (For the other thing, see the package above.)
The technical detail.
composer require iberfacil/es-aeat-vnif
vendor/bin/aeat-vnif doctor
vendor/bin/aeat-vnif check 00000000T --nombre=Zefira --apellido1=Lumina --apellido2=Peralvillo
vendor/bin/aeat-vnif batch clientes.csvThe CSV is separated by ;, one line per taxpayer. From code:
use Iberfacil\AeatVnif\VnifClient;
use Iberfacil\AeatVnif\Data\TaxpayerName;
$client = VnifClient::create('/etc/aeat/certificado.p12', getenv('AEAT_VNIF_CERT_PASSWORD'));
$result = $client->check('00000000T', TaxpayerName::naturalPerson('Zefira', 'Lumina', 'Peralvillo'));
$result->isIdentified(); // true
$result->censusName; // 'LUMINÁ PERALVILLO ZÉFIRA' (as it appears in the register)The service accepts up to 10,000 taxpayers per request and the package splits the batches by itself.
Responses are matched by NIF, never by name, and a "NOT PROCESSED" doesn't bring down the batch: it is flagged to be retried. There is a Laravel adapter with a facade, Artisan commands, events and optional caching. The password always lives in the environment, never in the code, and the package logs nothing on its own: you decide what gets audited.
WHO IS IT FOR?
Well, in reality all kinds of organisations, from the smallest SME to the largest company, can benefit from these packages. Being able to check that a first name, surnames and an ID number match, are correctly spelled and complete exactly as they appear in the AEAT register, and making it easy for customers, employees and partners to identify themselves with a digital certificate in corporate applications, are useful to practically anyone. However, some organisations, by their nature, can benefit especially:
Accounting and advisory firms: letting clients log in to their private area with a certificate, and reviewing a file of new registrations before actually registering them.
Law firms: telling the individual apart from someone acting as a company's representative, and getting the exact name as it appears at the AEAT.
Invoicing and administration: avoiding invoices with a non-existent NIF or a company name that doesn't match.
Compliance and supplier onboarding: checking that the company tax ID (CIF) and the company name go together, and keeping evidence of the check.
Platforms and public administrations: identifying the applicant in a procedure and requiring a stricter profile for sensitive operations.
AND NOW, FINALLY… WHY ARE WE GIVING IT AWAY?
Back to the criticism at the start, which was fair.
It took us real work. And that is exactly why: if this cost us, it is costing others the same, right now, in another office, solving exactly the same problem for the umpteenth time in this country. That is not a competitive advantage. That is infrastructure, and infrastructure duplicated a thousand times is time thrown away, a thousand times.
Our business is not charging to validate a certificate. It is what we build on top.
They are free software under the MIT licence: no Iberfácil API in the middle, no fee and no need to sign up for anything with us. Your server talks directly to the EU trusted lists and to the AEAT. If we disappear tomorrow, your integration keeps working. That is part of the deal too.
And there is a less romantic reason: code that handles certificates and personal data has to be reviewable. In the open, anyone can review it. If you find a bug in mine, you are doing me a favour, not criticising me.
I sincerely believe that Spanish companies can contribute a great deal more open source in general. But around dealing with public administrations, digital identity and eIDAS, we are still in nappies as far as open source goes. We complain a lot about how hard it is to integrate with the public sector —sometimes rightly— but then everyone keeps their solution in a drawer. This is our grain of sand.
And, to be honest: I enjoyed doing it enormously. I had forgotten what it feels like to close a problem for real, with green tests, instead of closing a meeting. If you are a CEO, CTO or founder and haven't written any code in months: pick a small problem and do it yourself. You won't regret it.
HOW CAN YOU HELP? (Here comes the "selfish" part)
If you found it useful, give the repos a star. It sounds silly, but it is what makes the next person who hits this problem at two in the morning find it instead of writing it again from scratch.
Issues and pull requests are welcome. Both repositories explain the rules in their CONTRIBUTING.md: short branch from main, tests that don't touch the network and always made-up data, never real certificates or real data. If you find a security issue, don't open a public issue: follow each repository's SECURITY.md.
And if you work at an accounting firm, a law firm, a platform or a public administration and this solves something for you: pass it on to your development team. Or if you are the one who develops, pass it on to your boss. It's two composer requires and it costs nothing.
Marco Gavilán
CEO of Iberfácil
29 September 2026