Purpose
This guide explains how to create a new Keycloak client for an external application and use its client secret with the Giotto Python client.
By the end of this guide, you will have:
- logged into Keycloak as an administrator
- created a new client for your application
- enabled the correct client settings
- retrieved the client secret
- used the new client in a working Python example
Overview
If you want an external application to authenticate against Giotto, you need to create a dedicated Keycloak client for that application.
The process is simple:
- log into Keycloak as admin
- select the correct realm
- create a new client
- assign a client ID
- enable service accounts and client authentication
- save the client
- Go to the dedicated scope under the Client scopes tab
- Select Configure a new mapper and add an Audience mapper with all permissions enabled
- retrieve the client secret from the Credentials tab
- use that secret in your application
In this guide, the example client ID is:
my-app-clientBefore you begin
Make sure you have:
- access to the Giotto homepage
- admin credentials for Keycloak
- access to the application environment where the new client will be used
- a deployed model or agentic system to test against afterward
Step 1 — Log into Keycloak as admin
Open the Keycloak admin interface and log in using your administrator credentials.
This gives you access to realms, clients, users, and credentials.
Step 2 — Move to the giotto realm
Once logged in:
- open the Realms section
- select the giotto realm
This is the realm where the new application client will be created.
Step 3 — Go to Clients and create a new client
Inside the giotto realm:
- open the Clients section
- click Create client or the equivalent create action in the UI
This starts the creation flow for the new application client.
Step 4 — Choose the client ID
When prompted for the client identifier, enter:
my-app-clientThis will be the client_id used by your application.
You can choose a different name if needed, but my-app-client is the example used in this guide.
Step 5 — Enable service accounts and client authentication
In the client settings:
- enable Service accounts
- enable Client authentication
These are the key settings required for this use case.
Why these settings matter
- Service accounts allow the client itself to authenticate as a machine-to-machine application
- Client authentication enables the use of a client secret
Together, these settings make the client usable from backend code such as the Giotto Python client.
Step 6 — Ignore the rest and save
For this guide, you can leave the remaining settings unchanged and save the client.
Once saved, the new client is created and becomes available in the Clients list.
Step 7 — Go to the dedicated Client scopes
Move to the client scopes and select the <client-name>-dedicated scope. For this tutorial this scope is called my-app-client-dedicated.
This is the place where mappers for the client can be created and placed.
Step 8 — Add authentication Audience mapper
After selecting the dedicated scope you have the option to Configure a new mapper
Select the Audience option.
Fill out the mapper settings as shown below with all permissions active
The purpose of this mapper is to allow the client to inform the authentication proxy that this client may posses an authentication token. The authentication proxy can then verify the authentication token and allow the client to pass requests directly to the model without the need for redirection to the authentication server for further validation
Step 9 — Go to Credentials and retrieve the token
After the client is saved:
- open the new client
- go to the Credentials tab
- copy the client secret
This secret is the value your application will use as its authentication token.
Important: treat this secret as sensitive. Do not commit it to source control or expose it in screenshots, logs, or shared documentation.
Step 10 — Use the new client in your application
Now test the client by using the new client_id and secret in a simple Python script.
client = GiottoClient(
base_url=f"{BASE_URL}/api",
keycloak_base_url=f"{BASE_URL}/keycloak",
realm="giotto",
client_id="my-app-client",
client_secret="<your_new_token>",
)
response = client.responses.create(
model="giotto-model",
input="Write a one-sentence bedtime story about a unicorn.",
)
print(response.output_text)What this does
This script:
- authenticates with your newly created Keycloak client
- sends a simple request to the deployed model
- prints the model output
If everything is configured correctly and the target model is already deployed, the script should return a normal response.
Expected result
A valid response may look like:
The little unicorn curled up in the soft clover field, dreaming of silver stars as the gentle moon watched over him.Security note
The client secret is effectively a credential for your application.
Follow these best practices:
- do not hard-code it in production code
- use environment variables or a secret manager
- rotate it if it is ever exposed
- restrict access to client management in Keycloak
A safer pattern is to load the secret from the environment rather than embedding it directly in code.
Troubleshooting tips
I cannot create the client
Make sure you are logged in with administrative permissions and are working inside the correct realm.
The client authenticates, but the request fails
Check that:
- the model name is correct
- the model is already deployed
- the base URLs and realm match your environment
The secret does not work
Verify that:
- you copied the full secret correctly
- client authentication is enabled
- service accounts are enabled
- you are using the correct client ID
The script runs, but no response comes back
Inspect the deployed system and confirm that the target model is healthy and reachable.
Best practices
Create one client per application
This makes access easier to manage and rotate over time.
Use clear client IDs
A descriptive client name makes administration easier later.
Restrict who can access client secrets
Only administrators or trusted operators should retrieve or manage credentials.
Test immediately after creation
The simplest validation is to run a small Python request like the one shown above.
Comments
0 comments
Article is closed for comments.