OpenAthens test accounts

There are a large number of things you can test and experiment with just using your own domain's OpenAthens accounts. This page shows you the ways you can manipulate things.

When you change things you will need to kill your OpenAthens session. Our QA team say that keeping the sign-out page open in a tab is the most convenient method: https://login.openathens.net/signout 

Prerequisites and assumptions

• You have access to the OpenAthens admin area at https://admin.openathens.net
• You can create, list and modify user accounts there

Methods

Changing roles

Roles as used by the the SAML federation attribute 'scopedAffiliation' are defined by what are called permission sets. A user-account can have anywhere from zero to 256 permission sets, but generally they will have one or two.

Why this should be tested

You should test what happens when an account has more than one role since you are very likely to have to deal with more than one at a time - the role attribute (scopedAffiliation) can be multi-valued in SAML and you cannot predict in which order the values will be sent (even for the same user). 

Create permission sets

1. Go to Resources > Permission sets > Add.
2. Give it a description, choose a role from the list and click add

Allocate / remove permission sets

1. List accounts (or search)
2. For one or more accounts:
   1. Select the boxes next to the accounts
   2. From the actions menu that appears, select the allocate or remove permission sets option as appropriate
   3. In the dialog box, select the permission sets you want to act on and hit the allocate button
3. For single accounts you can also:
   1. Click the account username
   2. Go to the permissions tab
   3. Select or clear permission sets as required and save changes

Modify a permission set

1. Go to Resources > Permission sets and click on the relevant permission set
2. On the attributes tab modify the role as required

To test with entitlement values (if you think you will need to use them), a workaround is required since the administration area you are using cannot display your resource until it is made live in the federation. This is not how your customers would do it:

1. Using the schema editor (see below) select the permission set tab and create a text attribute with a target name of:
   1. urn:oid:1.3.6.1.4.1.5923.1.1.1.7
2. Give it a display name and select the releasable box
3. Click done and save

What this does is give you an attribute that will appear on the attributes tab of a permission set that you can set a desired value on. Unlike a real entitlement that would be released to a specified service provider, this version would be release to all service providers you visited one enabled under release policies (see below).

Releasing attributes

The attributes released by OpenAthens are controlled under Preferences > Attribute release. If you cannot see that menu option you will need to log out and use the domain administrator credentials.

Standard attributes are always released under the global policy, and additional attributes can be released to specified service providers. They would usually be set up to release the bare minimum in the global policy and add additional policies for any specific service providers who need additional attributes, or have other non-standard methods.

For the widest compatibility with all federations you should avoid configuring your application to need or require any more than the three standard federation attributes (scopedAffiliation, targetedID and entitlement), however here is how to play about with them if you want to. Unless you are using your OpenAthens domain to access other resources in the live environment, you can get away with just making changes to the global policy.

Why you might want to test this

This should only need to come up if you are expecting to work from SAML attributes that are not normally sent by default. E.g if your app would ask a new user for their name and email, you could make use of those values if they are present to save the user entering them (as said elsewhere in these docs though, you should not insist on them being sent or rely on them being present).  

Modifying attribute release

1. Go to Preferences > Attribute release, move your mouse over the global policy and click on Edit
2. Click attributes to toggle them between released or not
3. Click done and then save to make the changes live

You need to use the global policy as, like with the entitlement attribute above, your resource won't appear yet. Once live your customers would add a specific policy for you. 

Creating additional attributes

If you need to play with an attribute with a different target name (i.e. the name that the mapping rules would see and then translate to an OIDC claim), this can be created in the schema editor:

1. Go to Preferences > Schema editor.
2. Drag a type of attribute such as text into the custom attributes section and configure it
   1. The 'target name' is what will be sent to service providers
   2. Select the releasable box to have it appear in the release policy section
3. Click done and save changes
4. Jump over to Preferences > Attribute release and mark it for release

You will need to update your test accounts or permission sets with values for this new attribute.

Changing federation scopes

You can set up a sub-organisation below your domain which will have a different scope.

Why you should test this

Different parts of the same customer entity can have different scopes. In OpenAthens this will usually resemble sub-domains, but in some cases you might find totally different internet domains used by the same entity.

Changing scope

OpenAthens does so by adding a number in-front of your domain scope. This is how a consortium such as NHS England, or the VA in the USA does it. To set this up:

1. Create a new organisation account via Accounts > Add > Organisation account.
2. On the second page of the wizard, select the boxes for unique identifier and unique scope then finish working through the wizard
3. Impersonate the new organisation by any of:
   
   1. Open the account details and click the Impersonate button next to the trash button
   2. From any list view of organisation accounts, click the icon
4. Create an account there. This account will have a different federation scope

Not releasing expected attributes

You will want to be able to test what happens when expected federation attributes are not sent. It is not possible to turn off the targetedID attribute with OpenAthens, but you can turn off the scopedAffiliation one by setting the role on a permission set as blank and making sure that set is the only one used by a test account.

Since the most important consideration in most cases is the organisation identifier (the federation scope included with the role), this is likely sufficient for your testing needs.