Mapping SAML attributes to OIDC claims
As you would imagine, a mapping process exists so that you can specify an incoming and outgoing attribute names. These mappings are defined under the rules menu, and need to be switched on or off on the connection used by the application. Where a connection is used by multiple applications, the rules will apply to all the applications.
See also: Standard attributes in the OpenAthens federation
Default rules
Out of the box there are some useful rules that we have pre-defined for you:
Affiliation and scope derived from eduPersonScopedAffiliation- This one separates out scope and role from the single SAML attribute that contains both
- Scope is the recommended organisation identifier in SAML
- It is not turned on by default, but is often useful
- A user might have several roles, but they will all have a common scope
Common EduPerson- Set on by default for new connections
- This one maps the four most commonly used SAML attributes to sensible claim names (targetedID, pairwiseID, scopedAffiliation and entitlement)
Extended EduPerson- This one maps all the less common SAML attributes and will usually not be necessary
Normalised targetedID- This one adds together the IdP entityID, SP entityID to the end-user's targetedID and normalises it.
- It should only be needed if you are migrating from Shibboleth and were using the longform version of targetedID so that you can maintain user IDs
- (Longform example:
https://idp.example.org/openathens!https://sp.example.org/oa/metadata!84e411ea-7daa-4a57-bbf6-b5cc52981b73)
- (Longform example:
Shortened OIDC subject (52 characters)- Some OIDC relying parties have a limit on the length of the sub field, for example AWS Cognito. This rule creates a 52 character identifier which will be consistent for that user for you.
The rule for legacy OpenAthens is not necessary for new services and is included only to help publishers migrate old services to federation identifiers.
Many eduPerson attributes can be multi-valued - for example a user might have roles of 'student' as well as 'member' - so you should expect to receive unordered arrays - e.g. { "claimName" : [ "value1", "value2"] }
Additional rules
There are a couple of rule types you can use to extend the mapping capability. The simple mapping rules can modify both the name and value using regular expressions - some examples:
| Type | Incoming | Outgoing | Notes |
|---|---|---|---|
| Name | emailAddress | email | changes the attribute name emailAddress to the claim name email |
| Value | @(.*) | $1 | Removes all but the domain part of a scopedAffiliation value or email address |
| Name |
| mynamespace$1 | Strips everything before the final slash in a name and replaces it with mynamespace - e.g. changes |
To create or edit a rule set
Rule sets are created and managed from the rules menu on the side of the publisher dashboard. To add a new one click the green button at the top of the page:
To create or edit a rule
Once you have your rule set, you can populate it with rules.
You can either add a new mapping, or edit, clone or delete an existing one via the dots menu next to each rule.
To edit a rule:
This example uses a regular expression to extract the internet domain from an email address after changing the name to emailDomain.
If you do not add anything to the either box in the value line, the value is unchanged.
In the unlikely event that the simple rules cannot give you the mappings you need, there is a javascript editor available for more complex situations. See: Mapping SAML attributes to OIDC claims with Javascript
Anything to watch out for?
If a rule doesn't appear to be applied, first check that it is turned on for the relevant connection and that connection has been saved.