This walks through setting up a Joomla site so its visitors log in through another site (an Identity Provider) instead of - or in addition to - a normal Joomla username and password. If you instead want this site to be the one other sites log their visitors in through, see Setup Joomla! as an Identity 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. |
| Enable Identity Provider | Set this to No - this site doesn't need to accept logins from elsewhere just to send its own visitors out. |
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 - Connect this site to an Identity Provider
This is the main step: telling this site which other site to send visitors to for logging in, and what to do with them once they come back. Go to Identity Provider Profiles -> New. The form is split into a few tabs:
Settings
- Name - anything descriptive.
- Alias - filled in automatically from the name; used in the login link and must be unique across every connection on this site (see "Avoiding naming conflicts" below).
- Protocol - leave as saml unless a developer has told you to connect this site directly to a company directory (LDAP) instead of another SAML-based site.
- Published - must be Yes.
Authorization SAML
- Identity Provider Metadata URL - the web address the other site gave you for its Identity Provider (see the setup-as-identity-provider guide, Step 3). If they instead gave you the technical details directly rather than a working address, paste them into Identity Provider Metadata XML instead.
- Identity Provider Login URL - leave this empty in almost every case; it's worked out automatically from the address above. Only fill it in if a developer specifically tells you to (this mainly comes up with older Microsoft ADFS-style setups), since an outdated value here is a common cause of login failures after the other site changes something.
- The Private Key File / Certificate Key File fields are only needed if this connection should sign its logout requests or its own technical details - most setups can leave these blank.
Joomla
Controls what happens to the visitor once they're identified by the other site:
| Field | What it does |
| Default Usergroup | Which Joomla group a new visitor is placed into. |
| Usergroup Mapping | Automatically place visitors into specific Joomla groups based on information sent back by the other site. |
| Sync Usergroups At Login | Re-check group membership every time the visitor logs in. |
| Create User | Whether a visitor who's never logged in here before gets a new Joomla account automatically (recommended Yes for most setups). |
| Redirect After Login | Where to send the visitor after a successful login; leave as-is to just stay on the page they were on. |
Field Mapper
Different sites can call the same piece of information by different names. This tab lets you match up what the other site calls something (its Identity Provider fieldname) with what this site expects to receive (its Local Fieldname - typically email address, name, first/last name, or username). If visitors' names or emails aren't coming through correctly after a login, this is usually the tab to check.
Save.
Step 3 - Register this site with the Identity Provider
This site trusting the other site isn't enough on its own - the other site also needs to be told to trust logins coming from this one. Find this site's own address for that purpose:
<scheme>://<host>/<baseurlpath>module.php/saml/sp/metadata.php/<profile-alias>
for example https://your-site.example/sso/module.php/saml/sp/metadata.php/idp (using the Alias from Step 2). The URL can also be found in the list of Identity Providers. Send that address to whoever manages the Identity Provider, so they can add it under their own Service Provider Clients screen - see Setup Joomla! as an Identity Provider).
Step 4 - Add a way to log in
Pick whichever fits your site:
- A login button on the front end: add the RO SSO module to a menu position and set its Identity Provider Profile field to the connection created in Step 2.
- A direct link: link to index.php?option=com_sso&task=login.login&profile=<alias> from anywhere on the site (a custom menu item, a button in an article, etc.).
- A login button on the admin login page: go to Components -> RO SSO -> Options, turn on Enable Backend Login, and set the profile to use on the Authentication - RO Single Sign In plugin's settings. This adds an SSO button to the normal Joomla admin login form. This uses the default Joomla template, if you have your own template or an override, you will need to modify this yourself to show the Single Sign On login button.
Step 5 - Keep things up to date automatically
Once this connection is set up, ask your host or developer to schedule a recurring task ("cron job") on the server so this site automatically notices changes on the other end (like a renewed certificate). The command to use is shown on the RO SSO dashboard (Components -> RO SSO):
/usr/bin/php <site>/libraries/simplesamlphp/modules/cron/bin/cron.php -t hourly > /dev/null 2>&1
Step 6 - Test it
- Use the login button or link from Step 4.
- You should be sent to the other site (or straight through if already logged in there), then back here already signed in as a Joomla user.
- If it doesn't work, visitors only see a generic "single sign-on login could not be completed" message - check libraries/simplesamlphp/log/simplesamlphp.log for the real reason, or ask a developer to.
Avoiding naming conflicts
The Alias chosen in Step 2 needs to be unique across every connection on this site - including any Service Provider Clients, if this site is also set up as an Identity Provider (see Setup Joomla! as an Identity Provider). Reusing a name can cause one connection's details to silently overwrite another's, breaking logins.
Common problems
- "Metadata not found" errors - open and re-save the Profile from Step 2; this usually resolves a mismatch after the Identity Provider's details changed.
- Connecting to Microsoft Entra ID / Azure AD or ADFS - the address Microsoft gives you for federation metadata is often not quite what's needed for the Identity Provider Login URL field; if logins fail after importing it, ask a developer to double-check that value against what Microsoft actually issues logins from.
- Visitors get logged out unexpectedly, or see "unsolicited response" errors - usually a cookie setting mismatch; make sure the site is fully served over HTTPS and ask a developer to check the session cookie settings if this keeps happening.
- A visitor's name/email/username doesn't come through correctly, or no new account gets created - check the Field Mapper tab from Step 2 against what the other site actually sends; turning on Enable Debug on the Configuration screen temporarily and checking the log file can show exactly what was received.
- Connecting directly to a company directory (LDAP) instead of another SAML site - this needs developer involvement to get the connection details right; the LDAP-specific fields under the Authorization tab are what they'll need to fill in.
A note on multi-factor authentication
Whether a passwordless login (like a passkey) on the Identity Provider lets a visitor skip this site's own MFA prompt depends on the Identity Provider actually reporting that - not all of them do. See Multi-factor authentication (MFA) and single sign-on for the full picture, including a setting under Users -> Options that controls this.