Skip to main content
Skip table of contents

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:!!84e411ea-7daa-4a57-bbf6-b5cc52981b73)
  • 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:

NameemailAddressemailchanges the attribute name emailAddress to the claim name email
Value@(.*)$1Removes all but the domain part of a scopedAffiliation value or email address



Strips everything before the final slash in a name and replaces it with mynamespace - e.g.

changes couldbeanything/somethingelse/role to mynamespace/role

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.

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.