Add and manage custom SAML resources

Path to function: Resources > Catalogue > Custom

Custom resources, once created, can be allocated to permission sets like any other resource. This page is about custom SAML resources rather than /wiki/spaces/MD/pages/5079902.

Custom SAML resources were developed for SSO to things like your VLE, /wiki/spaces/WWTPA/pages/12124496 or /wiki/spaces/WWTPA/pages/12026000. You can also use them for peer to peer access to SAML resources that have not yet got enough subscribers to benefit from membership of a federation (which makes things much easier for all parties). In both situations, this should work for any SAML target that adheres to the SAML 2 core specification (http://saml2int.org/profile/current).

Because SAML requires a resource to have a unique identifier (entityID) they can only be added at the domain level.

Custom SAML resources will appear in reports alongside regular and proxy resources.

You will also need to tell the custom resource your OpenAthens details - see: /wiki/spaces/MD/pages/5079134

Add a new custom SAML resource

As the domain administrator, go to the custom tab of the resource catalogue and click the create button. Choose the SAML option.

You are first asked for the resource's metadata and you can supply the URL or upload a file:

Pop-up window titled 'Add a SAML resource'. It displays the message 'Upload SAML 2 metadata via a URL or file'. There is a text field labeled 'Metadata URL' and a button labeled 'Upload file'. At the bottom of the window are buttons labeled 'Create resource' and 'Cancel'.

This creates the resource, but it may not have the friendliest of names at this point as the name is drawn from the metadata and it will fall back to the entityID. If you click on the name in the resource catalogue, you can edit the name, description and logo if you need to.

Custom SAML resources are identified in the catalogue with a 'SAML' tag:

Example of a custom SAML resource called 'Google Apps'. Beside the title and description of the resource is the label 'saml'.

You will almost always need to tell the other application about /wiki/spaces/MD/pages/5079134 or endpoints before it will work, and you commonly have to add a custom /wiki/spaces/MD/pages/5079882 so that the target gets sent the attributes it is expecting - there are examples of this using /wiki/spaces/WWTPA/pages/12124496 or /wiki/spaces/WWTPA/pages/12026000.

It can take a few minutes for the resource to be live.

SAML 1.x is not supported for this kind of connection.

Manage an existing custom resource

As well as being able to edit names and descriptions, custom SAML resources have two additional tabs which allow you to view certificate details and update the metadata. You might need to update the metadata, for example, when the resource has changed its certificates or endpoints. If you created the custom resource by uploading a metadata file, you would need to delete the resource and then re-upload the new metadata.

Updating the metadata will overwrite any customisations you have made to other fields, so should be done only when necessary. If you have deleted and recreated the resource, you will need to reassign it to any permission sets.

Delete a custom resource

From the catalogue, click on the resource title to bring up its details page and click on the trash button next to the save button.

'Modify resource' screen of a custom resource. At the top of the page are buttons labeled 'Delete custom resource', which is highlighted, and 'Save changes'.

Allocate a custom SAML resource

Custom SAML resources can be /wiki/spaces/MD/pages/5079422 to permission sets in the same way as any other resource or custom resource.

Anything to watch out for?

Every few years we have to /wiki/spaces/MD/pages/413433857 which will affect these connections and require an update at the resource end. Since that end is both variable and unknown to us, we recommend you make and keep notes on how the resource end is configured. It could be as long as 9 years before you need to refer to those notes, so local retention policies could become relevant.

Where SAML resources do not adhere to the SAML 2 core specification, they might not be able to work with OpenAthens this way. Whilst our service desk will always try to be helpful, they can only support the OpenAthens end of the connection; they will of course be happy to put the publisher in touch with someone who can talk to them about the benefits of federation membership.