The Federation Organization Source Plugin is designed to sync Organizations from SAML Federation metadata.
Federation Source is Experimental, and may change across minor releases.
Modes
| Organization Sync Mode | Support |
|---|---|
| Accrual | Supported |
| Full | Supported |
| Manual | Supported |
| Update | Supported |
Installation
This is a non-core plugin, see Installing and Enabling Registry Plugins for more information.
Configuration
Before configuring Federation Source, create a new HTTP Server via Servers > 
Add a New Server, and set the Type of the new Server to HTTP. On the Server configuration page, set the Server URL to the MDQ URL, eg https://mdq.incommon.org. In general, authentication is not required for querying MDQ servers, so the remaining attributes can be set or left blank appropriately.
After the Server is defined, add a new Organization Source via Configuration > Organization Sources > Add a New Organization Source. Set the plugin to FederationSource and then pick the newly defined Server on the plugin configuration page. (Note that Sync Modes are further defined in the Organization Sources documentation.)
Protocol
Federation Source supports two ways to retrieve Metadata, both using HTTP Servers.
- MDQ: The Metadata Protocol, which is the most efficient option but must be supported by the server.
- Metadata File: The Server URL configured above can instead be set to the full path to a metadata file, eg as returned by SimpleSamlPhp. Note that not all metadata files are constructed exactly the same way, it's possible some won't fully parse without further modifications. Also, Metadata files must be processed in their entirety, even when retrieving a single record. As such, this option should only be used for limited sets of records and not for a full federation's worth of entity data.
Considerations
Attribute Mapping
Federation Source relies on multiple standards to parse a metadata record into an Organization object. Not all MDQ servers may return metadata utilizing the same standards, and so the resulting Organization objects may differ.
| Attribute | SAML Source | Multiple? |
|---|---|---|
| Organization:description | mdui:Description* | No |
| Organization:logo_url | mdui:Logo, but only if populated with a URL (not actual image data)* | No |
| Organization:name | In order of preference: mdui:DisplayName, OrganizationName, or the entityID* | No |
| Organization:saml_scope | shibmd:Scope | No |
| Contact | ContactPerson, using whatever information is populated | Yes |
| Identifier (type: entityID) | entityID | No |
| Identifier (type: name) | OrganizationName, flagged with language tags when available | Yes |
| URL (type: official) | OrganizationURL, flagged with language tags when available | Yes |
*If multiple entries are found with different language tags, an English entry will be preferred, or else the first entry found is used
Cached Records
Because of the potential size of a collection of metadata records (see also Memory Requirements, below), and in order to facilitate processing, the cached record stored in the Organization Source Record is a JSON encoded copy of only those attributes used by Federation Source, and records will only be automatically reprocessed by Org Sync Job if one of those attributes changed. If, for example, the KeyDescriptor changes (which is not directly used by Federation Source to create Organizations), the record will not automatically resync since none of the attributes of interest changed.
Memory Requirements
When manually syncing individual records, the individual record is retrieved from the MDQ server, and so memory requirements are nominal.
When syncing records via Org Sync Job, regardless of the Sync Mode (Accrual, Full, or Update), the full set of entities must be loaded in order to be processed. While the resulting XML document is processed efficiently, the initial download can consume a fair amount of available memory. As a rule of thumb, PHP should be allocated between 2 and 3 times the size of the full metadata file. For example, the InCommon metadata file is currently around 55MB. Federation Source can successfully process this file with 128M allocated to PHP, though it might be safer to allocate 192M or 256M to allow for future growth. Processing the full file should take a few minutes on a basic server configuration.
Multiple MDQ Servers
It is possible to instantiate Federation Source multiple times, and sync records from multiple MDQ servers. If the same Entity ID is retrieved from multiple servers within the same CO, only the first instance will be synced (not yet implemented).
Search Interface
MDQ only supports retrieval by Entity ID, or retrieval of all available records. As such, Federation Source does not support searches by other attributes, such as organization name or URL.
See Also
- Locating the production metadata (InCommon MDQ documentation)
- Metadata for the OASIS Security Assertion Markup Language (SAML) v2.0
- Metadata Query Protocol (Internet Draft)
- SAML Profile for the Metadata Query Protocol (Internet Draft)
- SAML V2.0 Metadata Extensions for Login and Discovery User Interface Version 1.0
- ShibMetaExt V1.0
- Organization Sources
- cm_federation_sources