Attribute mapping

This feature is designed to make data from your systems available for you to use within our systems. You are responsible for complying with all local policies and laws that may apply.

When you connect a local authentication system to OpenAthens you have the ability to map attributes from one system to the other - e.g. the 'mail' attribute from LDAP could be mapped to an Email address attribute in OpenAthens. This kind of mapping can achieve two things:

1. When you list accounts, you will be able to see or search your users by any mapped attribute, just like with OpenAthens accounts
2. Attributes that your local source passes to OpenAthens can in turn be released to service providers, subject to the release policy of course
3. These attributes can be used in the reporting interface

In both cases you can map as many or as few attributes as you need to accomplish your goals.

If the values of the attributes in your local system are not what you quite need, there is also an attribute transformation option.

Screenshots on this page are from an LDAP connection, but mappings are set up in the same basic way for any type of local authentication system.

Adding or editing a mapping

Prerequisites:

• If you will be using these attributes for reporting, releasing data to publishers, or you need them to match existing OpenAthens accounts then you must create them in your OpenAthens attribute schema first
  
  
• You will need to know the names of the attributes available from your local connection and what they are for. Your IT colleagues will be able to give you a list if they are not with you when you do this.
  
  
  • Attribute and claim names are case sensitive

To add a mapping

1. Click the add mapping button on the attributes tab of your local area connection
   
   
2. Enter the name of the attribute you are mapping from. 
   
   
3. Enter the target name.
   1. Existing OpenAthens attributes will appear as choices as you type - if you want to set the attribute as releasable or reportable it will need to be in your account schema first.
   2. There are some target names you can't use because the system has already defined them.
      
      
4. Enter a display name. The system will have had a guess at a display name for you but this can be changed if you like.
   
   

   

   
   
   
5. Click done
   
   
6. Repeat the process to add any more mappings and then use the save changes button

To edit a mapping

1. Click the edit button visible when you hover over a mapping on the attributes tab of your local area connection
   
   

   

   
   
   
2. You can edit the local connection attribute name and the display name. You cannot edit the target name.
   
   

   

   
   
   
3. Click done
   
   
4. Repeat the process to edit any other mappings and then use the save changes button

Removing a mapping

To remove a mapping:

1. Find the mapping in question on the attributes tab of your local connection
   
   
2. When you mouse over the mapping you will see options to edit or remove it
   
   

   

   
   
   
3. Click on remove and then confirm the deletion in the confirmation box

Anything to watch out for?

You can have only have one rule of any type per target attribute.

Any changes you save will go live almost immediately but do not affect users until the next time they sign in to OpenAthens - i.e. a user with an active browsing session will continue to use the old settings until their session ends (this is most relevant when you are testing your changes).

When you add a mapping to an existing schema attribute that is releasable, then the data in the local connection attributes you map becomes releasable too. This is usually both deliberate and desirable but may not always be so. You should be aware of and understand your release policies before adding a mapping to any releasable OpenAthens attribute.

When you remove a mapping, the data will no longer available to the system which has implications if anything is using it, especially if it is being used for access to a resource.

Mapped data is truncated to fit when it is too large and this may become relevant if you are mapping to the username, forenames or surname attributes as those are limited to 20 characters.

Only fields considered attributes can be mapped as attributes - e.g. only the data in the attribute statement sent by SAML or the API connectors. This is most likely to affect you if you use the API connector - see: Implementing the API connector in your code

If you are mapping to a releasable attribute that would be scoped in a federation context (e.g. eduPersonPrincipalName), then OpenAthens will add the scope. If you send values that already include a scope you will end up with values such as value@organisation.org@organisation.org (which will not work).