How Trust & Security Works in Gawati
This document focuses on how trust and security works in Gawati, what are the components we use, how they interact with each other, and what are the specific configuration choices we have made in Gawati. We cover aspects governing both authentication and authorization in Gawati.
To install KeyCloak for Gawati use see the :doc:`../development/authentication` .
Users in KeyCloak are defined within authentication realms. Applications wanting to authenticate with a Realm, need to be registered and configured on the Realm, a registered Application in KeyCloak is called a
Client. Applications can define specific roles which can be assigned to users on the Realm. In the image below we have added a realm called
kiribati which will hold all the registered users.
Client applications wishing to connect need to register, by
Add Client, see image below, where we add a
root url is the URL of the application authenticating with the KeyCloak instance.
test-client can be edited. For use in Gawati we need to change some defaults. Most importantly, we need to change the default
Access Type from
confidential. We do this because, the
public method does not provide access to authentication tokens;
confidential also requires passing a
secret to KeyCloak when initiating any kind of request, and is more secure; finally, in
confidential mode, tokens can be introspected on the server side (this is possible when
Service Accounts Enabled is switched on).
Direct Access Grants. For application use you may also set
Direct Access Grants to off, but some admin tools may not work with the client. Set the rest of the URL parameters as per your application. When
Access Type is changed to
confidential, a new
credentials tab is added which has the
secret which has to be passed by clients making requests to KeyCloak.
We can create roles specific to the client, in the Roles tab. Roles for a client can also be given a realm wide scope if needed so other clients in the realm can use them.
installation tab allows you to export the client configuration and use it within your application to integrate with KeyCloak. This configuration will be used in both client applications, and also in server applications (where it will be used in
service accounts mode).
We export the configuration in
Keycloak OIDC JSON format.
Login is initiated by the Application by initializing itself with the KeyCloak JSON file shown above, and then initating a call to Login. This redirects the browset to KeyCloak where login is securely done, and then the user is redirected back to the calling application. At this point an authentication
access_token is available to the client application. The raw response decoded looks like this:
access_token has only a short life-span, and needs to be periodically updated by the Application, by making a refresh token API call to KeyCloak, to indicate that the user is still active. The
access_token contains all the information associated with the Application, that we had configured on the KeyCloak client earlier. The client can make authenticated and unauthenticated API calls to a server side API, but for authenticated Server Side apis, the
access_token is passed, and validated at the server end. Validation happens at the server end, by passing the token back to the KeyCloak server, to an introspecting API, which returns a status of
active = false if the token is invalidated, or if it is valid returns the full decoded content of the token:
The decoded information(for e.g. the roles) can be used by the server API to apply it to business logic - for instance, filter queried data based on the role of the user, and send it back to the client in the API response. Effectively there is an overhead of querying KeyCloak to instrospect the token for every request made to the the server.
There is an alternative approach which avoids the overhead of the request, by making use of signed JWT, where the signature passed by the client is validated by the server API using standard JWT libraries, without querying KeyCloak. We have not implemented this in Gawati yet.