SAML: Data field mapping and admin rights

After the technical SAML connection, data field mapping and permission options determine which edoobox identity and permissions are used. Start with a test login and check every intended role scenario.

Open and save mapping

Open Settings → SAML (SSO) and select the provider.
Switch to Data field mapping. The table shows the label, description, edoobox field and received attribute.
Click Edit. The JSON editor opens the complete current mapping.
Adapt the attribute names to the names actually supplied by the Identity Provider.
Save valid JSON with Save in the Mapping tab. The general configuration button is a separate saving step.

Align standard fields

edoobox field	Google/generic SAML	Microsoft claim
`email`	`email`	`http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress`
`first_name`	`givenName`	`http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname`
`last_name`	`sn`	`http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname`
`acl`	`edoobox.acl` when importing admin permissions is enabled

Compare the exact names. A display name such as “Email” in the provider portal is not automatically the same attribute name as email. First name, last name and email must be mapped appropriately. Use each of these edoobox standard fields only once.

Distinguish NameID from data fields

The NameID is the permanent identifier of the SAML identity. Edoobox uses the provider and NameID to find an existing SAML link again. The mapped email field is additionally used for data matching or the initial link.

Under Configuration → NameID format, choose Email Address, Persistent or Unspecified. Agreement and value come from the Identity Provider. Only change the identifier of a provider already in use after a controlled test; a different identifier can change the existing association.

The supplied NameID must contain at least five characters. Use a permanent identifier; a short internal number such as “123” is rejected even if the rest of the mapping is correct.

Link existing admins

Enable Link admins with SAML if existing active admins should be linked using the same email address. Without such linking, a new admin identity must be authorised through enabled ACL import. An unknown IdP user does not gain admin access through their email address alone.

If you want to maintain permissions in edoobox, leave ACL import disabled and use existing authorised admins. After login, check the permission profile actually present.

Import admin permissions from SAML

The Permission management via edoobox option enables evaluation of the SAML attribute mapped to acl. Add the attribute to the mapping and have the Identity Provider send the intended values:

Value	Result
`edoobox.acl.0` or `edoobox.acl.1`	No permitted admin access.
`edoobox.acl.2`	Instructor permissions.
`edoobox.acl.3`	Administration permissions.
`edoobox.acl.4`	Superadmin permissions.

If several levels are supplied, the highest is evaluated. In particular, check people with multiple group memberships. Missing or inappropriate ACL values are a configuration error; do not rely on the selected fallback permission replacing missing authorisation.

Example: course administration supplies only edoobox.acl.3. The small group responsible for the account supplies edoobox.acl.4. Test both roles and an unauthorised person before enabling further people.

Map additional participant fields

In addition to standard fields, additional participant data fields data_1 to data_30 can be populated from SAML. Identify beforehand which participant data field belongs to the intended content. These additional fields affect participants only.

The following complete example uses generic attribute names and adds the employee number in additional field 5. Replace the attribute names and field number with your actual configuration:

[
  {"name":"Email", "description":"Business email", "attr":"email", "field":"email", "only_user":false},
  {"name":"First name", "description":"First name", "attr":"givenName", "field":"first_name", "only_user":false},
  {"name":"Last name", "description":"Last name", "attr":"sn", "field":"last_name", "only_user":false},
  {"name":"Employee number", "description":"Custom participant field 5", "attr":"employeeNumber", "field":"data_5", "only_user":true}
]

For admin ACL, additionally add a line with "attr":"edoobox.acl" and "field":"acl" for a provider intended for this purpose. Only enable permission import once the provider actually supplies the attribute.

On later participant logins, existing non-empty attribute values update the mapped data. Missing or empty values do not routinely overwrite existing participant data with empty content. For newly created participants, the required mapped values must be present.

Verify additional fields using a test profile

A successful login initially confirms access. Also check in the participant profile and data field configuration that every required additional field arrived correctly. The visible label “Employee number” is not a technical SAML field name: what matters is the Identity Provider’s exact attribute name and the matching edoobox field slot, for example data_5.

For each field, note its purpose, edoobox field slot and data type, and exact IdP attribute name. Agree an unambiguous value format; for identifiers with leading zeros, use a suitable text field. Date or selection fields require values matching their configuration.
Add the association to the complete mapping and save. For a scalar profile value, use exactly one intended attribute value. For a multi-valued SAML attribute, participant matching takes the first value, not a combined list.
Sign in a new test person and then open their profile. Compare email, first name, last name and all additional fields with the expected values.
Change a value at the Identity Provider and sign in the same person again. Check that the same record is updated and the new value appears in the correct field.

Test case	Expectation and consequence
New person, all mapped attributes populated	A profile is created; check every field and its display in the profile.
New person, an additionally mapped attribute is missing or empty	The new participant login may fail. This requirement also applies if the field is optional in the normal booking form. Therefore, only map fields that the provider reliably supplies for new people.
Existing person, a new non-empty value	The mapped profile value is updated on the next login. This can also overwrite a previous manual change.
Existing person, attribute missing or empty	The existing value is retained. An empty IdP attribute is not a reliable deletion instruction.
Attribute contains multiple values	Check the provider’s ordering; only the first value is imported into the participant field.

If there is an error, first check the field slot, attribute spelling and supplied value. Then correct the mapping or IdP output and repeat the same case. Participant field mapping does not grant admin permissions or replace provider tags or offer filters.

Troubleshooting

Cannot save: check JSON syntax, the complete structure and duplicate standard field assignments.
A new person cannot sign in: check login scope, NameID, required attributes and, for admins, the permitted linking or valid ACL.
Existing participant data appears unchanged: check that the attribute is supplied and non-empty, and that you selected the correct additional data field.
Admin permissions are too high: check all supplied ACL values; a higher second role may override the expected lower role.