+ SimpleSAMLphp developer information +
+ +-
+
-
+
+ SimpleSAMLphp developer information
+
+
-
+
- + + Overview + + +
- + + Libraries that SimpleSAMLphp uses and planned changes + + +
- + + Build process + + +
- + + Code checks + + +
- + + Following a simple login + + +
-
+
+ Documentation
+
+
-
+
- + + Documentation updates + + +
- + + Documentation linting + + +
+
+
+ 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.
+
+ 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. +
+