> For the complete documentation index, see [llms.txt](https://docs.greenstand.org/auth-system/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.greenstand.org/auth-system/how-to-set-up-the-keycloak-for-greenstand.md).

# How to set up the Keycloak for Greenstand

## Set up the resources

Create resources items on Keycloak to represent the features on the whole Greenstand platform.

#### 1. Install Keycloak

#### 2. Create realm

1. Login
2. Create a realm with the name: greenstand

#### 3. Create front end client

For example: the web map client that can login as a dashboard to do some map-dedicated management.

Create a client with name `webmap`

Settings for this client: 

* Access type: public
* Root URL: the url of the web-map-clients dashboard, e.g. <http://localhost:3000/admin>

#### 4. Create User

#### 5. Create Role

Such as: `web-map-viewer` , `web-map-operator`

#### 6. Create client for resource

Create a client with name: `api-services`

With settings:

* Access type: credential
* Authorization enabled: true

Create resources and scope on this client.

* Create resources, e.g. `web-map-theme`
* Create authorization scope, e.g. `view` `edit`

Create permission items, for example, the permission to view web-map-theme

Create policy to build the permission rule, for example, the policy that allows role `web-map-viewer` to be able to view web-map-theme.

#### 7. Test the permission:&#x20;

There is a tool to test if everthing is fine: api-services -> authorization -> evaluate

#### 8. Integrate with real client

## Set up group

The group represents the organzaitons on Greenstand, like the Freetown, TheHaitiTreeProject.

Keycloak needs to be aware of the organization for a user, so it can decide if a user has the permission to operate resources belonging to some organization.

1. Open the `group` menu and create group.
2. Assign the group an attribute: {'organization\_id': xxx} that should be the same as the number in the DB for that organization.
3. To fetch user's organizations id on the client-side:

   1. Assign the group just created to the user.
   2. Open the client, say, `webmap`
   3. Open `mapper` and click `create`
   4. Create the mapper with settings as below:
      * map type: user attribute
      * user attribute: organization\_id
      * Token claim name: organization\_id
   5. Done

   Now the user's organization\_id attribute will be shown in the user's information sent to the client.

On Keycloak, there are export and import functions. Here is an exported realm for Greenstand:

{% file src="/files/VUPH0fMs4BjQCYIJ25Zc" %}