Prerequisites and assumptions

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

Go to Resources > Permission sets > Add.

Give it a description, choose a role from the list and click add

Allocate / remove permission sets

List accounts (or search)

For one or more accounts:

Select the boxes next to the accounts

From the actions menu that appears, select the allocate or remove permission sets option as appropriate

In the dialog box, select the permission sets you want to act on and hit the allocate button

For single accounts you can also:

Click the account username

Go to the permissions tab

Select or clear permission sets as required and save changes

Modify a permission set

Go to Resources > Permission sets and click on the relevant permission set

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:

Using the schema editor (see below) select the permission set tab and create a text attribute with a target name of:

urn:oid:1.3.6.1.4.1.5923.1.1.1.7

Give it a display name and select the releasable box

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

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:

Go to Preferences > Schema editor.

Drag a type of attribute such as text into the custom attributes section and configure it

The 'target name' is what will be sent to service providers

Select the releasable box to have it appear in the release policy section

Click done and save changes

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:

On the second page of the wizard, select the boxes for unique identifier and unique scope then finish working through the wizard

Impersonate the new organisation by any of:

Open the account details and click the Impersonate button next to the trash button

From any list view of organisation accounts, click the icon

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.