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.
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 https://doi.org/10.5281/zenodo.6533400. 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 MUurn: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).
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 https://doi.org/10.5281/zenodo.2247446. 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 ProxyIdPres:<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 fromres:TestingCapabilitiesValue1urn:geant:cesnet.cz:res:books:act:read#perun.cesnet.cz- generated fromres: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.