{"id":19591902,"url":"https://github.com/catalyst/moodle-auth_saml2","last_synced_at":"2025-05-16T19:07:28.725Z","repository":{"id":37939449,"uuid":"56109515","full_name":"catalyst/moodle-auth_saml2","owner":"catalyst","description":"SAML done 100% in Moodle, fast, simple, secure","archived":false,"fork":false,"pushed_at":"2025-05-12T21:21:31.000Z","size":50239,"stargazers_count":76,"open_issues_count":181,"forks_count":139,"subscribers_count":45,"default_branch":"MOODLE_500_STABLE","last_synced_at":"2025-05-12T22:30:52.950Z","etag":null,"topics":["idp","moodle","openam","saml-plugin","simplesamlphp"],"latest_commit_sha":null,"homepage":"https://moodle.org/plugins/auth_saml2","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/catalyst.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":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2016-04-13T01:03:02.000Z","updated_at":"2025-05-03T03:21:48.000Z","dependencies_parsed_at":"2025-04-12T18:39:39.117Z","dependency_job_id":"e81d32ce-e0d6-40eb-a470-2bf308a41465","html_url":"https://github.com/catalyst/moodle-auth_saml2","commit_stats":null,"previous_names":[],"tags_count":34,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/catalyst%2Fmoodle-auth_saml2","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/catalyst%2Fmoodle-auth_saml2/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/catalyst%2Fmoodle-auth_saml2/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/catalyst%2Fmoodle-auth_saml2/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/catalyst","download_url":"https://codeload.github.com/catalyst/moodle-auth_saml2/tar.gz/refs/heads/MOODLE_500_STABLE","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254592395,"owners_count":22097013,"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":["idp","moodle","openam","saml-plugin","simplesamlphp"],"created_at":"2024-11-11T08:31:40.786Z","updated_at":"2025-05-16T19:07:28.719Z","avatar_url":"https://github.com/catalyst.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![ci](https://github.com/catalyst/moodle-auth_saml2/actions/workflows/ci.yml/badge.svg?branch=MOODLE_404_STABLE)](https://github.com/catalyst/moodle-auth_saml2/actions/workflows/ci.yml?branch=MOODLE_404_STABLE)\n\nhttps://moodle.org/plugins/auth_saml2\n\n# 100% Moodle SAML fast, simple, secure\n\n![Churchill quote](/pix/churchill.jpg?raw=true)\n\n* [What is this?](#what-is-this)\n* [Why is it better?](#why-is-it-better)\n* [How does it work?](#how-does-it-work)\n* [Features](#features)\n* [Branches](#branches)\n* [Installation](#installation)\n* [Configuration](#configuration)\n* [Testing](#testing)\n* [Debugging](#debugging)\n* [Gotchas](#gotchas)\n* [Other SAML plugins](#other-saml-plugins)\n* [Support](#support)\n* [Warm thanks](#warm-thanks)\n\n\n## What is this?\n\nThis plugin does SAML authentication and user auto creation with field mapping.\n\n\n## Why is it better?\n\n* 100% configured in the Moodle GUI - no installation of a whole separate app,\n  and no touching of config files or generating certificates.\n* Minimal configuration needed, in most cases just copy the IdP metadata in\n  and then give the SP metadata to your IdP admin and that's it.\n* Fast! - 3 redirects instead of 7\n* Supports Single Logout via the HTTP-Redirect binding which many organisations require\n\n\n## How does it work?\n\nIt completely embeds a SimpleSamlPHP instance as an internal dependency, which\nis dynamically configured the way it should be by inheriting almost all of its\nconfiguration from Moodle configuration. In the future we should be able to\nswap to a different internal SAML implementation and the plugin GUI shouldn't\nneed to change at all.\n\n\n## Features\n\n* Dual login vs. forced login for all as an option, with `?saml=off` on the login\n  page for manual accounts, and `?saml=on` supported everywhere to deep link and\n  force login via SAML if dual auth is on.\n* SAML attributes to Moodle user field mapping\n* Automatic certificate creation\n* Optionally auto create users\n* Support for multiple identity providers\n* IdP initiated flow / IdP first flow / IdP unsolicited logins, eg:\n  http://idp.local/simplesaml/saml2/idp/SSOService.php?spentityid=http://moodle.local/auth/saml2/sp/metadata.php\u0026RelayState=http://moodle.local/course/view.php?id=2\n\n\nFeatures not yet implemented:\n\n* Enrolment - this should be an enrol plugin and not in an auth plugin\n* Role mapping - not yet implemented\n\n\n## Supported branches\n\n| Moodle version    | Branch             | PHP       | SimpleSAMLphp |\n| ----------------- | ------------------ |-----------|---------------|\n| Moodle 5.0        | `MOODLE_500_STABLE`| 8.2+      | v2.3.7        |\n| Moodle 4.5        | `MOODLE_405_STABLE`| 8.1+      | v2.3.7        |\n| Moodle 4.4        | `MOODLE_404_STABLE`| 8.1+      | v2.3.5        |\n| Moodle 4.1        | `MOODLE_401_STABLE`| 7.4+      | v2.0.5        |\n| Totara 19+        | `TOTARA_19`        | 7.4+      | v2.0.5        |\n| Totara 13+        | `TOTARA_13_STABLE` | 7.4+      | v2.0.5        |\n\n## Installation\n\n1. Install the plugin the same as any standard Moodle plugin, either via the\n[Moodle plugin directory](https://moodle.org/plugins/auth_saml2), or you can use\ngit to clone it into your source:\n\n   ```sh\n   git clone git@github.com:catalyst/moodle-auth_saml2.git auth/saml2\n   ```\n\n2. Then run the Moodle upgrade\n\n3. If your IdP has a publicly available XML descriptor, copy its URL into\n   the SAML2 auth config settings page. Otherwise copy the XML verbatim into\n   the settings textarea instead.\n\n4. If your IdP requires whitelisting each SP, use the links in the settings page\n   to download the XML, or you can provide that URL to your IdP administrator.\n\nFor most simple setups, this is enough to get authentication working. There are\nmany more settings to define how to handle new accounts, dual authentication,\nand to easily debug the plugin if things are not working.\n\n\n## Configuration\n\nFor setting up a new SAML integration, see the\n[Quick Start Guide](https://github.com/catalyst/moodle-auth_saml2/wiki/Quick-start-Guide).\n\nMost of the configuration is done in the Moodle admin GUI and should be self\nexplanatory for someone familiar with SAML generally. There are a few extra\nconfiguration items which currently don't have a GUI and should be added\nto your Moodle config.php file:\n\n```php\n$CFG-\u003eauth_saml2_disco_url = '';\n$CFG-\u003eauth_saml2_store = '\\\\auth_saml2\\\\redis_store'; # Use an alternate store\n$CFG-\u003eauth_saml2_redis_server = ''; # Required for the redis_store above\n```\n\n\n## Testing\n\nThis plugin has been tested against:\n\n* SimpleSamlPHP set up as an IdP\n* openidp.feide.no\n* testshib.org\n* An AAF instance of Shibboleth\n* OpenAM (Sun / Oracle)\n* Microsoft ADFS\n* NetIQ Access Manager\n\nTo configure this against testshib you will need a moodle which is publicly\naccessible over the internet. Turn on the SAML2 plugin and then configure it:\n\nHome ► Site administration ► Plugins ► Authentication ► SAML2\n\n1. Set the Idp URL to: https://www.testshib.org/metadata/testshib-providers.xml\n2. Set dual auth to Yes\n3. Set auto create users to Yes\n4. Click on 'Download SP Metadata'\n5. Save the settings\n6. Upload that file to: https://www.testshib.org/register.html\n7. Logout and login, you should see 'TestShib Test IdP' as an alternate login method\n   and be able to login via the example credentials.\n\n\n## Debugging\n\nIf you are having any issues, turn on debugging inside the SAML2 auth plugin, as well\nas turning on the Moodle level debugging. This will give in depth debugging on the SAML\nXML and errors, as well as stack traces. Please include this in any GitHub issue you\ncreate if you are having trouble.\n\nThere is also a stand-alone test page which authenticates but isn't a 'Moodle' page. All\nthis page does is echo the SAML attributes which have been provided by the IDP. This can\nbe very handy for setting up the mappings, e.g. when the IDP might be providing the\nright attributes but under an unexpected key name.\n\n```\n/auth/saml2/test.php\n```\n\nIf you can succesfully do a SAML login using this page then it narrows down where the\nissues lie. Some common issues are:\n\n1. You received a valid set of SAML attributes, but the attribute(s) needed are not\n   present. For example, often in ADFS configuration you may need to 'release' the username.\n\n2. You have got a valid set of attributes, but the key for the username isn't what\n   you expected. Cut and paste the correct key name into the Moodle auth saml2 config\n   page to correctly map the 'idpattr' value.\n\n3. The attribute key name might be a really crazy long looking string. This is common\n   with ADFS. If that long string contains certain characters then Moodle will not\n   accept it, and this is an issue in Moodle itself and applies to all auth plugins.\n   You can add a custom claim in ADFS to rename this attribute to something nicer.\n   See: [GitHub issue #124](https://github.com/catalyst/moodle-auth_saml2/issues/124).\n\n4. If it is bringing across all the attributes properly, but you are getting:\n   \"You have logged in succesfully as 'xyz' but do not have an account in Moodle\"\n   then you either need to change your user provisioning process to ensure users are\n   created ahead of time, or you need to enable the `autocreate` setting. If you do\n   auto create then you need to be very careful that auto-created users, and users\n   provisioned via other means, are set up consistently.\n\n\n## Gotchas\n\n### Bitnami Moodle\n\nWe get lots of complaints in many plugins that end up being issues with Bitnami. It does a very\npoor job and does not properly configure Moodle with some quite basic things and we strongly\nrecommend you don't use it at all, not just for SAML issues. In particular it dynamically\ndetects the domain that Moodle is on, which is not supported by Moodle. `$CFG-\u003ewwwroot`\nMUST be manually set to a static value in `config.php`.\n\n\n### Multiple IdPs\n\nWhen using multiple IdPs the system will force enable the dual login setting. This is so\nthat a list of possible identity providers will be presented to the user when logging in.\n\nTo enable multiple IdPs you can use the 'IdP metadata XML OR public XML URL' configuration\nfield. An example might look like this:\n\n```\nIdentity Provider Name https://ssp1.local/simplesaml/saml2/idp/metadata.php\nhttps://ssp2.local/simplesaml/saml2/idp/metadata.php\n```\n\nIf there is any text before the `https` scheme then it will be used as the override name.\n\nIt is not be recommended to use the 'IdP label override' configuration option with\nmultiple IdPs.\n\n\n### Deep linking saml=on URL parameter\n\nFor most use cases, this parameter should work on all supported Moodle versions. However, to make\nthis paramater force a SAML login redirect, even when users are already logged in as a guest, we\nuse a [Moodle hook](https://docs.moodle.org/dev/Login_callbacks#after_config) that is only available\nin Moodle \u003e= 3.8.\n\nTo make guest user redirecting work on moodle 3.7 and below, you will need to backport\nthe changes from [MDL-66340](https://tracker.moodle.org/browse/MDL-66340).\n\n\n### OpenAM\n\nIf you are getting signature issues with OpenAM then you may need to manually\nyank out the contents of the `ds:X509Certificate` element into a file and then\nimport it into OpenAM's certificate store:\n\n```bash\n$ cat moodle.edu.crt\n-----BEGIN CERTIFICATE-----\nthesuperlongcertificatestringgoeshere=\n-----END CERTIFICATE-----\n$ keytool -import -trustcacerts -alias moodle.edu -file moodle.edu.crt -keystore keystore.jks\n```\n\nThen follow the prompts and restart OpenAM.\n\n\n### Certificate Locking\n\nIt is possible to lock the certificates in the admin UI which prevents inadvertent\noverwriting of them. They can also be unlocked in the UI. If you really want to\nprotect them, `chown` the files so that your webserver user cannot modify them at all.\n\nThese certificates are located in the `$CFG-\u003edataroot/saml2` directory.\n\nTo manually unlock the certificates please restore the write permissions to the required files.\n```bash\n$ cd $CFG-\u003edataroot/saml2\n$ chmod 0660 site.example.crt\n$ chmod 0660 site.example.pem\n```\n\n\n### Windows configuration for OpenSSL\n\nSome environments, particularly Windows-based, may not provide an OpenSSL\nconfiguration file at the default location, producing errors like the\nfollowing when regenerating certificates:\n\n```\nerror:02001003:system library:fopen:No such process\nerror:2006D080:BIO routines:BIO_new_file:no such file\nerror:0E064002:configuration file routines:CONF_load:system lib\n```\n\nYou may also see OpenSSL errors in various Moodle screens (including the admin\npage) related to the `auth_saml2` plugin. For example:\n\n```\nWarning: openssl_csr_sign(): cannot get CSR from parameter 1 in\nC:\\path\\to\\moodle\\auth\\saml2\\setuplib.php\n```\n\nThere are two ways to resolve this problem (you only need to do one of these,\nthe first is probably more sensible):\n\n1. Set the `OPENSSL_CONF` environment variable to point to the full path and\n   location of an [`openssl.cnf`](https://www.openssl.org/docs/manmaster/man5/config.html)\n   file (e.g. `C:\\tools\\php73\\extras\\ssl\\openssl.cnf`) and restart Apache.\n\n2. (for PHP versions \u003c= 7.3) Make a copy of that `openssl.cnf` file in the\n   location `C:\\usr\\local\\ssl\\openssl.cnf`.\n\n\n### OKTA configuration\n\nOkta has some weird names for settings which are confusing, this may help decipher them:\n\n| Okta name             | Sane name             | Value                                                            |\n| --------------------- | --------------------- | ---------------------------------------------------------------- |\n| Single sign on URL    | ACS URL               | `https://example.com/auth/saml2/sp/saml2-acs.php/example.com`    |\n| Audience URI          | Entity ID             | `https://example.com/auth/saml2/sp/metadata.php`                 |\n| Enable Single Log Out | Enable Single Log Out | True                                                             |\n| Single Logout URL     | Single Logout URL     | `https://example.com/auth/saml2/sp/saml2-logout.php/example.com` |\n| Assertion Encryption  | Assertion Encryption  | Encrypted                                                        |\n\nSuggested attribute mappings:\n\n| Name        | Value            |\n| ----------- | ---------------- |\n| `Login`     | `user.login`     |\n| `FirstName` | `user.firstName` |\n| `LastName`  | `user.lastName`  |\n| `Email`     | `user.email`     |\n\n\n### Auth Proc Filter Hooks\n\nOther plugins may hook into SAML2 and create custom Auth Proc Filters.\nAuth Proc Filters allow you to mutate the attributes passed back from the IdP\nbefore Moodle handles them and maps them to profile fields.\n\nSteps to implement the hook:\n\n1. Create a plugin that will implement the hook (e.g `local_hookimplement`)\n2. Define the hook function `local_hookimplement_extend_auth_saml2_proc` in the plugin's `lib.php` file.\n3. The function should return an array of SimpleSaml Auth Proc Filters.\n\nExamples:\n\n```php\nfunction local_hookimplement_extend_auth_saml2_proc() {\n   return [\n      52 =\u003e array(\n         'class' =\u003e 'core:AttributeMap',\n         'oid2name'\n      )\n   ]\n}\n```\n\nCustom code:\n\n```php\nfunction local_hookimplement_extend_auth_saml2_proc() {\n   return [\n      51 =\u003e array(\n         'class' =\u003e 'core:PHP',\n         'code' =\u003e '$attributes = update_attributes($attributes)'\n      )\n   ]\n}\n\nfunction update_attributes($attributes) {\n   if (isset($attributes[\"uid\"])) {\n      $attributes[\"uid\"] =\u003e $attributes[\"username\"];\n   }\n   return $attributes;\n}\n```\n\nMultiple IdP filter:\n\n```php\nfunction local_hookimplement_extend_auth_saml2_proc() {\n   return [\n      51 =\u003e array(\n         'class' =\u003e 'core:PHP',\n         'code' =\u003e '$attributes = update_attributes($attributes)'\n      ),\n   ]\n}\n\nfunction update_attributes($attributes) {\n   global $SESSION, $saml2auth;\n    $idps = $saml2auth-\u003emetadataentities;\n    foreach ($idps as $idp) {\n        foreach ($idp as $key =\u003e $value) {\n            if ($SESSION-\u003esaml2idp == $key) {\n                $alias = $idp[$key]-\u003ealias;\n            }\n\n            if ($alias == 'idp_alias') {\n                $attributes[\"uid\"] = $attributes['username'];\n            }\n        }\n    }\n}\n```\n\n\n## Other SAML plugins\n\nThe diversity and variable quality and features of SAML moodle plugins is a\nreflection of a great need for a solid SAML plugin, but the neglect to do\nit properly in core. SAML2 is by far the most robust and supported protocol\nacross the internet and should be fully integrated into Moodle core as both\na Service Provider and as an Identity Provider, and without any external\ndependencies to manage.\n\nHere is a quick run down of the alternatives:\n\n### Moodle Core\n\n* `auth/shibboleth` - This requires a separately installed and configured\n  Shibboleth install.\n\n    One big issue with this, and the category below, is the extra\n    application between Moodle and the IdP, so the login and logout processes have\n    more latency due to extra redirects. Latency on potentially slow mobile\n    networks is by far the biggest bottleneck for login speed, and the biggest\n    complaint by end users in our experience.\n\n* `auth/oauth2`\n\n    OAuth2 has direct support in Moodle.\n\n\n### Plugins that require SimpleSamlPHP\n\nThese are all forks of each other, and unfortunately have diverged quite early\nor have no common git history, making it difficult to cross port features or\nfixes between them.\n\n* [moodle.org/plugins/auth_saml](https://moodle.org/plugins/auth_saml)\n\n* [moodle.org/plugins/auth_zilink_saml](https://moodle.org/plugins/auth_zilink_saml)\n\n* [github.com/piersharding/moodle-auth_saml](https://github.com/piersharding/moodle-auth_saml)\n\n\n### Plugins which embed a SAML client library\n\nThese are generally much easier to manage and configure as they are standalone.\n\n* [moodle.org/plugins/auth_onelogin_saml](https://moodle.org/plugins/auth_onelogin_saml) - This one uses its own\n  embedded SAML library which is great and promising, however it doesn't support\n  'back channel logout' which is critical for security in any large organisation.\n\n* This `auth_saml2` plugin, with an embedded and dynamically configured SimpleSamlPHP\n  instance under the hood.\n\n\n## Support\n\nIf you have issues please log them in\n[GitHub](https://github.com/catalyst/moodle-auth_saml2/issues).\n\nPlease note our time is limited, so if you need urgent support or want to\nsponsor a new feature then please contact\n[Catalyst IT Australia](https://www.catalyst-au.net/contact-us).\n\n\n## Warm thanks\n\nThanks to the various authors and contributors to the other plugins above.\n\nThanks to [La Trobe University](https://www.latrobe.edu.au/) in Melbourne for\nsponsoring the initial creation of this plugin.\n\n![LaTrobe](/pix/latrobe.png?raw=true)\n\nThanks to [Centre de gestion informatique de l’éducation (CGIE)](https://portal.education.lu/cgie/)\nin Luxembourg for sponsoring the user autocreation and field mapping work.\n\n![CGIE](/pix/cgie.png?raw=true)\n\nThis plugin was developed by [Catalyst IT Australia](https://www.catalyst-au.net/).\n\n\u003cimg alt=\"Catalyst IT\" src=\"https://cdn.rawgit.com/CatalystIT-AU/moodle-auth_saml2/MOODLE_39_STABLE/pix/catalyst-logo.svg\" width=\"400\"\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcatalyst%2Fmoodle-auth_saml2","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcatalyst%2Fmoodle-auth_saml2","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcatalyst%2Fmoodle-auth_saml2/lists"}