SimpleSAMLphp developer information
This document is intended to provide an overview of the code for developers. It should be readable to new developers and developers who contribute as time allows and may have forgotten some details over time.
Overview
This is a living document and various sections and additions are being made as my knowledge of the SSP code and environment expands. Hopefully this can help others find their way around the code a bit quicker.
The
master
branch is where active development of the next release is
taking place. If you would like to contribute an update to and
existing release please checkout the branch for that release, for
example to make a contribution to the v2.1.1 release you would
checkout the
simplesamlphp-2.1
branch
.
Libraries that SimpleSAMLphp uses and planned changes
Many dependencies are listed in the require clause of the composer.json such as Symfony, Twig, and simplesamlphp/saml2.
As at early 2024 there is a plan to move from using robrichards/xmlseclibs to using the newly written xml-security library . The integration of xml-security started in the v5 of the saml2 library. The saml2 library is already a dependency of SimpleSAMLphp and is brought in with composer as a dependency here. .
Build process
There are two main release targets for each release: slim and full. This is done by the build-release.yml script. The full version also contains some simplesamlphp modules . The build will also include some files in the vendor directory in the full build that are not in the slim build.
If the SimpleSAMLphp code relies on other repositories on the simplesamlphp site then they are brought in using composer as shown for example for the saml2 library .
Code checks
The github actions perform some linting and checks on the php code.
The linting is done with super-linter and the php checks with phpcs.
You can run the phpcs checks locally by executing
phpcs
in the root
of the git repository. If you would like your simpler issues to be
solved for you execute
phpcbf
which will update the code to remedy
as many issues as it can.
CSS and common asset setup
The common assets such as CSS in SimpleSAMLphp, for example, that stored in public/assets/base/css/stylesheet.css comes from the simplesamlphp-assets-base package.
The dependencies are updated using github actions in simplesamlphp-assets-base. Select a recent branch such as release-2.2 and dig into the .github directory for details.
Following a simple login
The
SimpleSAML\Auth\Simple
class takes the authentication_source
name and can be used to find a login URL with
getLoginURL()
. The
getLoginURL method takes the return URL as it's only parameter. The
URL returned from
getLoginURL()
will be a request to module.php and
include the return URL information.
The module.php code
Module::process
. The
process
method uses
Symfony to dispatch the request. This may result in a call to
modules/core/src/Controller/Login.php in
Login::loginuserpass()
. The
code flows through
handleLogin()
which may call
UserPassBase::handleLogin(authstateid, username, password)
. The
handleLogin
method looks up the
$as = Auth\Source
and passes the
login credentials to the
$as->login( username, password )
method.
For an SQL based login this would be in
modules/sqlauth/src/Auth/Source/SQL.php and the
SQL::login
method.
This
login
method either returns the user attributes on success or
throws an exception on login failure.
Documentation
The core of the simplesamlphp.org website is taken from simplesamlphp.github.io . The docs subdirectory is built from the docs subdirectory of the main repository on github.
Documentation updates
There are two main repositories for documentation. The website itself comes from one place and everything that is under the "Documentation" menu uses another process https://simplesamlphp.org/docs/stable/index.html .
The website lives in https://github.com/simplesamlphp/simplesamlphp.github.io
That only has a "release" branch to commit to, which is the website as it is shown. There you'd commit to change the pages on the website, e.g. to the page /contrib/
The "docs" repo (as described in the readme of the repo) only contains the scripts that generate the docs website. In order to improve the content of the documentation themselves, you commit using the same branches used for code contributions at https://github.com/simplesamlphp/simplesamlphp .
You can address documentation updates to master https://github.com/simplesamlphp/simplesamlphp/tree/master/docs . Though it makes sense to backport them to supported releases, so each version under https://simplesamlphp.org/docs/VERSION/ will show the change. In other words, if a documentation change relates to 2.1.3 you might like to make the pull request against the simplesamlphp-2.1 branch and leave it to the team to also apply it to master and other branches in the same way that code updates work.
Documentation linting
The CI system has some linting for markdown files in place. This uses
github-action-markdown-cli
to perform the work which itself uses
markdownlint-cli
. You can install the latter with npm install and
then setup the rc file from github-action-markdown-cli from
https://github.com/nosborn/github-action-markdown-cli/blob/master/.markdownlintrc
to run the linter locally.
For example, with the markdownlintrc from above in a local file you
could use the following if you have not globally installed
markdownlint. The
--fix
option will have markdownlint fix simpler
issues for you so you can concentrate on the document and not the fine
details of the syntax formatting.
npm install markdownlint-cli
cd ./node_modules/.bin
# copy the markdown lint file to markdownlintrc
./markdownlint -c markdownlintrc /tmp/simplesamlphp-developer-information.md
./markdownlint -c markdownlintrc --fix /tmp/simplesamlphp-developer-information.md
You will probably want to make a script or alias to the above command and apply it before pushing documentation changes to github.
Making a release
The release process is documented on the wiki https://github.com/simplesamlphp/simplesamlphp/wiki/Release-process .
Dependbot
The dependbot https://docs.github.com/en/code-security/dependabot/dependabot-security-updates/configuring-dependabot-security-updates runs on the master branch and creates pull requests with recommended updates.
The release branches are updated automatically as part of the release process.