Updates readme with more details on configuration

[uw-rvitorino]

As directly requested in #36 and also suggested in #25, this PR aims at improving the README with:

• updated configurations for the library versions > 1.1.1
• instructions on setting up a Django application within Keycloak

Beyond the accuracy of the instructions, revisions to the English grammar and the quality of the screenshots are more then welcome.

[moritz89]

The decode token option is optional, and false by default, so it would make sense to reflect this in the readme. The following would be useful.

DECODE_TOKEN enables extracting a user's profile data from the JWT token instead of fetching this data from Keycloak via an API call. This has the effect of reducing the latency, but also requires the profile to be included in the JWT token in the first place. This can be configured in Keycloak's client scopes tab.

[moritz89]

Regarding the Graphene middleware, I'm not sure if we should promote its use. The middleware is basically only used for user authentication in the same way that the normal middleware is, but it is called for each node of the GraphQL query. In effect, this reauthenticates the user multiple times, when once using the normal middleware is enough. Therefore, unless there is some use case that I am not aware of, I would deprecate it instead of recommending its use.

[moritz89]

Regarding the setup instructions, they look quite similar to my internal ones. I've adding them below as reference:

Setup

1. Log into Keycloak and go to the "Administration Console"
2. Create a new realm (sidebar --> Hover over master --> Add realm) with the name my-realm
3. Set up the core service client
4. Set up the web app client
5. Set up the superuser

The imports folder contains all the settings to use keycloak in a dev environment. It is used by the start script of the core service.

Set Up Core Service Client

1. In the my-realm realm, go to clients and create a new one
2. Use core-service as the client ID and http://localhost:8000 as the Root URL and save the client
3. Change the Access Type to confidential and save the changes
4. Enable Service Accounts Enabled and save the changes
5. Go to the Service Account Roles tab
6. In the Client Roles dropdown select realm-management
7. In Available Roles select manage-users and press Add selected
8. Additionally, in Available Roles select view-users and press Add selected
9. This should result in 4 Effective Roles: manage-users, query-groups, query-users and view-users

In the core service Keycloak settings (core/core/settings.py --> KEYCLOAK_CONFIG) use core-service as the client ID and the secret from the Credentials tab.

Set Up Web App Client

1. In the my-realm realm, go to clients and create a new one
2. Use web-app as the client ID and http://localhost:4200 as the Root URL and save the client

Set Up the Superuser

1. In the my-realm realm, create a new realm role (sidebar --> Roles --> Add Role)
2. Name the role admin and press Save
3. Create a new client role for the core-service client (sidebar --> Clients --> core-service --> Roles tab --> Add Role)
4. Name the role admin and press Save
5. In the my-realm realm, go to the user management page
6. Select Add user and create a user with the username admin
7. In the admin editor, go to the Role Mappings tab
8. For the Realm Roles --> Available Roles select admin and the press Add selected
9. For the Client Roles --> core-service select admin from the Available Roles and press Add selected
10. In the admin editor, go to the Credentials tab
11. Enter the Django superuser password in the Password and Password Confirmation fields, unselect Temporary and save the password.

[diogosilva30]

@uw-rvitorino I like the docs improvement. A small, but important, note: These steps (and screenshots) are for keycloak v10. With the latest keycloak v19, they are a bit outdated. Maybe we should target more recent versions?

[uw-rvitorino]

Absolutely, I'm a recycling kind of guy 😀, can you, Simão or Moritz provide such screenshots? Feel free to contribute directly to the branch

[moritz89]

I'm also still on the legacy Keycloak branch, so my screenshots won't be any newer :sweat_smile:

[moritz89]

Hey @uw-rvitorino, how about we just add the 3 small changes I posted above to have the updates visible and do another round of doc improvements in a different MR?

[github-actions[bot]]

This PR is stale because it has been open 60 days with no activity. Remove stale label or comment or this will be closed in 10 days.

[github-actions[bot]]

This PR was closed because it has been stalled for 10 days with no activity.