Visitar URL original
List of tasks · simplesamlphp/simplesamlphp Wiki · GitHub
Skip to content

List of tasks

Jump to bottom
Tim van Dijen edited this page Feb 28, 2023 · 44 revisions

This is a list of tasks that need to be done in SimpleSAMLphp, from simple things to more advanced features.

Easy

  • Switch all PHP files to use spaces instead of tabs (PSR-2 compliance, issue #458).

  • Switch all PHP classes to use namespaces.

More info

Currently, class names are using the old [PSR-0](http://www.php-fig.org/psr/psr-0/) convention, separating folder and class names with underscores. So for example, for a class defined in `lib/SimpleSAML/Session.php`, the class name is `SimpleSAML_Session`, with `lib/` being the root directory for class names. Similarly, the class `SimpleSAML_Auth_Source` is located in `lib/SimpleSAML/Auth/Source.php`.

For classes inside modules, we used to prepend `sspmod_modulename_` to the class name (including the path to it), so that the class located in `modules/core/lib/Auth/Source/AdminPassword.php` is then named `sspmod_core_Auth_Source_AdminPassword`.

This is the old naming convention, which is no longer used. New classes are created using namespaces, and old classes are migrated to use namespaces too. The ultimate goal is to have all our classes following the [PSR-4 standard](http://www.php-fig.org/psr/psr-4/). An autoloader is in place to allow us load classes regardless of whether they are using namespaces or not. That way, when we migrate a class to use namespaces, we can do it without breaking all existing code using the old class name, and slowly change that code without having huge, monolithic commits.

Migrating a class to namespaces is, therefore, a two-step process:

  • Add the corresponding namespace at the top of the file:
    namespace SimpleSAML\Foo; // for classes located in lib/SimpleSAML/Foo/
    or
    namespace SimpleSAML\Module\modulename\Bar; // for classes located in modules/modulename/lib/Bar/
  • Changing the name of the class. So, for `SimpleSAML\Foo\Bar`:
    class Bar
    {

Some classes, like `SimpleSAML\Logger` or `SimpleSAML\Module` have already been migrated to use namespaces. Use them as a reference. If you want to take the chance to rename a class whose original name does not make much sense or is misleading, you can also do that. In that case, remember to add a mapping to the autoloader function in `lib/_autoload_modules.php`. You will need to add a line to the definition of the `$renamed` array, stating the original name and the new name *following the old naming convention*. So if we want to move the class in `lib/SimpleSAML/Foo/Bar.php` to `lib/SimpleSAML/Bar/Foo.php`, then we need a line like: ` 'SimpleSAML_Foo_Bar' => 'SimpleSAML_Bar_Foo',`. This is because the autoloader will first rename the class, then look for it and create the appropriate aliases.

  • Reformat all PHP files to be PSR-2 compliant (apart from whitespace), paying special attention to our contribution guidelines.

  • Get rid of all concatenated translation strings, like $this->t('{something:'.$variable.'}');. Those are difficult to migrate because we don't know the possible values or we can't parse it easily in an automated way. Try to simplify them to a single string whenever is possible.

  • Scrutinize existing modules for problems in their web pages / templates or translation strings, and report the issues found. Mostly, the main issue is templates implementing logic, even entire functions, that are later used. Twig templates cannot implement more than very basic logic, so that should be moved to the PHP scripts using the templates.

  • Find all translations of variables. If the content of the variable is always a string, make sure to surround it with braces, making it explicit what dictionary to use to look for the tag. Note that sometimes we use t() passing an array with translations as a parameter. That is useful when we need to translate some string whose translations are not included in SimpleSAMLphp (e.g. the name of a SAML entity on its metadata). Those cases cannot be simplified.

  • Namespace translation tags, or document why that is not possible. See issue #505, which has an example.

  • Find uses of SimpleSAML_XHTML_Template::t() passing an array as first parameter, instead of a tag. Remove them by getting the current language and doing the translation manually.

More info This is useful when we want to translate strings whose translations are coming from outside SimpleSAMLphp (i.e. metadata). In those cases, though, it doesn't make much sense to use the translation infrastructure, as the translation is as simple as picking one of the elements of the array corresponding to the current language. The current code is complicated and makes us support legacy behavior that's difficult to change for a better internationalization system.

We need to find all occurrences of this, and stop calling `t()` for those translations, performing it directly. For example, if we have an array variable with the translations for the name of a SAML entity, named `$spname`, we can get the current language from the template by calling `$template->getLanguage()` and use that to index the array: `$translated_name = $spname[$template->getLanguage()];`. Then we can just pass the translated string to the template to use it: `$template->data['SPName'] = $translated_name;`.

  • [?] Write an authproc filter that sanitizes the attributes of a user, trimming white space removing empty values and attributes, etc.

  • Make it explicit in the documentation that the userid.attribute configuration option is used before running any authentication processing filters, and therefore the attribute specified must be available right after authentication.

Intermediate

  • Add support for the REFEDS Research & Scholarship and eduGAIN Code of Conduct entity categories to the entitycategories module.

  • Remove logic from templates. Only very basic logic should be done in templates, like if clauses or loops. See issues #454 and #485 for more information about this.

  • Migrate existing templates to twig to help discover what's missing from the base templates. Add issues accordingly.

  • Document how to migrate templates to twig in the wiki, including a list of solutions for common problems.

  • Create unit tests. Expand the current code coverage by adding one or more unit tests under tests/. To run the test suite, invoke php vendor/phpunit/phpunit/phpunit --configuration tools/phpunit. PhpUnit also allows you to generate coverage information to find what code lacks testing.

  • Clean up the translations in the consentAdmin module. See issue #465.

  • Add an interface for errors, requiring two methods: getTitle() and getDescription(). Implementing that interface allows us to have errors that we can inquiry for both title and description, in order to show them. We basically want to remove the necessity of the SimpleSAML\Error\ErrorCodes-class so that all errors are passed as error-objects and not as errorcodes in strings.

  • Add classes implementing the new error interface, corresponding to every error found in dictionaries/errors.definition.json.

  • Write an authproc filter in the saml module to handle the eduPersonTargetedID attribute. We should always convert _eduPersonTargetedID_s to SAML2\XML\saml\NameID objects. The filter should also look at both the attributes and the SAML Subject element, with a configuration option to give priority to one or the other if both are present. It should also perform validation of the NameID (e.g. make sure the SPNameQualifier equals our entityID) and allow building it from illegal eduPersonTargetedID string values for legacy purposes.

  • Refactor and clean the consent module. Currently, the module is a mess and needs to be rewritten in part to make it easier to manage.

  • Allow the use of custom metadata storage backends. Apart from the ones we have today, it should be possible to specify a class name in the configuration and use that, provided that the class extends \SimpleSAML\Metadata\MetaDataStorageSource. It should be as simple as resolving a class name here and checking the type of the resulting class.

Advanced

  • Create a language installer so that people can add translations of SimpleSAMLphp by installing a module. A language installer is already work in progress but needs to be finished. SimpleSAMLphp needs to be able to look for translations in modules, and incorporate them dynamically into the list of available translations.

  • Add a configuration option that allows skipping the <samlp:Scoping> element in SAML authentication requests. See issue #498.

  • Make it possible for admin authentication sources to run the authentication processing filters defined in authsources.php. That way, not only we can use other authentication sources to provide admin login, but also apply filters during the process, like authorization rules. See this discussion.

  • Add unit tests. We need to cover as much code as possible with tests. Take a look at the current coverage and add tests for the classes or lines that are not yet covered.

  • Make the SimpleSAML\Logger class PSR-3 compliant. That way we can change our logger class with other classes if needed. This is especially useful for the SAML2 library, as it would make it easier to do logging without requiring SimpleSAMLphp to be used. See issue #371 for a detailed description of the task.

  • Write an authproc filter that verifies the value of schacHomeOrganization against the shibmd:Scope elements defined in metadata. In case of failure, the conflicting values should be removed, and an error logged.

  • Write a generic template in Twig for displaying tables. This should be used instead of the functions in templates/includes/attributes.php, and enable the same functionality without being specific to attributes. It can be implemented by creating a twig template that can be included where a table needs to be displayed, plus twig macros that handler particularities for attributes. Recursiveness should probably be ignored after making sure it's not currently needed.

  • Write a generic template in Twig for displaying NameIDs. This should be used to display the contents of a NameID, typically received/sent in the Subject of a SAML assertion, or as the value for the eduPersonTargetedID attribute. The template should be able to display all the information contained in the NameID (see SAML 2.0 Core, section 2.2.2, or alternatively, allow the user to display the raw XML.

  • Write an authproc filter that generates and sends f-ticks for each successful SSO event.

  • Add a method to \SimpleSAML\XHTML\Template to handle sending of HTTP headers, particularly those related to security.

More info This is currently done in `templates/includes/header.php`, which is wrong not only because templates should only print HTML and not deal with headers or security mechanisms, but also because using your own theme could mean skipping those security mechanisms.

The proper way to implement this is to add a method to `\SimpleSAML\XHTML\Template` to set headers and security mechanisms that should be enforced. Then, this method should be called from `show()` in the same class, before loading the template itself. Finally, the new method should run a specific hook that would allow modules to execute code **before sending out the HTTP headers**.

  • Write a tool that extracts strings from twig templates and PHP scripts, and dumps them to a .po file. See issue #493.

  • Add a tool to upload/download strings/translations to/from Transifex. See issue #493.

  • Get rid of SimpleSAML\Locale\Translate->getPreferredTranslation(). See issue #460.

  • Get rid of SimpleSAML\Locale\Translate->getAttributeTranslation(). See issue #461.

  • Get rid of SimpleSAML\Locale\Translate->getTag(). See issue #462.

  • Get rid of SimpleSAML\Locale\Translate->includeInlineTranslation(). See issue #463.

  • Get rid of SimpleSAML\Locale\Translate->includeLanguageFile(). See issue #464.

Clone this wiki locally