KeyCloak : Users, Groups, Roles for the portal

[kohsah]

We have authentication, we need an authorization implementation. The process is like this - the user registers on keycloak and gets an identity to authenticate on the portal. The authenticated user can create a profile on the portal.

Users are members of organizations - organizations are pre-registered / pre-created on the portal. The default organization is "public" for authenticated users i.e. a member of the general public. Otherwise during profile creation they can choose to indicate membership of an organization.

An Organization has the following info:

• name
• url
• logo
• country
• creation Date

An organization is equivalent to a group of users.

Users in a "non-public" organization like the above also get roles within the organization. Roles are:

• admin - can administer the organization (add / remove / block users ; access all content)
• content editor (can add and edit documents)
• content submitter (can only add documents)
• reader (can view documents)

This needs to be developed as an installable module, so it can be used in application contexts other than the portal. It will need a database back-end to store the user profile, group and role information (this can be something like couchdb or mongodb)

[kohsah]

So there are Realms, Groups and Roles in KeyCloak.

Realms are like domains and have their own user directory independent of other realms.

There is a "Master" realm whose users are super admins of all other realms.

So in our case, we could use "Realms" for each partner country - so effectively each partner country can have their own user directory with Groups and Roles used to group people and assign them specific permissions.

We need to explore whether this is a good fit with Gawati - and what work needs to be done to have a custom UI (.e.g. a user logging in will need to chose a realm (partner) they are logging into ) , and to have custom metadata.

[kohsah]

Roughly this is what would mean in the user interface:

user indicates a realm while logging in and is authenticated against that.

General public users use a realm called "Public" others use specific realms for an organization.

Similarly while registering, users need to be asked which realm they are registering in. To finally activate the user an admin of the realm will need to do it.

[kohsah]

Here is an illustration of the hierarchy in authentication:

We fix roles, because functionality is implemented against roles. So if we allow freedom to create roles - we don't know what an unknown role implies in terms of functionality. For this reason Country databases will have a set of roles mapped to specific functional aspects in the software e.g. editorial roles relevant to gawati could be : "editor" , "reader", "admin", "submiter", "approver" etc. For documents these are mapped to "modes" which are implemented in software - "view", "edit", "delete", "list" - and roles are mapped to modes for a document "state". Document "state" is set by a workflow system .

Different policies are supported:

http://www.keycloak.org/docs/3.3/authorization_services/topics/policy/overview.html

Authorization for accessing resources:

http://www.keycloak.org/docs/3.3/authorization_services/topics/resource/overview.html

We need to determine if local admins within realms are supported.

[ccsmart]

I'm concerned over the idea of providing authorization for 3rd parties. Also would like to suggest a different glossary if thats the right term too...

The Master Database i would not assign to any entity. Master Database is essentially an "administrative account" kind of thing. "Public" as in initial post i would suggest to retire too.

A realm is the equivalent of an entity. A country as such is not. Kenya Law is an entity and if choosing Gawati, would be represented by a realm. Each realm should be equivalent to the primary DNSdomain representing that entitiy. What is "public" above, should be "gawati.org".

Any entity running Gawati with the intention to do editing over pure collection, with any need for permissioning actually, should have their own keycloak instance with their own realm. All authorization of that entity should be exlcusively defined in a realm of that instance.

Cross realm access should be defined by authorisation of a remote user in a local realm/instance.

The feature for providing for external realms can be implemented and used, should nto be much different from single realm cases if not identical, but should be a demo / development / low risk feature only for those cases that are not sensitive as it puts too much responsibility on the provider. A production instance of a government related entitiy would be out of that picture by definition imo.

[kohsah]

@ccsmart I have used databases synonmously with Realms... thats what they are.

Our intention is to run every partner within a realm; its not a domain in the context of KeyCloak, just equivalent - in terms of isolating a set of users groups and roles in terms of managing and authenticating users only within that realm ; you can have multiple realms running on a single auth.system.com running keycloak (it just vdirs it internally auth.system.com// )

Master is the default realm users of which can administer other realms (that would be Us) .

Having multiple partners within a realm makes it less flexible and requires a lot more configuration and management -- and the isolation capabilities of localized management with realms is not easy (not sure if possible since it requires setting up multiple policies and role permissions) .

You would need a " public" realm otherwise where do you register public users on the internet ? No point having a parallel system for registering public users who are not part of any partner organization.

We don't prevent people from using their own keycloak that is upto them - since the software does not prevent it, but Partners who want to sync content need to be on our authentication instance otherwise there is no way to validate who they are and what they are authorized to do.

[ccsmart]

I think you are describing the same components, but with different words.

Fully agreed, every partner, entitity in my words, has its dedicated realm. I use the DNSdomain to name it. Kenyalaw would have a dedicated realm called "kenyalaw.org". That as you say isolates it from other entities/realms that may or may not be present on a given keycloak instance. Clearly, my statement is, in most cases an entity of any security relevance, should run their own keycloak instance for said security, ownership and responsibility reasons.

Master is owner of the instance, us in 1 case ( or 2 if you count dev etc). And should only countain IT administrative data for keycloak itself. Nothing that Gawati, or any other application uses.

Multiple partners, or entities, should never be in a single realm. And usually not on a single server.

"public" remains undefined. Needs not be defined, and should not be defined. "Public" from OUR perspective, is whats found in the realm "gawati.org". Or "gawatipublic.org" if a distinction for gawati project members was to be made. Or "africanlawlibrary.net" if you were to look at it from there. Those latter three may or may not be on a single instance based on our preference. But explicitly not "kenyalaw.org".

Identities are defined, even if they are not present in local keycloak. if a document owner is me@kenyalaw.org in a document on africanlawlibrary.net it's ownership is clear and maintained.

If it is for defining permissions for me@kenyalaw.org on africanlawlibrary.net, then that permissions will be granted to me@kenyalaw.org in the realm africanlawlibrary.net.

If it is for fetching supplementary data for me@kenyalaw.org, eg an avatar picture, then that keycloak instance (or a readonly, partial proxy thereof) must be accessible via internet on a known, DNS registered service.

If users of realm kenyalaw.org are supposed to have direct, interactive permissions (not backend sync) that requires them to log in, then again, kenyalaw.org keycloak instance must be accessible on a DNS registered service to allow that.

Potentially, this is easier to discuss by call.

[ccsmart]

I would like to add the suggestion that we go forward and run two live keycloak instances right away, one containing 2 realms, gawati.org and africanlawlibrary.net, one additional as an instantiation of "public" either on a new domain, akomantoso.com or any other we might designate for that purpose.

Then we reference identities from both in dev/test environment, exploring all the options.

[ccsmart]

To add to the backend sync case, valid identity of users in that case can be warranted by the sending server, as sending server is declared trusted and can be authenticating either by its own server identity in the receiving realm, or by a public key based challenge/response.

[kohsah]

Follow up, practical implementation related issues: Issue #44, Issue #45