{"id":23859238,"url":"https://github.com/openconext/stepup-middleware","last_synced_at":"2025-09-08T07:30:52.041Z","repository":{"id":20586654,"uuid":"23867318","full_name":"OpenConext/Stepup-Middleware","owner":"OpenConext","description":"Stepup Middleware","archived":false,"fork":false,"pushed_at":"2025-08-18T22:34:11.000Z","size":5542,"stargazers_count":3,"open_issues_count":14,"forks_count":2,"subscribers_count":14,"default_branch":"main","last_synced_at":"2025-08-18T23:42:08.400Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/OpenConext.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2014-09-10T08:47:14.000Z","updated_at":"2025-08-18T08:23:55.000Z","dependencies_parsed_at":"2023-09-23T03:55:54.595Z","dependency_job_id":"2f31c572-517a-4ea9-b291-a83ccdb4bc12","html_url":"https://github.com/OpenConext/Stepup-Middleware","commit_stats":null,"previous_names":[],"tags_count":173,"template":false,"template_full_name":null,"purl":"pkg:github/OpenConext/Stepup-Middleware","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OpenConext%2FStepup-Middleware","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OpenConext%2FStepup-Middleware/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OpenConext%2FStepup-Middleware/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OpenConext%2FStepup-Middleware/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/OpenConext","download_url":"https://codeload.github.com/OpenConext/Stepup-Middleware/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OpenConext%2FStepup-Middleware/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":274152125,"owners_count":25231285,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-08T02:00:09.813Z","response_time":121,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-01-03T03:33:10.311Z","updated_at":"2025-09-08T07:30:51.478Z","avatar_url":"https://github.com/OpenConext.png","language":"PHP","readme":"Step-up Middleware\n==================\n\n[![Build Status](https://travis-ci.org/OpenConext/Stepup-Middleware.svg)](https://travis-ci.org/OpenConext/Stepup-Middleware) [![Scrutinizer Code Quality](https://scrutinizer-ci.com/g/OpenConext/Stepup-Middleware/badges/quality-score.png?b=develop)](https://scrutinizer-ci.com/g/OpenConext/Stepup-Middleware/?branch=develop)\n\nThis component is part of \"Step-up Authentication as-a Service\". See [Stepup-Deploy](https://github.com/OpenConext/Stepup-Deploy) for an overview and installation instructions for a complete Stepup system, including this component. The requirements and installation instructions below cover this component only.\n\n## Requirements\n\n * PHP 5.6+ or PHP7\n * [Composer](https://getcomposer.org/)\n * A web server (Apache, Nginx)\n * MariaDB 10\n * A working [Gateway](https://github.com/OpenConext/Stepup-Gateway)\n\n## Installation\n\nClone the repository or download the archive to a directory. Install the dependencies by running `composer install` and fill out the database credentials et cetera.\n\nMake sure to run database migrations using `bin/console middleware:migrations:migrate`.\n\nWhen using 'Stepup-Deploy' the 'deploy' entity manager should be used in order to use the correct credentials e.g. `bin/console middleware:migrations:migrate --em=deploy`\n\n## Management API\n\nSome of the configuration of the components is static (i.e. stored in parameteres.yml). The configuration that is expected to change during the operation of a Stepup system is managed through an API on the middleware. This provides  one place and action to change the configuration and allows changing of this configuration without having to modify the configuration of several components on several servers.\n\n- The API calls are documented in the [middleware API documentation](./docs/MiddlewareManagementAPI.md).\n- The configuration itself is elaborate and is described in detail in the [Middlware configuration](./docs/MiddlewareConfiguration.md).\n- The ansible Stepup-Middleware role write scripts in /opt/stepup/  for pushing the configuration to the middleware component\n\n## Development Notes\n\n### Adding new events\n\nWhenever adding a new event, be sure to update `bin/config/events.yml`.\nThis is a list of events that is shown when replaying events.\nAlso be sure to create or update the event serialization/deserialization tests,\nfor example see [EventSerializationAndDeserializationTest for Configuration events][event-serialization-example]\n\n### Mocking time\n\nDue to a limitation of mocking of static methods, to mock time, the helper `DateTimeHelper::stubNow(DateTime $now)` was\ncreated. Call `::stubNow($now)` to set a fixed date/time, and call `::stubNow(null)` to disable stubbing. It is\nrecommended to run tests in a separate process when using this helper so the stub value doesn't persist between tests.\n\n```php\n/** @runTestInSeparateProcess */\npublic function testItWorks()\n{\n    # Trick `DateTime::now()` into thinking it is 1970.\n    DateTimeHelper::stubNow(new DateTime('@0'));\n\n    $this-\u003eassertEquals('1970-01-01T00:00:00+00:00', (string) \\Surfnet\\Stepup\\DateTime\\DateTime::now());\n}\n```\n\n### Middleware vs Gateway projections\nYou might have seen that both the Gateway and Middleware have databases of their own. Gateway has very little\nknowledge of any Middleware business logic. However some data is required in Gateway for smooth operation. For example\nwe want to verify in Gateway if an institution is whitelisted. Doing an API call for each gateway interaction would \nbe more costly than having this data projected in the Gateway database. \n\nAt this point four Gateway projections exist. Note that they are exclusively managed by Middleware! \n\nResults from a Middleware event might result in an update of a Gateway projection.\n\n#### Creating a Gateway projection\nMiddleware uses Doctrine for ORM and DBAL implementation. Middleware is configured with a multi entity manager setup.\nThree EntityManagers (EM) are known: middleware (default), gateway and deploy. Each have a different user with each his\nown privileges.\n\nNote that when you want to do an interaction on a specific EM, you need to specifically instruct Symfony/Doctrine to do\nso. This becomes apparent when creating and running Doctrine Migrations. Say you want to add a field to the \n`whitelist_entry` Entity. Simply running:\n\n```shell\n$ ./bin/console doctrine:migrations:diff \n```\n\nDoes not result in a new Migration file containing the whitelist entity change. In order to get that change to show up,\nyou need to explicitly instruct use of the correct Entity Manager.\n\n```shell\n$ ./bin/console doctrine:migrations:diff --em=gateway\n```\n\nThe resulting migration is not yet ready to go. The migration file itself needs to be marked to use the correct database \nschema. The following snippet from a Migration shows how to achieve this goal.\n\n```php\n// Excerpt from Version20220519134637\n$gatewaySchema = $this-\u003egetGatewaySchema();\n$this-\u003eaddSql(sprintf('ALTER TABLE %s.second_factor ADD vetting_type VARCHAR(255) NOT NULL', $gatewaySchema));\n```\n\n#### Keep entities in sync\nNow here comes the tricky bit. Both Gateway and Middleware have a view on the projection. Middleware writes to the \ngateway schema. And Gateway reads the data. Both projects utilize Doctrine to achieve those goals. Needless to say\nthe Entity definitions for the entity in question needs to be synchronized. If they are not, weird errors may occur.\n\nFor example see [this PR](https://github.com/OpenConext/Stepup-Gateway/pull/123/commits/4ec910f22c9b2dd0347dda2ae0f855a50bd43e64)\n\n### Adding support for a new Generic SAML Second Factor `biometric`, by example\n\n * https://github.com/OpenConext/Stepup-bundle/pull/31/commits/55279033a7f4e261277008603d9be94ebb582469\n * Release a new minor version of `surfnet/stepup-bundle`.\n * https://github.com/OpenConext/Stepup-Middleware/pull/106/commits/c3b42c92593f10587f9e0051420e711c974dd319\n * https://github.com/OpenConext/Stepup-SelfService/pull/96/commits/efa7feb29f0ee26d0d9860849f3f379131ba23cd\n * https://github.com/OpenConext/Stepup-RA/pull/102/commits/f2c0d4f57912a6c026c58db2818735bacf7a7787\n * https://github.com/OpenConext/Stepup-Gateway/pull/90/commits/1463cf05d1bec9e5e1fa1103b81fa6ada00a611f\n * Add the Self-Service and RA applications to the `gssp_allowed_sps` parameters:\n```yaml\ngssp_allowed_sps:\n   - (...)\n   - 'https://ss-dev.stepup.coin.surf.net/app_dev.php/registration/gssf/biometric/metadata'\n   - 'https://ra-dev.stepup.coin.surf.net/app_dev.php/vetting-procedure/gssf/biometric/metadata'\n```\n * Configure these SPs through the Middleware configuration API.\n\n## Release strategy\nPlease read: https://github.com/OpenConext/Stepup-Deploy/wiki/Release-Management fro more information on the release strategy used in Stepup projects.\n\n[event-serialization-example]: src/Surfnet/Stepup/Tests/Configuration/Event/EventSerializationAndDeserializationTest.php\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopenconext%2Fstepup-middleware","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fopenconext%2Fstepup-middleware","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopenconext%2Fstepup-middleware/lists"}