SimpleSAMLphp is a native PHP application for dealing with SAML authentication

The reference implementation, not a library

SimpleSAMLphp is an application written in native PHP that deals with authentication, and the repository is described as the official repository of the SimpleSAMLphp software.

The word application is the important one. This is not a package you add to your codebase and call, it is a service you deploy that sits between your application and an identity provider, and it does the SAML part of the conversation. The topics on the repository are authentication, php, saml, saml2 and simplesamlphp, and the primary language is PHP.

That framing explains the rest of the project. The homepage is simplesamlphp.org, and the downloads link goes to a download page on the same site, so the artefacts, the documentation and the code are published from different places with the code on GitHub.

The licence is LGPL-2.1, with a COPYING file and a LICENSE file at the top of the repository, and the readme carries a short line asking people to contribute, with a link to the contributing guide.

The implementation language, the topics and the licence are the only technical facts the readme gives you. That is a deliberate choice for a project whose documentation lives elsewhere, and it is worth knowing before you start reading the repository expecting an explanation of how to configure it, because you will not find one here.

The readme is a signpost, and the documentation is on the site

The readme is short enough to read in a minute, and it contains exactly three kinds of thing.

First, the badges, and they are more informative than the prose. There is a GitHub Actions CI build status for the master branch, a codecov coverage badge, a Scrutinizer code quality score, a type coverage badge from shepherd.dev, and a BrowserStack status badge. That last one tells you the project runs its test suite in real browsers, which for an application whose job is to render login pages and SAML metadata is the kind of coverage you cannot fake.

Second, a note that the project was developed using JetBrains IDEs, with the JetBrains logo linking to their open source support programme.

Third, the links, to the SimpleSAMLphp homepage and to the downloads page, and a request to contribute.

So the documentation strategy is the opposite of the one most repositories use. The wiki and the site carry the user documentation, the repository carries the code and the contribution guide, and a newcomer is expected to start at simplesamlphp.org rather than in the git history.

That is a reasonable arrangement for a project that has been running in production at many organisations for a long time, and it does mean that the repository is best read as a directory listing with intent rather than as a narrative.

Two code trees, which tells you the project's age

The top level listing is the most informative part of the repository, and one detail stands out.

There is a src/ directory and a lib/ directory. Both are at the top level, alongside the public/ directory that an application would serve and the tests/ directory.

In a PHP project of this age, that pairing is a migration in progress. src/ holds the modern code and lib/ holds the older code that predates it, and the usual reason for the split is a gradual rewrite where the old tree is still in use and the new one is being filled in. It is a pattern you will recognise from any long-lived PHP framework.

Alongside those are the directories a deployment actually touches. There is a config/ directory for the configuration, a metadata/ directory for the identity provider and service provider metadata, and a cert/ directory for certificates. There is a modules/ directory, which in this layout is where the protocol and application support lives, kept apart from the core so that a different kind of deployment can be assembled from the same base.

Then there is a bin/ directory, which is where the command line entry points live, and a routing/ directory, and a templates/ directory for the views, and a locales/ directory for the translations, and an attributemap/ directory, and an extra/ directory for the files that go into a distribution but are not source, and a tools/ directory.

The readme has a CONTRIBUTING.md and a separate TESTING.md, which suggests that the test procedure is a document rather than a convention, which is what you would expect from a project with contributors who did not write it.

Static analysis, type coverage and browser tests

The analysis configuration is the densest part of the listing, and it says a lot about how the project is maintained.

There is a phpstan.neon for PHPStan and a second one, phpstan-dev.neon, which is a separate configuration for the development tree. There is a phpcs.xml for the coding standard, and a .php_cs.dist file for the code style fixer. There is a phpunit.xml for the test suite, a codecov.yml for the coverage configuration, and a .markdownlintrc and .markdownlintignore for the documentation.

Having two PHPStan configurations is the detail that tells you about the two code trees. A separate configuration for the development tree is what you need when the older code and the newer code have different analysis levels, or when the newer code is stricter than the older and the older cannot be fixed all at once.

Then there are the external services. Codecov for the coverage report, Scrutinizer for the code quality score, shepherd.dev for type coverage, and BrowserStack for the browser test runs. The type coverage badge is the unusual one, since it measures how much of the code is covered by static type information rather than by tests, which is the other half of knowing whether a large legacy codebase is safe to change.

The .editorconfig, .gitattributes and .github/ directories complete the setup, and the composer.json and composer.lock at the root are what pin the dependencies.

Two release lines, patched on the same day

The release list is short and it shows something worth understanding.

The recent releases are v2.4.10 from 2026-08-30, v2.5.3.1 from 2026-08-09, and v2.4.9.3 from 2026-08-09.

So there are two lines in maintenance at once, the 2.4 line and the 2.5 line, and the last two releases were published on the same day. That is the pattern of a project that treats the older line as the one most installations run, and keeps shipping it security and compatibility fixes while the newer line moves on.

The patch numbering is also informative. v2.5.3.1 carries a fourth component, which conventionally means a hotfix on top of a patch release, and v2.4.9.3 is the third iteration of the 2.4.9 patch. Those are the release numbers of a project where something broke for a subset of installations and needed a targeted correction.

The repository is not archived, and the last push was on 2026-10-13, so the code is being worked on after the August releases.

For an adopter, the practical question is which line to run. The answer is usually the one your distribution or your hosting platform packages, and the release list tells you that both are still being fixed, so neither is abandoned.

Localisation, licensing and the security file

The locales/ directory in the listing is a small item with a large implication. SimpleSAMLphp is used by organisations in many countries, and the user interface strings are translated, which means the application presents itself in the reader's language rather than only in English.

The licensing is LGPL-2.1, and the two files at the top of the tree are the COPYING file and the LICENSE file. The LGPL is a reasonable choice for an application of this kind, and it is worth understanding what it means for the two ways you might use it. If you run SimpleSAMLphp as a service, the licence obligations sit with the distribution of the service. If you embed parts of it in a product, the LGPL's dynamic linking and modification rules are what apply, and that is a question for whoever handles your licence compliance rather than something to settle from a README.

There is a SECURITY.md file at the top of the repository, which is the file to look at if you find a vulnerability. For an authentication service, the presence of a documented security contact is not a small detail, because the project handles credentials and session state and is by definition a high value target for anyone who wants into an organisation.

The rest of the tree is the working set of a deployable application: config/ for the configuration, metadata/ for the provider metadata, cert/ for the certificates, templates/ for the views, public/ for the served assets, and the docs/ directory for the documentation that the readme points you towards.

Editorial conclusion

Adopt SimpleSAMLphp when you need a SAML service provider or identity provider and you want the reference implementation rather than a framework you assemble yourself. Do not adopt it if you are looking for a modern application framework, because the repository carries both a src/ tree and a lib/ tree, which is the shape of a project that grew over a decade rather than one designed recently. Verify first which release line you install, because the 2.4 and 2.5 lines are both receiving patches, and read the documentation on the project site, since the readme in the repository deliberately contains almost nothing about configuration.

Frequently asked questions

Official sources

1. License: LGPL-2.1
2. Project website
3. README
4. Releases
5. simplesamlphp/simplesamlphp on GitHub