{"id":20345945,"url":"https://github.com/silinternational/ssp-base","last_synced_at":"2025-07-05T03:07:14.171Z","repository":{"id":14499713,"uuid":"75423616","full_name":"silinternational/ssp-base","owner":"silinternational","description":"Base Docker image for simpleSAMLphp","archived":false,"fork":false,"pushed_at":"2025-06-26T21:56:10.000Z","size":2345,"stargazers_count":3,"open_issues_count":2,"forks_count":1,"subscribers_count":7,"default_branch":"main","last_synced_at":"2025-06-26T23:15:24.760Z","etag":null,"topics":["hub","idp","security","simplesamlphp"],"latest_commit_sha":null,"homepage":null,"language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/silinternational.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2016-12-02T19:13:42.000Z","updated_at":"2025-05-20T13:09:35.000Z","dependencies_parsed_at":"2024-01-09T02:28:13.637Z","dependency_job_id":"1774a949-f696-455f-8e65-383f1862fe2d","html_url":"https://github.com/silinternational/ssp-base","commit_stats":null,"previous_names":[],"tags_count":117,"template":false,"template_full_name":null,"purl":"pkg:github/silinternational/ssp-base","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/silinternational%2Fssp-base","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/silinternational%2Fssp-base/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/silinternational%2Fssp-base/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/silinternational%2Fssp-base/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/silinternational","download_url":"https://codeload.github.com/silinternational/ssp-base/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/silinternational%2Fssp-base/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":263674240,"owners_count":23494541,"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","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":["hub","idp","security","simplesamlphp"],"created_at":"2024-11-14T22:10:28.779Z","updated_at":"2025-07-05T03:07:14.163Z","avatar_url":"https://github.com/silinternational.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ssp-base\n\nBase image for SimpleSAMLphp IdP and Hub with custom modules\n\nDocker image: [silintl/ssp-base](https://hub.docker.com/r/silintl/ssp-base/)\n\n## Prerequisite software\n[Docker](https://www.docker.com/products/overview) and [docker compose](https://docs.docker.com/compose/install)\nmust be installed.\n\n[Make](https://www.gnu.org/software/make) is optional but simplifies the build process.\n\n## Configuration\n\nBy default, configuration is read from environment variables. These are documented\nin the `local.env.dist` file. Optionally, you can define configuration in AWS Systems Manager.\nTo do this, set the following environment variables to point to the configuration in\nAWS:\n\n* `AWS_REGION` - the AWS region in use\n* `APP_ID` - AppConfig application ID or name\n* `CONFIG_ID` - AppConfig configuration profile ID or name\n* `ENV_ID` - AppConfig environment ID or name\n* `PARAMETER_STORE_PATH` - Parameter Store base path for this app, e.g. \"/idp-name/\"\n\nIn addition, the AWS API requires authentication. It is best to use an access role\nsuch as an [ECS Task Role](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task-iam-roles.html).\nIf that is not an option, you can specify an access token using the `AWS_ACCESS_KEY_ID` and\n`AWS_SECRET_ACCESS_KEY` variables.\n\nIf `PARAMETER_STORE_PATH` is given, AWS Parameter Store will be used. Each parameter in AWS Parameter\nStore is set as an environment variable in the execution environment.\n\nIf `PARAMETER_STORE_PATH` is not given but the AppConfig variables are, AWS AppConfig will be used.\nThe content of the AppConfig configuration profile takes the form of a typical .env file, using `#`\nfor comments and `=` for variable assignment. Any variables read from AppConfig will overwrite variables\nset in the execution environment.\n\n### SimpleSAMLphp Metadata\n\nNo metadata files are included by default. All metadata configuration must be provided\nby using ssp-base as a base image and adding files to the\n`/data/vendor/simplesamlphp/simplesamlphp/metadata` directory. `SSP_PATH` is defined by\nssp-base as shorthand for `/data/vendor/simplesamlphp/simplesamlphp`.\n\n```Dockerfile\nCOPY metadata/* $SSP_PATH/metadata/\n```\n\n#### Legacy Metadata Format\n\nPrior to version 10 of ssp-base, the saml20-idp-remote and saml20-sp-remote files contained\nPHP code to search the metadata directory for files beginning with `sp` or `idp` to assemble\nthe metadata. The format of these files differed from the standard SimpleSAMLphp metadata\nfiles.\n\nExample:\n```php\nreturn [\n    'https://example.com' =\u003e [\n        'name' =\u003e ['en' =\u003e 'Example'],\n        // ...\n    ],\n]\n```\n\nTo use this old, non-standard file structure and format, add these two files to\nyour new image:\n\nsaml20-idp-remote.php\n```php\n\u003c?php\n\nuse Sil\\SspUtils\\Metadata;\n\n$startMetadata = Metadata::getIdpMetadataEntries(__DIR__);\nforeach ($startMetadata as $key =\u003e $value) {\n    $metadata[$key] = $value;\n}\n```\n\nsaml20-sp-remote.php\n```php\n\u003c?php\n\nuse Sil\\SspUtils\\Metadata;\n\n$startMetadata = Metadata::getSpMetadataEntries(__DIR__);\nforeach ($startMetadata as $key =\u003e $value) {\n    $metadata[$key] = $value;\n}\n```\n\n#### Standard Metadata Format\n\nExample:\n```php\n$metadata['https://example.com'] = [\n    'name' =\u003e ['en' =\u003e 'Example'],\n    // ...\n]\n```\n\nMoving forward, to utilize a multi-file approach while using the standard SimpleSAMLphp\nmetadata format, add these two files to your image:\n\nsaml20-idp-remote.php\n```php\n\u003c?php\n\nuse Sil\\SspUtils\\Metadata;\n\n$files = Metadata::getMetadataFiles(__DIR__, 'idp');\nforeach ($files as $file) {\n    include $file;\n}\n```\n\nsaml20-sp-remote.php\n```php\n\u003c?php\n\nuse Sil\\SspUtils\\Metadata;\n\n$files = Metadata::getMetadataFiles(__DIR__, 'sp');\nforeach ($files as $file) {\n    include $file;\n}\n```\n\n## Local testing\n\n1. `cp local.env.dist local.env` within project root and make adjustments as needed.\n2. `cp local.broker.env.dist local.broker.env` within project root and make adjustments as needed.\n3. Add your GitHub [personal access token](https://github.com/settings/tokens?type=beta) to the `COMPOSER_AUTH` variable in the `local.env` file.\n4. Create `localhost` aliases for `ssp-hub.local`, `ssp-idp1.local`, `ssp-idp2.local`,\n   `ssp-idp3.local`, `ssp-idp4.local`, `ssp-sp1.local`, `ssp-sp2.local`, and `ssp-sp3.local`.\n   This is typically done in `/etc/hosts`.\n   * Example line:\n     `127.0.0.1  ssp-hub.local ssp-idp1.local ssp-idp2.local ssp-idp3.local ssp-idp4.local ssp-sp1.local ssp-sp2.local ssp-sp3.local`\n5. Change the BASE_URL_PATH for ssp-idp1.local in docker-compose.yml to have the port number, as\n   specific in the comment on that line in the file.\n6. Bring up the various containers that you will want to interact with. Example:\n   `docker compose up -d ssp-hub.local ssp-idp1.local ssp-idp2.local ssp-idp3.local ssp-idp4.local ssp-sp1.local ssp-sp2.local ssp-sp3.local`\n7. Go to \u003chttp://ssp-sp1.local:8081\u003e in a browser on your computer.\n8. Click \"Test configured authentication sources\"\n9. Click \"ssp-hub-custom-port\"\n10. Enter the username and password for the desired user. The list of valid options, and the details\n    about each of those users, is defined in the `authsources.php` file for the relevant IDP (e.g.\n    `development/idp-local/config/authsources.php`).\n\n_Note:_ there is an unresolved problem that requires a change to BASE_URL_PATH for ssp-idp1.local in\ndocker-compose.yml due to a requirement in silauth that it be a full URL. For automated testing, it\nmust not have a port number, but for manual testing it needs the port number.\n\n### Configure a container for debugging with Xdebug\n\n1. Add a volume map for run-debug.sh on the container you wish to debug.\n\n```yml\n    - ./development/run-debug.sh:/data/run-debug.sh\n```\n\n2. Add or change the `command` for the container.\n\n```yml\n    command: /data/run-debug.sh\n```\n\n3. Restart the container.\n\n```shell\ndocker composer up -d ssp-hub.local\n```\n\n### Setup PhpStorm for remote debugging with Docker\n\n1. Make sure you're running PhpStorm 2016.3 or later\n2. Setup Docker server by going to `Preferences` (or `Settings` on Windows) -\u003e `Build, Execution, Deployment`\n   -\u003e Click `+` to add a new server. Use settings:\n - Name it `Docker`\n - API URL should be `tcp://localhost:2375`\n - Certificates folder should be empty\n - Docker Compose executable should be full path to docker compose script\n\n3. Hit `Apply`\n4. Next in `Preferences` -\u003e `Languages \u0026 Frameworks` -\u003e `PHP` click on the `...`\n   next to the `CLI Interpreter` and click `+` to add a new interpreter. Use\n   settings:\n - Name: Remote PHP7\n - Remote: Docker\n - Server: chose the Docker server we added\n - Debugger extension: `/usr/lib/php/20151012/xdebug.so`\n\n5. Hit `Apply` and `OK`\n6. On `PHP` for Path mappings edit it so the project root folder maps to /data on remote server\n7. Hit `Apply` and `OK`\n8. Click on `Run` and then `Edit Configurations`\n9. Click on `+` and select `PHP Web Application`\n10. Name it `Debug via Docker`\n11. Click on `...` next to Server and then `+` to add a server.\n12. Name it `Localhost` and use settings:\n - Host: localhost\n - Port: 80\n - Debugger: Xdebug\n - Check use path mappings and add map from project root to `/data`\n\n13. Hit `Apply` and `OK`\n14. Click on `Run` and then `Debug 'Debug on Docker'`\n\n### Metadata Tests Check:\n- Metadata files can be linted via php (`php -l file`)\n- Metadata files return arrays\n- IdP Metadata files have an IdP namespace that exists, is a string, and only contains letters, numbers, hyphens, and underscores\n- IdP Metadata files don't have duplicate IdP codes\n- SP Metadata files don't have duplicate entity ids\n- IdP Metadatas contains `name` entry with an `en` entry\n- IdP Metadatas contains `logoURL` entry\n- if SP Metadata contains `IDPList`, check that it is allowed for that IdP as well\n\n#### Hub mode tests [SKIPPED if HUB_MODE = false]\n- IdP Metadata files SP List is an array\n- IdP Metadata files LogoCaption isset\n- IdP Metadata files SP List has existing SPs\n- All SPs have an IdP it can use\n- All SPs have a non-empty IDPList entry\n- All SPs have a non-empty name entry\n\n#### SP tests [SKIPPED if `'SkipTests' =\u003e true,`]\n- Contains a `CertData` entry\n- Contains a `saml20.sign.response` entry AND it is set to true\n- Contains a `saml20.sign.assertion` entry AND it is set to true\n- Contains a `assertion.encryption` entry AND it is set to true\n\n## Overriding translations / dictionaries\n\nIf you use this Docker image but want to change some of the translations, you\ncan do so by appending the translations on the end of the base image's files.\nUse the modules/material/locales/en/LC_MESSAGES/material.po file for reference.\nReference the [GNU gettext PO Files](https://www.gnu.org/software/gettext/manual/gettext.html#PO-Files)\ndocumentation for more information about the file format.\n\nExample Dockerfile excerpt (overriding text in the MFA module's material theme):\n```dockerfile\n# Copy your translation changes into the working folder:\nCOPY locales/* /data\n\n# Append those changes onto the existing translation files:\nRUN cat /data/en.material.po \u003e\u003e $SSP_PATH/modules/material/locales/en/LC_MESSAGES/material.po\nRUN cat /data/es.material.po \u003e\u003e $SSP_PATH/modules/material/locales/es/LC_MESSAGES/material.po\nRUN cat /data/fr.material.po \u003e\u003e $SSP_PATH/modules/material/locales/fr/LC_MESSAGES/material.po\nRUN cat /data/ko.material.po \u003e\u003e $SSP_PATH/modules/material/locales/ko/LC_MESSAGES/material.po\n```\n\n## Custom Modules\n\nSeveral modules are included and active by default. The Authentication Process (AuthProc)\nfilters in these modules require metadata configuration as described here.\n\n### ExpiryChecker SimpleSAMLphp Module\n\nA SimpleSAMLphp module for warning users that their password will expire soon\nor that it has already expired.\n\n**NOTE:** This module does *not* prevent the user from logging in. It merely\nshows a warning page (if their password is about to expire), with the option to\nchange their password now or later, or it tells the user that their password has\nalready expired, with the only option being to go change their password now.\nBoth of these pages will be bypassed (for varying lengths of time) if the user\nhas recently seen one of those two pages, in order to allow the user to get to\nthe change-password website (assuming it is also behind this IdP). If the user\nshould not be allowed to log in at all, the SimpleSAMLphp Auth Source should\nconsider the credentials provided by the user to be invalid.\n\nThe expirychecker module is implemented as an Authentication Processing Filter,\nor AuthProc. That means it can be configured in the global config.php file or\nthe SP remote or IdP hosted metadata.\n\nIt is recommended to run the expirychecker module at the IdP, and configure the\nfilter to run before all the other filters you may have enabled.\n\n#### How to use the module\n\nSet filter parameters in your config. We recommend adding\nthem to the `'authproc'` array in your `metadata/saml20-idp-hosted.php` file,\nbut you are also able to put them in the `'authproc.idp'` array in your\n`config/config.php` file.\n\nExample (in `metadata/saml20-idp-hosted.php`):\n\n```php\nuse Sil\\PhpEnv\\Env;\nuse Sil\\Psr3Adapters\\Psr3SamlLogger;\n\n$metadata['idp.example.com'] = [\n    // ...\n    'authproc' =\u003e [\n        15 =\u003e [\n            // Required:\n            'class' =\u003e 'expirychecker:ExpiryDate',\n            'accountNameAttr' =\u003e 'cn',\n            'expiryDateAttr' =\u003e 'schacExpiryDate',\n            'passwordChangeUrl' =\u003e Env::requireEnv('PASSWORD_CHANGE_URL'),\n\n            // Optional:\n            'warnDaysBefore' =\u003e 14,\n            'loggerClass' =\u003e Psr3SamlLogger::class,\n        ],\n\n        // ...\n    ],\n];\n```\n\nThe `accountNameAttr` parameter represents the SAML attribute name which has\nthe user's account name stored in it. In certain situations, this will be\ndisplayed to the user, as well as being used in log messages. This attribute must\nbe in the attribute set returned when the user successfully authenticates.\n\nThe `expiryDateAttr` parameter represents the SAML attribute name which has\nthe user's expiry date, which must be formated as YYYYMMDDHHMMSSZ (e.g.\n`20111011235959Z`). This attribute must be in the attribute set\nreturned when the user successfully authenticates.\n\nThe `passwordChangeUrl` parameter contains the URL of the password manager. A\nlink to that URL may be presented to the user as a convenience for updating\ntheir password.\n\nThe `warnDaysBefore` parameter should be an integer representing how many days\nbefore the expiry date the \"about to expire\" warning will be shown to the user.\n\nThe `loggerClass` parameter specifies the name of a PSR-3 compatible class that\ncan be autoloaded, to use as the logger within the ExpiryDate class.\n\n#### Acknowledgements\n\nThis module is adapted from the `ssp-iidp-expirycheck` and `expirycheck` modules.\nThanks to Alex Mihičinac, Steve Moitozo, and Steve Bagwell for the initial work\nthey did on those two modules.\n\n### Material Module\n\nMaterial Design theme for use with SimpleSAMLphp\n\n#### Configuration\n\nNo configuration is necessary. The `theme.use` config option is pre-configured to `material:material`.\nOptional configuration is described below.\n\n##### Google reCAPTCHA\n\nIf a site key and secret have been provided in the `RECAPTCHA_SITE_KEY` and `RECAPTCHA_SECRET_KEY`\nenvironment variables, the username/password page may require the user prove his/her humanity.\n\nDeprecated: `RECAPTCHA_SECRET` is deprecated and will be removed in the next major version.\n\n##### Branding\n\nSet the `THEME_COLOR_SCHEME` environment variable using one of the following values:\n\n```\n'indigo-purple', 'blue_grey-teal', 'red-teal', 'orange-light_blue', 'brown-orange', 'teal-blue'\n```\n\nThe default is `indigo-purple`.\n\nThe login page looks for `/simplesamlphp/public/logo.png` which is **NOT** provided by default.\n\n##### Analytics\n\nSet the `ANALYTICS_ID` environment variable to contain your Google Analytics 4 tag ID.\n\n##### Announcements\n\nUpdate `/simplesamlphp/announcement/announcement.php`:\n\n```\n return 'Some \u003cstrong\u003eimportant\u003c/strong\u003e announcement';\n```\n\nBy default, the announcement is whatever is returned by `/simplesamlphp/announcement/announcement.php`.\nTo add an announcement, copy a custom `announcement.php` to that path. If provided, an alert will be\nshown to the user filled with the content of that announcement. HTML is supported.\n\n#### Testing the Material theme\n\nSee a full listing of [Manual tests](./docs/material_tests.md) in the `docs` directory in this repo.\n\n#### i18n support\n\nTranslations are in files located in the `modules/material/locales` directory.\n\nLocalization is affected by the configuration setting `language.available`. Only language codes found in this property\nwill be utilized. For example, if a translation is provided in Afrikaans for this module, the configuration must be\nadjusted to make 'af' an available language. If that's not done, the translation function will not utilize the\ntranslations even if provided.\n\n### Multi-Factor Authentication (MFA) SimpleSAMLphp Module\n\nA SimpleSAMLphp module for prompting the user for MFA credentials (such as a\nTOTP code, etc.).\n\nThis mfa module contains an Authentication Processing Filter,\nor AuthProc. That means it can be configured in the global config.php file or\nthe SP remote or IdP hosted metadata.\n\nIt is recommended to run the mfa module at the IdP, and configure the\nfilter to run before all the other filters you may have enabled.\n\n#### How to use the module\n\nYou will need to set filter parameters in your config. We recommend adding\nthem to the `'authproc'` array in your `metadata/saml20-idp-hosted.php` file.\n\nExample (for `metadata/saml20-idp-hosted.php`):\n\n```php\nuse Sil\\PhpEnv\\Env;\nuse Sil\\Psr3Adapters\\Psr3SamlLogger;\n\n$metadata['idp.example.com'] = [\n    // ...\n    'authproc' =\u003e [\n        10 =\u003e [\n            // Required:\n            'class' =\u003e 'mfa:Mfa',\n            'employeeIdAttr' =\u003e 'employeeNumber',\n            'idBrokerAccessToken' =\u003e Env::get('ID_BROKER_ACCESS_TOKEN'),\n            'idBrokerBaseUri' =\u003e Env::get('ID_BROKER_BASE_URI'),\n            'idBrokerTrustedIpRanges' =\u003e Env::get('ID_BROKER_TRUSTED_IP_RANGES'),\n            'idpDomainName' =\u003e Env::get('IDP_DOMAIN_NAME'),\n            'mfaSetupUrl' =\u003e Env::get('MFA_SETUP_URL'),\n\n            // Optional:\n            'idBrokerAssertValidIp' =\u003e Env::get('ID_BROKER_ASSERT_VALID_IP'),\n            'loggerClass' =\u003e Psr3SamlLogger::class,\n            'recoveryContactsApi' =\u003e Env::get('MFA_RECOVERY_CONTACTS_API'),\n            'recoveryContactsApiKey' =\u003e Env::get('MFA_RECOVERY_CONTACTS_API_KEY'),\n            'recoveryContactsFallbackName' =\u003e Env::get('MFA_RECOVERY_CONTACTS_FALLBACK_NAME'),\n            'recoveryContactsFallbackEmail' =\u003e Env::get('MFA_RECOVERY_CONTACTS_FALLBACK_EMAIL'),\n        ],\n        // ... more AuthProc filters ...\n    ],\n];\n```\n\nThe `employeeIdAttr` parameter represents the SAML attribute name which has\nthe user's Employee ID stored in it. In certain situations, this may be\ndisplayed to the user, as well as being used in log messages. This attribute must\nbe in the attribute set returned when the user successfully authenticates.\n\n`idBrokerAccessToken` is an authentication token for access to the id-broker API\n\n`idBrokerBaseUri` is the base URL for the id-broker API. It must be a full http URL.\n\n`idBrokerTrustedIpRanges` is a comma-separated list of CIDR-formatted IPv4 or IPv6 networks. The PHP\nclient for the id-broker API performs a DNS check against this list. If the resulting IP address is\nnot in any of the trusted ranges, it will not proceed with connection to the API.\n\nThe `idpDomainName` parameter is used to assemble the Relying Party Origin\n(RP Origin) for WebAuthn MFA options.\n\nThe `mfaSetupUrl` parameter is for the URL of where to send the user if they\nwant/need to set up MFA.\n\n`idBrokerAssertValidIp` can be set to 'false' to bypass IP checks. The default is 'true'.\n\nThe `loggerClass` parameter specifies the name of a PSR-3 compatible class that\ncan be autoloaded, to use as the logger within the module.\n\n##### \"Recovery Contacts\" Feature\n\nThe `recoveryContacts*` parameters allow you to call an API to retrieve a list\nof recovery contact addresses which should be offered when the user requests help with\ntheir MFA.\n\nIf the `recoveryContactsApi` is provided, the \"More options\" \u003e \"I need help\"\noption will result in a call to that API, with the API key included as a Bearer\ntoken in an Authentication header, with the email address of the current user in\nan `email` query string parameter.\n\nThe response must be a JSON array of zero or more objects, each with a `name`\nand `email` field. Example:\n`[{\"name\": \"John Smith\",\"email\":\"john_smith@example.com\"}]`\n\nNames returned by the API will be partially abbreviated to avoid giving out too\nmuch information in case a user's password is compromised. If the returned array\nis empty, the provided fallback parameters will be used. Note: The fallback name\nwill not be abbreviated.\n\n#### Why use an AuthProc for MFA?\nBased on...\n\n- the existence of multiple other SimpleSAMLphp modules used for MFA and\n  implemented as AuthProcs,\n- implementing my solution as an AuthProc and having a number of tests that all\n  confirm that it is working as desired, and\n- a discussion in the SimpleSAMLphp mailing list about this:\n  https://groups.google.com/d/msg/simplesamlphp/ocQols0NCZ8/RL_WAcryBwAJ\n\n... it seems sufficiently safe to implement MFA using a SimpleSAMLphp AuthProc.\n\nFor more of the details, please see this Stack Overflow Q\u0026A:\nhttps://stackoverflow.com/q/46566014/3813891\n\n#### Acknowledgements\nThis is adapted from the `silinternational/simplesamlphp-module-mfa`\nmodule, which itself is adapted from other modules. Thanks to all those who\ncontributed to that work.\n\n### Profile Review SimpleSAMLphp Module\n\nA SimpleSAMLphp module for prompting the user review their profile (such as\n2-step verification, email, etc.).\n\nThis module contains an Authentication Processing Filter,\nor AuthProc. That means it can be configured in the global config.php file or\nthe SP remote or IdP hosted metadata.\n\nIt is recommended to run the profilereview module at the IdP, after all\nother authentication modules.\n\n#### How to use the module\n\nYou will need to set filter parameters in your config. We recommend adding\nthem to the `'authproc'` array in your `metadata/saml20-idp-hosted.php` file.\n\nExample (for `metadata/saml20-idp-hosted.php`):\n\n```php\nuse Sil\\PhpEnv\\Env;\nuse Sil\\Psr3Adapters\\Psr3SamlLogger;\n\n$metadata['idp.example.com'] = [\n    // ...\n    'authproc' =\u003e [\n        30 =\u003e [\n            // Required:\n            'class' =\u003e 'profilereview:ProfileReview',\n            'employeeIdAttr' =\u003e 'employeeNumber',\n            'profileUrl' =\u003e Env::get('PROFILE_URL'),\n\n            // Optional:\n            'mfaLearnMoreUrl' =\u003e Env::get('MFA_LEARN_MORE_URL'),\n            'loggerClass' =\u003e Psr3SamlLogger::class,\n        ],\n        // ... other AuthProc filters ...\n    ],\n```\n\nThe `employeeIdAttr` parameter represents the SAML attribute name which has\nthe user's Employee ID stored in it. In certain situations, this may be\ndisplayed to the user, as well as being used in log messages.\n\nThe `profileUrl` parameter is for the URL of where to send the user if they\nwant/need to update their profile.\n\n`mfaLearnMoreUrl` can be set to a URL the user can visit to learn more about MFA. It is\nused in a link on the profilereview 'nag-for-mfa' page.\n\nThe `loggerClass` parameter specifies the name of a PSR-3 compatible class that\ncan be autoloaded, to use as the logger within ExpiryDate.\n\n### SilAuth SimpleSAMLphp module\n\nSimpleSAMLphp module containing an Auth Source implementing custom business logic:\n\n- authentication\n- rate limiting\n- status endpoint\n\n#### Configuration\n\nThe following configuration is included in the ssp-base Docker image:\n\nauthsources.php:\n```php\nuse SimpleSAML\\Module\\silauth\\Auth\\Source\\config\\ConfigManager;\n\n$config = [\n    // ...\n    'silauth' =\u003e ConfigManager::getSspConfig(),\n];\n```\n\nThe `ConfigManager::getSspConfig` helper expects the following environment variables to be defined:\n\n```\nTRUSTED_IP_ADDRESSES=\nID_BROKER_ACCESS_TOKEN=\nID_BROKER_ASSERT_VALID_IP=\nID_BROKER_BASE_URI=\nID_BROKER_TRUSTED_IP_RANGES=\nIDP_DOMAIN_NAME=\nMYSQL_HOST=\nMYSQL_DATABASE=\nMYSQL_USER=\nMYSQL_PASSWORD=\nRECAPTCHA_SITE_KEY=\nRECAPTCHA_SECRET_KEY=\nPROFILE_URL=\nHELP_CENTER_URL=\n```\n\nReference `local.env.dist` for details on each of these variables.\n\n#### Database Migrations\nTo create another database migration file, run the following (replacing\n`YourMigrationName` with whatever you want the migration to be named, using\nCamelCase):\n\n    make migration NAME=YourMigrationName\n\n#### Rate Limiting\nSilAuth will rate limit failed logins by username and by every untrusted IP\naddress from a login attempt.\n\n##### tl;dr (\"the short version\")\nIf there have been more than 10 failed logins for a given username (or IP\naddress) within the past hour, a captcha will be included in the webpage. The\nuser may or may not have to directly interact with the captcha, though.\n\nIf there have been more than 50 failed logins for that username (or IP address)\nwithin the past hour, logins for that username (or IP address) will be blocked\nfor up to an hour.\n\n##### Details\nFor each login attempt, if it has too many failed logins within the last hour\n(aka. recent failed logins) for the given username OR for any single untrusted\nIP address associated with the current request, it will do one of the following:\n\n- If there are fewer than `Authenticator::REQUIRE_CAPTCHA_AFTER_NTH_FAILED_LOGIN`\n  recent failures: process the request normally.\n- If there are at least that many, but fewer than\n  `Authenticator::BLOCK_AFTER_NTH_FAILED_LOGIN`: require the user to pass a\n  captcha.\n- If there are more than that: block that login attempt for `(recent failures\n  above the limit)^2` seconds after the most recent failed login, with a\n  minimum of 3 (so blocking for 9 seconds).\n- Note: the blocking time is capped at an hour, so if no more failures occur,\n  then the user will be unblocked in no more than an hour.\n\nSee `features/login.feature` for descriptions of how various situations are\nhandled. That file not only contains human-readable scenarios, but those are\nalso actual tests that are run to ensure those descriptions are correct.\n\n##### Example 1\n\n- If `BLOCK_AFTER_NTH_FAILED_LOGIN` is 50, and\n- if `REQUIRE_CAPTCHA_AFTER_NTH_FAILED_LOGIN` is 10, and\n- if there have been 4 failed login attempts for `john_smith`, and\n- there have been 10 failed login attempts from `11.22.33.44`, and\n- there have been 3 failed login attempts from `192.168.1.2`, and\n- someone tries to login as `john_smith` from `192.168.1.2` and their request\n  goes through a proxy at `11.22.33.44`, then\n- they will have to pass a captcha, but they will not yet be blocked.\n\n##### Example 2\n\n- However, if all of the above is true, but\n- there have now been 55 failed login attempts from `11.22.33.44`, then\n- any request involving that IP address will be blocked for 25 seconds after\n  the most recent of those failed logins.\n\n#### Excluding trusted IP addresses from IP address based rate limiting\nSince this application enforces rate limits based on the number of recent\nfailed login attempts by both username and IP address, and since it looks at\nboth the REMOTE_ADDR and the X-Forwarded-For header for IP addresses, you will\nwant to list any IP addresses that should NOT be rate limited (such as your\nload balancer) in the TRUSTED_IP_ADDRESSES environment variable (see\n`local.env.dist`).\n\n#### Status Check\nTo check the status of the website, you can access this URL:\n`https://(your domain name)/module.php/silauth/status.php`\n\n### SilDisco module for SAML Discovery\n\nA SimpleSAMLphp module containing a custom IdP Discovery class and four Authentication Processing\nfilters. It is meant to be used as a SAML Hub, also known as a SAML Proxy. For more information, see\nthe [Module Overview](./docs/overview.md) in the docs/ folder.\n\n#### Configuration\n\n##### Authentication Process filters\n\nDetailed documentation is in [Editing Authprocs](./docs/editing_authprocs.md) in the docs/ folder of this repo. Following is a\nbrief summary:\n\nTwo of the AuthProc filters are configured in the SimpleSAMLphp config.php file when the\n`HUB_MODE` variable is set to `true`:\n\n```php\nif ($HUB_MODE) {\n    // prefix the 'member' (urn:oid:2.5.4.31) attribute elements with idp.idp_name.\n    $config['authproc.idp'][48] = 'sildisco:TagGroup';\n    $config['authproc.idp'][49] = 'sildisco:AddIdp2NameId';\n}\n```\n\nThe `LogUser` AuthProc can be configured in saml20-idp-remote.php:\n\n```php\n$metadata['idp.example.com'] = [\n    // ...\n    'authproc' =\u003e [\n        97 =\u003e [\n            'class' =\u003e'sildisco:LogUser',\n            'DynamoRegion' =\u003e 'us-east-1',\n            'DynamoLogTable' =\u003e 'idp-hub-prod-user-log',\n        ],\n    ],\n];\n```\n\nThe `TrackIdps` AuthProc can be configured in saml20-idp-hosted.php:\n\n```php\n$metadata['idp.example.com'] = [\n    // ...\n    'authproc' =\u003e [\n        95 =\u003e [\n            'class' =\u003e 'sildisco:TrackIdps',\n        ]\n    ],\n];\n```\n\n#### The Hub\n\nFor a full description of [The Hub](./docs/the_hub.md), see the docs/ folder.\n\n#### Development\n\nDetails for [Development](./docs/development.md) in the docs/ folder.\n\n#### Functional Testing\n\nInformation about [Functional Testing](./docs/functional_testing.md) in the docs/ folder.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsilinternational%2Fssp-base","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsilinternational%2Fssp-base","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsilinternational%2Fssp-base/lists"}