Entitlements

ProxyIdP can release information about privileges that the user should be granted in the target application. This information is released in the form of entitlements, which are string values representing individual access rights, user roles, group membership etc.

The values are released differently depending on the authentication protocol used:

in SAML, the values are listed in the eduPersonEntitlement attribute
in OIDC, the values are listed in the eduperson_entitlement claim in the userinfo endpoint, and scope eduperson_entitlement is required to gain access to this information

ProxyIdP releases several categories of entitlement values.

Forwarded entitlements

If the user has multiple linked identities, and the home Identity Provider sends some entitlements about the user, ProxyIdP will forward these entitlements, as they are, to the service.

The specific format of these entitlements depends on their issuer.

For security reasons, entitlements from the home Identity Provider which have the same issuer as the current Perun IdM instance are discarded.

Group entitlements

ProxyIdP releases entitlements also based on group membership and groups assigned to the service in Perun IDM. For convenience, ProxyIdP will release an entitlement value for each group that the user is a member of if that group is assigned to a resource on the facility that represents this service.

The procedure for generating these entitlements is described in the official specification Guidelines for expressing group membership and role information (AARC-G069). The format of each value is:

<NAMESPACE>:group:<GROUP>[:<SUBGROUP>*][#<AUTHORITY>]

where

<NAMESPACE> is a prefix which represents the instance of ProxyIdP
<GROUP> is the short name of the virtual organization of the group
[:<SUBGROUP>*] contains the full group name, if the user is a member of a group (URL encoded)
[#<AUTHORITY>] is a suffix representing the instance of Perun IDM

Examples:

urn:geant:muni.cz:group:MU#idm.ics.muni.cz - a member of a VO called MU
urn:geant:cesnet.cz:group:einfra:group1#perun.cesnet.cz - member of a group called group1 in a VO called einfra

How to configure group entitlements

The downside of this approach is that the value of the entitlement changes when the group is renamed or moved in the hierarchy. This poses a risk of breaking access when using multipurpose groups. For a more stable solution, see resource capabilities below.

Group entitlements are configured in the Perun IDM. Groups need to be assigned to a resource on the corresponding facility, and ProxyIdP will start releasing related group entitlements automatically (when requested or required by the service).

For example, in this setup:

User is a member of groups “VO1:Group C” and “VO2:Group D” assigned through resources to the current facility.

the group entitlements released by the ProxyIdP for the current user and facility are:

<NAMESPACE>:group:VO1:Group%20C#<AUTHORITY>
<NAMESPACE>:group:VO2:Group%20D#<AUTHORITY>

If you want to disable group entitlements (because you do not use them), you can set the “Disable group entitlements” attribute on resource where you do not want group entitlements.

This feature is currently in beta and is not available on all Perun instances.

Resource capabilities

To prevent access control from breaking when groups are renamed or moved in the group hierarchy, we highly recommend using entitlements in the form of resource capabilities. This form of entitlement effectively represents an M:N mapping of groups to entitlement values; multiple groups may be mapped to the same capability, and also one group may grant users multiple capabilities.

The procedure for generating these entitlements is described in the official specification Specification for expressing resource capabilities (AARC-G027) . The format of each value is:

<NAMESPACE>:res:<RESOURCE>[:<CHILD-RESOURCE>]...[:act:<ACTION>[,<ACTION>]...]#<AUTHORITY>

where

<NAMESPACE> is a prefix which represents the instance of ProxyIdP
res:<RESOURCE>[:<CHILD-RESOURCE>]...[:act:<ACTION>[,<ACTION>]...] is the resource capability value set in Perun IDM
[#<AUTHORITY>] is a suffix that represents the instance of Perun IDM

Examples:

urn:geant:cesnet.cz:res:TestingCapabilitiesValue1#perun.cesnet.cz - generated from res:TestingCapabilitiesValue1
urn:geant:cesnet.cz:res:books:act:read#perun.cesnet.cz - generated from res:books:act:read

How to configure resource capabilities

Resource capabilities are configured in the Perun IDM. Groups need to be assigned to a resource on the corresponding facility, and resource attribute Resource capabilities needs to be set to a value in the format res:<RESOURCE>[:<CHILD-RESOURCE>]...[:act:<ACTION>[,<ACTION>]...]

The specific value can be chosen depending on the service’s requirements. Each capability may represent:

user’s workplace (e.g. res:workplace:12345)
a part of the system which the user is allowed access to (e.g. res:agenda1:act:read)
a role which the user should be granted (e.g. res:admin)

Resource capabilities may be “nested” - for example by combining capabilities res:user, res:user:read and res:user:write, the access control inside the application may be greatly simplified.

Each resource may grant multiple capabilities, multiple resources may grant the same resource capability.

For convenience, if all resources should grant the same capability, instead of adding it to all individual resources, you may set facility attribute Facility capabilities to this value. Users in all groups on all resources will be granted this capability.

For example, in this setup:

User is a member of groups “VO1:Group C” and “VO2:Group D” assigned through resources “Resource 2” and “Resource 3”, with resource capabilities “res:admin” and “res:events:write”, to the current facility.

the resource capabilities released by the ProxyIdP for the current user and facility are:

<NAMESPACE>:res:admin#<AUTHORITY>
<NAMESPACE>:res:events:write#<AUTHORITY>

Group entitlements are also released in this case, see the other example (above).