Shibboleth + PERMIS


The PERMIS Shibboleth Apache Authorisation Module (SAAM) is an Apache module that uses PERMIS to control access to websites that use either Apache or Shibboleth to provide user authentication.

Why use PERMIS with Shibboleth?

When used in conjunction with Shibboleth, PERMIS extends the authorisation system used in Shibboleth by introducing hierarchies of roles and conditional decision making. Whilst the Shibboleth single sign on system (SSO) consists of a Service Provider (SP) that trusts specific Identity Providers (IDPs), PERMIS allows complex attribute management delegation trees to be built using X.509 Attribute Certificates. PERMIS still supports the existing Shibboleth attribute syntax, which can be used instead of X.509 ACs, but it extends their meaning by allowing them to be treated as roles in a hierarchy.

Some technical information about Shibboleth + PERMIS

Structure of shibboleth-permis integration
Architecure of PERMIS+Shibboleth intergration (click on the picture to enlarge it)

LEGEND for Diagram
SHIRE = Shibboleth component responsible for obtaining the user's authentication handle
SHAR = Shibboleth component responsible for retrieving the user's attributes or X.509 ACs
PV= Privilege Validator. PERMIS component responsible for checking that the user's attribute assignments are valid and were carried out in according with the SP's policy
PDP = Policy Decision Point. PERMIS component responsible for making access control decisions based on the user's validated attributes and the SP's policy

According to the different trust models adopted by the Shibboleth SP and IDP sites, the PERMIS SAAM can work in three different modes with Shibboleth attributes or X.509 ACs

  1. PERMIS SAAM in push mode with X.509 ACs
  2. PERMIS SAAM in push mode with normal Shibboleth attributes
  3. PERMIS SAAM in pull mode with X.509 ACs

PERMIS SAAM in push mode with X.509 ACs

If the IDP site wishes to distribute attribute assignments to different managers, and to support dynamic delegation of authority between users, and the SP site is willing to trust different attribute authorities at the IDP site, then the IDP site should store digitally signed attribute certificates (X.509 ACs) in its LDAP repository. Alternatively, if either the SP and/or the IDP do not trust the IDP site's attribute repository to securely store unsigned attributes, then the IDP should assign ACs to users and store these ACs in its LDAP repository. In these cases, SAAM should work in push mode and accept X.509 ACs from Shibboleth.

In this mode of operation, one user attribute (the user's distinguished name) and all user ACs should be configured for release to the target by the IDP's AA server. The user's DN and the role ACs should be retrieved by Shibboleth and passed to the PERMIS PV/PDP for validation and making access control decisions for the user's requests. The PV uses the PERMIS policy to decide who is trusted to assign which attributes to whom.

The interactions between the SP and IDP are as follows.

  1. When a user contacts a Shibboleth-protected service provider (SP) with the browser, requesting access to a Shibboleth-PERMIS protected URL, the user is redirected by the SHIRE to the WAYF site.
  2. After the user selects his/her home (origin) site at the WAYF site, the browser is redirected to the origin site's authentication server and the user is authenticated there.
  3. After successful authentication, the browser is redirected back to the SHIRE along with a handle package.
  4. The SHAR at the SP gets the handle and sends the handle back to the AA of the origin site requesting the user's attributes.
  5. The AA retrieves the user's DN and the role ACs of the user from the origin LDAP directory, base-64 encodes the attribute certificates, and sends them back to the SHAR.
  6. The SHAR puts the attributes in the Apache HTTP headers. These attributes can be defined and configured in the SP's Shibboleth Attribute Acceptance Policy (AAP). This is the last step of the authentication phase.
Up to this point in time the interactions between the SP and IDP have been according to the standard Shibboleth model. It is from now on that PERMIS takes over.
  1. In the authorisation phase of the HTTP request handling process, mod_permis is invoked first by the SP's Apache server.
  2. Assuming the location is being protected by PERMIS, the user's DN and role ACs are acquired by mod_permis from the HTTP headers (otherwise mod_permis returns DECLINED to Apache).
  3. Mod_permis calls the PERMIS PV and PDP to make an authorisation decision, which is based on the user's ACs, the web page that the user is wanting to access, the HTTP method being invoked on that page, and the SP's policy.
  4. After the PERMIS PDP makes the granted/denied decision, the decision is returned back to mod_permis;
  5. Mod_permis returns the decision result to the Apache server, and the user is then either granted or denied access to the web page according to the decision result.
From the above interactions between Shibboleth and the PERMIS SAAM we can see that the only difference between normal Shibboleth and this integrated Shibboleth is that ACs are retrieved and passed by Shibboleth instead of plain text attributes. Since ACs are stored in the IDP's LDAP as digitally signed binary attributes and Shibboleth could not initially retrieve binary attributes, Shibboleth needed to be slightly modified to handle them. On the origin side one Java class for retrieving attributes from LDAP - JNDIDirectoryDataConnector.class - was modified by us and another new Java class - Base64ValueHandler.class - was developed by the Shibboleth developers. The latter encodes the ACs into Base64 plain text. Now the encoded ACs can be transferred as plain text attributes from the origin to the target site, where they are decoded into normal binary ACs before being passed to the PERMIS PV/PDP, for use in decision making.

If a user possesses multiple roles, then multiple ACs can be assigned to the user and stored in the LDAP directory at the origin site. Shibboleth will retrieve all the role ACs at the origin site, encode them and pass then to the SP. In this way multiple ACs can be handled and utilised in access control decision making at the SP site.

PERMIS SAAM in push mode with normal Shibboleth attributes

If the SP trusts the origin's attribute repository and the origin to act as a single AA, then the origin will store plain attributes in its repository, and pass them in SAML messages to the target. This is the standard Shibboleth mode of operation. In this mode, the interactions between Shibboleth and the PERMIS SAAM are nearly the same as in push mode with X.509 ACs except that it is the user's attributes, not the user's DN and role ACs, that are passed by Shibboleth and used by the PERMIS PV/PDP to make decisions. In this case SAAM works in push mode, by pushing the attributes which were retrieved by Shibboleth, to the PERMIS PV/PDP.

The Shibboleth IDP can be configured to append a scope domain to each released attribute. Scope domains are used to distinguish between different attribute issuers at the origin site, for example some attributes could have a scope domain of "salford.ac.uk", while others could have a scope domain of "computing.salford.ac.uk" (note that the same attribute cannot have multiple scope domains, which effectively precludes dynamic delegation of authority in Standard Shibboleth). When the PERMIS PV is being passed "scoped" attributes instead of digitally signed ACs, the scope domains take the place of the AC signers. In order to validate "scoped" attributes, the PERMIS policy should specify the scope domains as trusted issuers in place of AC issuer DNs. We have reserved a special URL "shib:<scope domain name>" for this. In the above example there would be two corresponding SoAs identified in the policy by the special URLs: "shib:salford.ac.uk", and "shib:computing.salford.ac.uk" . If scope domains are not being used by an origin site, then SAAM inserts the name of the origin site as the scope domain for all the attributes. The scoped attributes can now be validated against the policy by the PERMIS PV in the same way as X.509 AC issuers, except that cryptographic validation cannot be performed. Thus there is no proof who actually issued the attributes as "scoped" attributes don't have digital signatures.

The other difference from the previous scenario is that the user's LDAP DN is not provided (since they have a random handle dynamically generated by the IDP). Therefore the PERMIS Subject Domain sub-policy should include the null DN (meaning that any DN is allowed) so that all handles are acceptable.

PERMIS SAAM in X.509 AC pull mode

If the SP trusts different attribute authorities based at the origin site and elsewhere, and wishes to authorise users based on these, then the origin site may not be able to push all these attributes to the SP. In this case the PERMIS SAAM can be configured to work in pull mode. It will fetch all the ACs itself from multiple IDP sites. An example might be: a graduate is issued with a degree certificate by a university, a doctor is issued with a "clinician" certificate by the General Medical Council, and an engineer is issued with a "certified MS engineer" by a Microsoft accredited agency. In this case various distributed LDAP repositories may sit in various places other than the original IDP site, and these should be made accessible to the PERMIS PV. The PERMIS PV can then operate in pull mode and fetch all the needed ACs from the various LDAP repositories. In this working mode, only one attribute of the user - the user's DN, needs to be configured and stored in the original IDP's LDAP repository. The user's DN denotes the holder identity of the ACs in the various LDAP repositories and this DN will be retrieved and passed by Shibboleth to the PERMIS PV, so that the PV can know which ACs to retrieve from the various LDAP repositories. Once the ACs have been retrieved by the PERMIS PV, the PV will use its policy to determine which ACs are trusted, and the PDP will use the policy to determine if the user has the necessary attributes to access the resource.

The interactions between the SP and the multiple IDPs are as follows.

  1. A user contacts a Shibboleth-protected resource site with the browser, is redirected by the SHIRE to the WAYF site, is authenticated at the original IDP site; then the browser is redirected back to the SP site along with a handle package. The SHAR at the SP site gets the handle and sends the handle back to the AA of the original IDP site with an attributes query. (the same as the initial steps in PERMIS SAAM in push mode with X.509 ACs )
  2. The AA retrieves the user's DN from the origin LDAP repository and sends this back to the SHAR.
  3. The SHAR passes the user's DN to the Apache HTTP header.
Up to this point in time the interactions between the SP and original IDP have been according to the standard Shibboleth model. It is from now on that PERMIS takes over.
  1. In the authorisation phase of the HTTP request handling process, mod_permis is first invoked by the Apache server, and the user's DN is acquired by mod_permis through the HTTP header.
  2. Mod_permis calls the PV and passes the user's DN to the PV. The PV then retrieves the user's ACs from the various LDAP repositories of multiple IDPs, and validates them against the policy. Finally the PDP makes an authorisation decision based on the user's validated attributes, the requested web page, the HTTP method being invoked on that page, and the SP's policy.
  3. After the PDP makes the decision, the decision is returned back to mod_permis.
  4. Mod_permis returns the decision result to the Apache server, then the user is either granted or denied access to the web page according to the decision result.