This walks through turning a Joomla site into a SAML Identity Provider - the site that other Joomla sites will send their visitors to for logging in, using this site's own user accounts. If you instead want this site to log its visitors in through another site, see Setup Joomla! as a Service Provider. To make one site do both at once (including testing against itself), see Setting up a site as both an Identity Provider and a Service Provider.
Before you start
- Install pkg_ro_sso_version.zip (or the individual extension zips) via System -> Manage -> Install.
- Go to System -> Manage -> Plugins, find Authentication - RO Single Sign On, and enable it.
- Go to System -> Manage -> Plugins, find System - RO Single Sign On, and enable it.
- During the installation RO Single Sign On will create a symlink. In case this fails, you will need to do this yourself. This one step needs server/hosting access rather than the Joomla admin - ask your host or developer if you don't have it: a shortcut ("symlink") named sso needs to be created in the site's root folder, pointing at libraries/simplesamlphp/public/. This is what makes the login pages reachable while keeping the rest of that folder private:
ln -sfn libraries/simplesamlphp/public sso - Go to Components -> RO SSO -> Configuration.
Step 1 - General settings
Fill in and save:
| Field | What to put there |
| Base URL Path | The folder name from the symlink step above, e.g. sso/. |
| Administrator Password | A password for SimpleSAMLphp's own separate admin panel. |
| Secret Salt | Any random string - used internally to secure sessions/cookies. |
| Technical Contact Name / Email | Shown to other sites as the contact for this Identity Provider. |
| Default Language / Available Languages | Which language(s) the login/error pages are shown in. |
Leave Production on and Enable Debug off for normal use - Debug adds extra detail to the log file, useful temporarily while troubleshooting a problem, but should be turned back off afterwards.
Step 2 - Create a certificate
Go to Certificates -> New and fill in the organisation details (Country, Province, City, Company Name, Department, Domain Name, Email Address) plus a Password. Saving creates a certificate and private key for this site to sign its logins with - you'll need at least one before the Identity Provider can be turned on.
Step 3 - Turn on the Identity Provider
Back on Configuration, set Enable Identity Provider to Yes. A few more fields appear:
| Field | What to put there |
| Private Key File / password, Certificate Key File | The certificate created in Step 2. |
| Login Module | How visitors are actually verified. Leave this as the default, `joomla:Joomla`, so visitors log in with their normal Joomla username and password. Only change this if a developer is setting up a different source (e.g. a company directory) for you. |
| Custom Theme / Theme Controller | Optional custom look for the login/error pages - see Multi-factor authentication (MFA) and single sign-on. Leave blank for the default look. |
| Consent Module | Optional - if enabled, asks visitors to approve sharing their details before sending them back to the other site. |
Save. A web address is now available for other sites to add as this Identity Provider - it looks like https://your-site.example/sso/saml2/idp/metadata.php. Open it in a browser to confirm it loads (it'll show some SAML technical data, not a normal page - that's expected). This is the address to give to anyone setting up their site to log in through this one.
By default, logging in through this Identity Provider only checks a password - it does not require or check multi-factor authentication, even for accounts that have it turned on. See Multi-factor authentication (MFA) and single sign-on for what this means and how another site had worked around it.
Step 4 - Trust a Service Provider
Before another site can log its visitors in through this one, it needs to be added here as a trusted destination. Go to Service Provider Clients -> New:
| Field | What to put here |
| Name | Anything descriptive, e.g. the other site's name. |
| URL | The web address the other site gave you for its own login setup. If they can't give you a working address, they can send you the technical details directly to paste into Metadata XML instead. |
| Output Folder | A short unique name for this connection - doesn't need to mean anything, just avoid reusing a name already used elsewhere in RO SSO (see "Avoiding naming conflicts" below). |
| Expire Days | How many days this site's copy of the other site's details is trusted before it needs refreshing. |
| Attributes | Optional - lets you rename what this site calls a piece of information (like email address) to match what the other site expects to receive it as. |
| Published | Must be Yes to use this Service Provider. |
Save.
Step 5 - Keep things up to date automatically
This site periodically re-checks the details of every trusted site to catch things like renewed certificates. For that to happen automatically, ask your host or developer to schedule a recurring task ("cron job") on the server - the exact command to use is shown on the RO SSO dashboard (Components -> RO SSO), and looks like:
/usr/bin/php <site>/libraries/simplesamlphp/modules/cron/bin/cron.php -t hourly > /dev/null 2>&1
Without this, connections will keep working day-to-day but won't notice when something changes on the other end until someone manually refreshes it.
Step 6 - Test it
- From the other site, trigger a login that points at this Identity Provider.
- You should land on this site's login page (or be signed straight through, if already logged in here), log in, and be sent back to the other site already signed in.
- If something goes wrong, the visitor only sees a generic error message - check `administrator/logs/simplesamlphp.log` for the actual technical reason, or ask a
developer to.
Avoiding naming conflicts
Every connection on this site - whether it's a site trusted to log visitors in through this one (Step 4 above) or, if this site is also set up as a Service Provider, a site this one logs its own visitors in through - needs its own unique name. Reusing a name that's already in use elsewhere can cause one connection's details to silently overwrite the other's, breaking logins until it's re-added. RO SSO blocks the obvious case of reusing an existing name when saving, but it's worth double-checking your list of names is all distinct.
Common problems
- Visitors get a generic error message when logging in - check administrator/logs/simplesamlphp.log for the real error.
- "Metadata not found" errors - double-check the address you gave the other site for this Identity Provider still loads correctly in a browser.
- Signing/certificate errors - create a new certificate under Certificates, then open and re-save the affected Service Provider Client so it picks up the change.
- A visitor's name/email/username doesn't come through correctly - a developer likely needs to adjust how this site maps a visitor's details before sending them onward; point them at the Attributes field under Step 4, or the equivalent settings for a self-loop setup.
- "Internal Server Error" after changes - this is usually a file-permissions issue on the server rather than something fixable from the Joomla admin; ask your host or developer to check that the `libraries/simplesamlphp` folder is readable/writable as expected and that the symlink is setup correctly.