-
Notifications
You must be signed in to change notification settings - Fork 10
rfc fine grained authorization
Version 0.4
With respect to the management of users and their tokens Stepup is effectively a multi-tenant system where the tenants (institutions) are isolated. This is reflected in the current role-based authorization system where operators (i.e. RAs) can only manage users that belong to their own institution.
In the context of this document the word "institution" has two related, but different, meaning, which can be confusing:
- Institution -- A organisation that uses Stepup. E.g. an educational institution or a medical research university. An institution typically has one SAML IdP that provides the first factor authentication of their user to Stepup. This IdP also issues the shacHomeOrganization (SHO) attribute. Most Dutch institutions use the same SHO value for all their users, but there are a few exceptions. An institution could have multiple IdPs, or none, and still have users that use Stepup.
- Institution -- In Stepup the concept of an Institution exists. Each institution is identified by one unique SHO. These institutions are currently completely isolated from each other, they cannot see each other's data or vet each other's users. Configuration of vetting locations, RAs, allowed token types etc. is all per institution.
So most of the time it is true that one Institution (the organisation) has one IdP that issues one SHO value and has one Institution configuration in Stepup. But not always. Being able to dealing with these cases is important for Stepup.
One of the ideas that we had since the conception of Stepup was that by having each institution implement the same vetting process, we could allow additional use-cases where institutions could cooperate or share administrative tasks, especially vetting. To support such scenarios, we need to break the barrier between institutions, in a controlled fashion, and allow more fine-grained control over what RA may perform what actions for what users.
In this document we discuss the use-cases and ways to implement them.
As an operator of the Stepup service we want to allow RAs to vet users for multiple institutions. We want to support scenario's where more flexibility is required of who can vet what users, and by extension who can revoke tokens, see user information and can manage RAs. In the RFC we discuss how to extend Stepup's authorization model, and by extension its UI, to allow for such scenario's. Below are the use-cases that we want to target.
For institutions with few (say 10-20) users that are using Stepup, for which setting up and maintaining a local vetting structure is relatively expensive, we want to allow a third party to do the vetting whereby the RA's are associated with this third party. It is expected that several institutions will use the same third party.
Allow users from institutions that cannot easily visit the vetting location at the institution, e.g. because they work remotely or abroad, to use the RA services of another institution that is closer to their location. By pooling the RAs from different geographical locations, the access for users to RA services is improved.
Two or more Institutions that are working (closely) together and that want to share their vetting infrastructure Note: the difference with the previous use case (B) is that in this use-case (C) each institution has fine grained control over who of the other institution may work for them.
Note that in use-case B an institution allows all RAs from the other institution(s), it has no control over who these are, this is decided by the RAAs for the other institution. In this usecase each institution manages all its RAA(s), i.e. it chooses which persons from the other institution are RA. These users are not required to be an RA at the other institution.
Allow users from a "guest" IdP (i.e. an IdP for users that do not have a relation with an institution that warrants adding them to the institutional IdP) to be vetted. The RA(A)s to do this will necessarily need to belong to another institution. The guest IdP itself does not have RAs or RAAs
An institution IdP that issues multiple SHOs, e.g. institution.org and some-related-part.institution.org. From the perspective of Stepup these would currently become multiple institutions, which each have and manage their own RA(A)s. This is not what the institution would want, they would want their multiple SHOs to appear as one institution management wise.
An institution that manages Stepup for (a group of) sister and/or daughter institutions. This use-case appears similar to use-case A. The differences lie in the relation that the managing institution has with the institutions being manged. RA(s)s could come from the sister/daughter institutions, but would be managed from the main institution.
The above use-cases are described from a functional standpoint, when deriving the requirements from these use-cases we notice that there are significant overlaps between the use-cases, which is good. Below we note the differences and similarities between the use-cases:
- Use-case C stands out because each institution continues to manage its RAA and RA roles on a per user basis, even if those users are associated with another institution. We see the same requirement in use-cases F, where the managing institution assigns users from the sister/daughter institutions RA(A) roles for the managing institution, and E, where institution.org could have RA(A)s from some-related-part.institution.org
- A common requirement is to make the RAs from one institution to be RAs in other institutions. The other intuitions do no select the individual RAs, but instead select the institutions that donates the RAs. When an institution donates its RAs, it donates them all. It is the donating institution that continues to manage the RAs. We see this requirement in all use-cases, except use-case C.
- A similar requirement to the previous one of donating RAs, is the requirement to donate RAAs to another institution. We can see this requirement in use-cases A, D, E and F.
To support these use-cases we need to allow users to become RAs and RAAs for not just their own institution, but also for other institutions. To be able to manage this effectively we suggest distinguishing between the three ways to assign users the rights to become an RA or an RAA for other institutions we identified above:
- An RAA of an institution can assign (and revoke) the RA(A) role to a user from another institution. Doing this modifies the user's RA(A) status for the institution that the RAA manages only. It does not affect the role of the user at his home institution.
- Make all RAs of one institution RA for another institution
- Make all RAAs of one institution RAA for another institution
These scenario's also affect the presentation of information in the user interface. Where relevant the institution of a user will need to be added to the UI. Because it has become more variable what user has what role in what institution, it makes sense to add information screens for RAs and RAAs that show this.
Current Implementation
Stepup has an authorization model that determines which identities (i.e. user accounts) may perform what actions. The model in Stepup consists of roles the are granted to users. An identity has one of the roles below. Ordered from least to most rights these roles are:
- User - the default role
- RA - RA administrator
- RAA - RA administrator
- SRAA - Super RA administrator
Each higher role contains all the rights of the lesser roles. An identity is always associated with exactly one institution.
A User can only access the Stepup-SelfService where the User can:
- View their current token information
- Request a token
- Delete their own token
RA and RAA rights (i.e. vet, view audit trail) apply only to (token of) identities of the same institution as the RA(A). RAs can access Stepup-RA.
In addition to a User, an RA can:
- Show and search the token information of all identities in their institution
- Show the audit trail of all identities in their institution
- Revoke tokens of all identities in their institution
- Vet tokens of all identities in their institution
Additionally, an RAA can:
- Grant the RA or RAA rights to identities in their own institution
- Manage institution vetting locations
- Export token overviews
A SRAA can exercise all these rights, for any institution, not just for the institution to which they belong.
To get an idea of how often RAs use the token over view page and audit log, we look at the HTTP access logs and the event log to see how these relate to the main operation performed by an RA -- vetting.
The different actions an RA can take in the RA application have recognisable URLs, by processing the access logs we can get a rough idea of much the different functionalities are used by RAs:
Based on SURFsecureID HTTP statistics over may-july 2018
| Total HTTP requests to the Stepup-RA, minus monitoring | 100% |
| verify identity | 20.6% |
| token overview | 4.8% |
| audit log | 0.5% |
| ra management | 0.26% |
| revoke | 0.15% |
By looking at the event log, we can see exactly how many actual revocations there have been. SURFsecureID production eventlog (September 2015 -- august 2018)
| The total number of vetted second factors | 100% |
| SecondFactorVettedEvent | 100% |
| VettedSecondFactorRevokedEvent | 14.6% (=revoked by user) |
| CompliedWithVerifiedSecondFactorRevocationEvent | 1.7% (=revoked by RA) |
Currently users of the RA interface (i.e. users with the RA or RAA roles) can only perform actions that affect users that belong to the same institution as they do. We want to grant RA(A) rights to perform operation that affect users of other intuitions.
When the relation between the RA and the organisation becomes more distant and the role of the RA in process more limited, as is the case in some of the use-cases, more granular rights may be desirable to limit the access to the personal information that is stored in Stepup and to limit the operations available to an RA. This is in line with the principle of least privilege. The privacy and security gains of having more fine-grained access control need to be balanced with the complexity of managing these rights, and of implementing such a system.
Because we expect to gradually introduce the more file-grained system we can keep the current roles, but when making implementation choices should keep in mind that we might want to add more roles and/or authorisations later. What rights could be granted to a user of the RA interface:
- The right to vet the token of a user
- The right to revoke a token of a user
- Manage RA rights (i.e. the current RAA role)
- Manage RA locations
- Access to token overview and/or audit log
- Export of token overview
How to present the information to RAs now that users can be from other institutions than their own?
The institutions switcher that is currently used by the SRAA role serves a different purpose, it allows the SRAA to view the UI as an RAA of the selected institution. For an RA(A) having to select the institution of a user before being able to find that user in the token overview is not that intuitive. It makes sense to keep the current switcher for the SRAA for this purpose.
In the screens that are used by the RAA to manage RA roles:
- Include the SHO of the RA
- Include all (candidate RAs), including RAs from other institutions when applicable
When a user is an RAA for multiple institution, the user must specify for which institution he / she is managing RAs. A selector needs to be added to the page. This can be like the SRAA institution switcher, or can be part of the page itself. To prevent confusion as to what it affects, I suggest only showing the selector when it is relevant.
Users from multiple institutions should be visible and searchable in the token overview page
- Show the SHO of the user
- Add the SHO as a filter option
- Show the SHO of the user
- Show the SHO of the actor (e.g. the RA (A) that vetted the user)
Emails currently show a list of vetting locations. When a user has access to the vetting locations of multiple institutions this can become a long list. Too long a list to show in an email. A solution would be to add a message stating that additional vetting locations are available and include a link to a page in the self service portal that shows all vetting locations for that user.
Because we plan to start small, we can postpone adding functionality for this, and use the locations to provide vetting information.
Because this situation is more likely to occur add feedback when a user visits an RA with a valid OTP, but for which the RA lacks the rights to vet. Message "you do not have the right to vet users from institution X".
Add a page for the RAA in Stepup-RA that shows the configuration of the institution. As the amount of institution specific configuration has grown, this would already be useful. I.e. show the configuration of:
- Use RA locations
- Show RAA contact information
- Verify email
- Allowed second factors
- Number of tokens per identity
And the new configuration options for this institution:
- From which other institution(s) can users be assigned the RA(A) role for this institution?
- From which other institution(s) the RAs are also an RA for this institution?
- From which other institution(s) the RAAs are also an RAA for this institution?
It might also be interesting to show the inverse:
- In which other institution(s) can users from this institution be assigned the RA(A) role for those other institutions?
- In which other institution(s) are the RAs from this institution an RA?
- In which other institution(s) are the RAAs from this institution an RAA?
When individual users could be made RA(A) for more than one institution there could be differences between the rights of RAs from the same institution. A "profile page" where a user can see his peronal roles in Stepup-RA could be helpful. I.e:
- In what institution(s) am I an RA?
- In what institution(s) am I an RAA?
When creating such a page add the info we already have about a user:
- Your NameID in Stepup (e.g.
urn:collab:...) - Your Common Name
- Your email
- Your preferred language
How to configure all this?
Considerations:
- An institution is identified by the SHO
- Allow institutions to manage their own RA(A)s. We discussed use-case C (two institutions that work closely together) with two institutions to which this scenario applies. They don't want to automatically allow all RA's from the other institution, but want to pick which ones. The rationale given was that not all RAs (service desk locations) are involved in the cooperation.
- For the other use-cases like B (pooling RA resources from multiple institutions) fine grained control over what RAs may vet a user is not required or infeasible as that would require each institution to add, and keep up to date a list of RAs that they allow to vet their users, without having a direct relation with these RAs.
The existing institution configuration is extended.
In the institution configuration of the middleware, for each institution, add configuration options with:
- UseRA -- A list of SHOs of the institutions from which the RAs are also RAs in the institution.
- UseRAA -- A list of SHOs of the institutions from which the RAAs are also RAAs in the institution.
- SelectRAA -- A list of SHOs of the institutions from which the users may become RA(A)s in the institution.
The difference between the first two lists and the third list is that in the first two lists each RA(A) from the listed institutions is also an RA(A) in in the target institution. In the second case all users from the listed institutions may become RA(A)s in the target institution.
During discussions we noticed that the Is vs Become naming can be confusing. Better naming is welcome. I tried to choose names that are short.
The UseRA and UseRAA lists of an institution could become long. If a group of ten institutions wants to share RAs (scenario B), each of them has to list itself and the nine others. The total number of SHOs grows exponentially O(2^n) with the number of institutions in the group. For smaller groups, this is not a problem. For larger groups this will lead to a verbose and sizable configuration. This could be solved by introducing the concept of a group. A simplified version is to treat the institution as group. I.e. add not only the RAs of an institution on the UseRA, but also those that are an RA because that institution has an UseRA, ad infinitum.
We expect the list of SelectRAA SHOs to short (typically 1-3, and < 10), it will be limited to institutions that are closely related (scenario C). Because RAAs have to be managed per institution, the associated management overhead grows as the number of institutions grows.
With these three options, quite complex configurations can be created, especially because the UseRA and UseRAA options inherit the RA(A)s from the listed institutions, which themselves could also have inherited RA(A) using UseRA or UseRAA, or could have added RA(A) from other institution using SelectRAA.
The default for each of the three options lists only the institution itself.
An SRAA still has all rights in all institutions. These users or their institution does not need to be inherited, or shown in the RA(A) information / profile screens.
This connect op lists can be extended to make the assignment of rights more fine-grained. E.g. by adding:
- A list of SHO's whose RAs may vet their users. This only grants the rights to vet the user.
- A list of SHO's whose RA(A) may revoke their users
- A list of SHO from which user may become only RA
- And more fine-grained: A lists of SHO's for which token information is shown, audit log is shown or for which tokens may be exported.
We propose not adding the more fine-grained options until it is clear that these are needed in practice.
Note:
- An RAA could be an RAA for multiple institutions.
Example configurations for the different scenarios.
The table below gives a quick overview of which non default options are used by what use-cases. When not the default, "External" means that one or more other institutions are configured and "Empty" means that no institutions are listed.
The default for each option the SHO of the institution itself. We need to decide what it means to have an empty list for UseRA and UseRAA. My suggestion is that an empy list means that there are no RA(A) for that institution, even when users have the RA(A) role for the institution.
Because a use-case consists of the configuration of multiple institutions, both "Empty" and "External" can occur.
| Use-case | UseRA | UseRAA | SelectRAA |
|---|---|---|---|
| A | External | External | Empty |
| B | External | ||
| C | External | ||
| D | Empty/External | Empty/External | Empty/External |
| E | External | External | Empty/External |
| F | External | External | Empty/External |
Note: The third party vetting service can become an institution in Stepup, I don't think we need to introduce a new concept for this.
Institutions: I and J Vetting service: V
I: {UseRA: [V], UseRAA: [], SelectRAA: [] }
J: {UseRA: [V], UseRAA: [], SelectRAA: [] }
V: {UseRA: [V], UseRAA: [V], SelectRAA: [V]}
Note that institutions I and J do not have RAAs. When desirable (e.g. for configuring vetting locations), a corresponding "UseRAA: [V]" option can be added. Otherwise only an SRAA could perform RAA tasks for these institutions.
Institutions: I and J Vetting service: V Vetting pool: P
In solution 1 the RAs that V employs for vetting I and J , are also RAs for V. If V does not want that, but wants a separate vetting pool P of RAs for I and J.
I: {UseRA: [P], UseRAA: [], SelectRAA: [] }
J: {UseRA: [P], UseRAA: [], SelectRAA: [] }
P: {UseRA: [], UseRAA: [V], SelectRAA: [V]}
V: {UseRA: [V], UseRAA: [V], SelectRAA: [V]}
Now V can have it's own RAs. The RA's for vetting I and J are assigned the RA role in P by the RAAs from V. RAs from P cannot vet or revoke users in either P or V.
Note that recursive evaluation of UseRA or UseRAA is not required here, because users from V are added as RA to P directly and managed from there.
Institutions: I , J and K
I: {UseRA: [I,J,K] }
J: {UseRA: [I,J,K] }
K: {UseRA: [I,J,K] }
Note that we do not need to add "UseRAA: [...]" or "SelectRAA: [...]" because the defaults fine. (for I: "UseRAA: [I], SelectRAA: [I]", and for J: "UseRAA: [J], SelectRAA: [J]", etc)
For a large number of institutions, we can introduce a virtual institution G , this institution does not have any users, it is only used to create a reusable group of RAs:
An institution acting as a group: G
G: {UseRA: [I,J,K], UseRAA: [], SelectRAA: []}
Institutions: I , J and K
I: {UseRA: [G]}
J: {UseRA: [G]}
K: {UseRA: [G]}
Note that this solution requires that the evaluation of the UseRA configuration is recursive.
The RAs for I are:
- Any RAs from I that were assigned the RA role by an RAA of (and here also from) institution I.
- All the RAs of G, which are none
- All the RAs of I , J and K.
- And if I , J and K have an UseRA, the RAs of any institutions listed there. Note that to prevent infinite recursion the evaluation of UseRA for I , must be stopped, because we already evaluated UseRA for that institution.
Institution A and B that want to partly share RA(A)s.
A: {SelectRAA: [A, B]}
B: {SelectRAA: [A, B]}
Each institution can make the other's users RA(A). There is no sharing of RA(A)s.
Vetting service: V Guest IdP: G
Any RA or RAA for V may also manage the Guest IdP.
G: {UseRA: [V], UseRAA: [V], SelectRAA: []}
V: {}
For the vetting service V the defaults for UseRA, UseRAA and SelectRAA could be fine. It could also have another more complex configuration, in which case any RA(A)s for V will also be RA(A)s for G.
Explicitly manage which users from V may work for V
G: {UseRA: [], UseRAA: [], SelectRAA: [V]}
V: {}
An institution I , with additional SHOs Ia , Ib and Ic.
I: {SelectRAA: [I,Ia,Ib,Ic]}
Ia: {UseRA: [I], UseRAA: [I], SelectRAA: []}
Ib: {UseRA: [I], UseRAA: [I], SelectRAA: []}
Ic: {UseRA: [I], UseRAA: [I], SelectRAA: []}
An institution I , which manages Stepup for institutions Ia , Ib and Ic.
I: {SelectRAA: [I,Ia,Ib,Ic]}
Ia: {UseRA: [I], UseRAA: [I], SelectRAA: []}
Ib: {UseRA: [I], UseRAA: [I], SelectRAA: []}
Ic: {UseRA: [I], UseRAA: [I], SelectRAA: []}
Note that this is exactly the same configuration as for use-case E
- Read only access to the RA interface. E.g. to allow a role that does reporting or monitoring of policy and compliance.
- Automated vetting service. In a different project we are looking at how RA functionality can be automated.
Version 0.4:
- Update title to include "for RAs"
- Rename RA configuration options: BecomeRAA => SelectRAA, IsRA => UseRA and IsRAA => UseRAA.