Continued integration of Keystone

Now that you've got a basic OIDC / Keystone setup working it's time to take care of how you interact with your federation customers. In most cases the preconfigured rules are all you need, but Keystone can handle more complicated things if you need it to.

Decisions to make

We don't know how your site is set up, but are assuming you already have some way of authorising access that results in a user having a session. We'll refer to this here as your authorisation flow.

You will also need to consider how the data available from Keystone will match up with whatever your site references to decide if a a valid subscription is in place - we'll refer to that here as your customer database. The recommended approach is to add support for the identifiers used in federations to your customer database as this has the minimum impact on your customers, and will make the addition of new federated customers easier for you in the long run.

The site identifiers in common use in federations are:

EntityID - this usually looks like a URL on a domain owned by the site but there doesn't have to be a web page there - e.g: https://idp.theirdomain.net/openathens. This is relevant to authentication, but rarely to authorisation.
Scope - this is always an internet domain owned by the site - e.g. theirdomain.net. A site might use sub-domains to separate organisational units - e.g. holbycity.theirdomain.net, sacredheart.theirdomain.net.

Of the two, Scope is the identifier to use for authorisation decisions as it allows large organisations to have multiple subscriptions with you, or for the subscription to be specific to one organisational unit. It also allows for the possibility of different authentication points within the same organisation, although in practice this is quite rare. Support for wildcards is recommended - e.g. *.theirdomain.net. See also: Entities with multiple scopes such as NHS England and consortia

Next is user identifiers.

You will receive a claim called 'sub', short for subject, but this is not persistent between sessions. If you want to track an individual between sessions for personalisation or statistics then there's something with the unlikely name of eduPersonTargetedID that is persistent for a user between sessions (called targetedID for short).

Decisions made, what do I turn on?

Assuming you're using Scope and targetedID, the preset rules will take care of things but they need to be turned on and this is done on the connection. The ones you want are 'Common EduPerson' and... the one with a very long name:

What you also need to know is what claim names contain the data you need as it is these claims that OIDC is making available to your system:

Thing you might want	Claim name
Scope	`derivedEduPersonScope`
EntityID	`realmName`
targetedID	`eduPersonTargetedID`

Now all you have to do is match up the claims to your authorisation flow and allow / deny access as appropriate.

You can also set up your own rules if you want the data to be available under different claim names. There are also several other SAML attributes that the standard rules will translate for you, but most will rarely have data.

Is there more data I can get?

Apart from those three above, there are two other common attributes. The main one you can reasonably expect from sites is a role attribute which can identify things such as member, staff, student, alum, and a few other education based items. It will usually say member and be in a claim called derivedEduPersonAffiliation. E.g. If your site is aimed at the education market, and should be presented differently to staff and student, your customers will be able to say that under role so you can make the determination.

If you need to do finer grained authorisation such as identifying a department you can use one called eduPersonEntitlement which can have any value you pre-arrange with sites.

Any of these could be multi-valued and would be passed to your OIDC instance as an unordered array - e.g. { "claimName" : [ "value1", "value2"] }

What about things like names and email addresses?

Personally identifiable information like that isn't supplied as standard and data protection regulations make sites very cautious about releasing it. Some may be willing where they see a justifiable use, but you should not expect it to be present and must not make it a condition of access.