Integrations
Connect Keycloak
Connect Keycloak as an Authorization Server in Apiable. Enter the Server URL, Realm, DCR endpoint and credentials, give the client the three realm-management roles scope binding needs, then test the connection.
You connect Keycloak as an Authorization Server under Integrations → Authorization Servers. You enter your Keycloak server and realm, the Dynamic Client Registration endpoint, and the credentials of a client Apiable signs in with. Apiable then registers a client in your realm for each subscription and binds the plan's scopes to it.
Where do you connect Keycloak?
Go to Integrations → Authorization Servers, choose + Add AuthZ, select Keycloak on the Select Authorization Server type screen, then choose Connect Authorization Server.
- Open Integrations → Authorization Servers.
- Choose + Add AuthZ.
- On Select Authorization Server type, select Keycloak.
- Choose Connect Authorization Server. The Keycloak connection form opens, titled Keycloak Configuration.
What does each Keycloak field mean?
The form has a name, a Server section, a DCR Credentials section, and an optional Admin API section. Fill in the required fields, then save.
| Field | Section | What to enter |
|---|---|---|
| Name | (top) | A label for this connection inside Apiable. Required, and unique across your Authorization Servers. |
| Server URL | Server | Your Keycloak base URL, for example https://keycloak.example.com. Required. Use https. |
| Realm | Server | The Keycloak realm that holds your clients and scopes. Required. |
| DCR Endpoint | Server | The Dynamic Client Registration endpoint. Apiable fills it in from the Server URL and Realm. Override it only if yours differs. |
| DCR Client ID | DCR Credentials | The client ID Apiable signs in with. Required. |
| DCR Client Secret | DCR Credentials | The secret for that client. Required. |
| Admin API Client ID | Admin API (optional) | A second client for the Keycloak Admin REST API. Used only when the checkbox below is ticked. |
| Admin API Client Secret | Admin API (optional) | The secret for that client. Used only when the checkbox below is ticked. |
| Force Admin API for scope binding (advanced) | Admin API (optional) | A checkbox. Tick it to make Apiable use the Admin API client for every call, including client registration. |
Which roles does the Keycloak client need?
The service account of the client Apiable signs in with needs three client roles from realm-management: create-client, manage-clients and view-clients. Registration through the DCR endpoint needs only create-client. Scope binding needs the other two.
| Role | What Apiable uses it for |
|---|---|
create-client | Register a client for each subscription, and the test client. |
manage-clients | Add and remove scopes on a subscription's client, and create scopes when you push them from Apiable. |
view-clients | Find a subscription's client and read the scopes in your realm. |
Assign the roles to the client whose credentials Apiable uses: the DCR client by default, or the Admin API client when Force Admin API for scope binding (advanced) is ticked.
When do you need the Admin API credentials?
Only when you tick Force Admin API for scope binding (advanced). Without it, Apiable uses the DCR credentials for every call and ignores the Admin API fields.
Scope binding always goes through the Keycloak Admin REST API. The checkbox changes two things:
- Which credentials Apiable uses. Unticked, the DCR client. Ticked, the Admin API client, for everything.
- How clients are registered. Unticked, through the standard DCR endpoint. Ticked, through the Admin REST API.
If you tick it, fill in both Admin API fields and give that client the three roles above.
Where must your scopes exist in Keycloak?
As client scopes in your realm, with Include in token scope turned on. Apiable adds them to each subscription's client as default client scopes. A scope that does not exist in the realm makes the binding fail.
You do not have to create them by hand. Sync with Auth Server on the Resource Groups page can push Apiable's scopes to Keycloak. Push creates the missing client scopes and turns on Include in token scope where it is off. See Resource groups and scopes.
How do you save and test the connection?
Click Save. The server's page opens and Apiable runs OIDC discovery for the realm in the background. Then click Test Connection to confirm Keycloak is reachable. The status reads Connected, Error, or Not tested.
- Click Save. A new connection shows Save. When you edit a saved one, the button reads Save & Test Connection and runs a test after saving.
- The server's page opens. The results of OIDC discovery appear under Discovered Auth Methods.
- Click Test Connection. Apiable reads your realm's OpenID configuration at
{server}/realms/{realm}/.well-known/openid-configuration. - Read the status: Connected means the realm responded. Error shows the start of the error message. Not tested means no test has run yet.
Connected means the realm answered. It does not check the client's credentials or roles, and it does not check for HTTPS. Discovery does: it only accepts an https address.
What are Discovered Auth Methods?
Discovered Auth Methods lists the token endpoint authentication methods your realm advertises that Apiable supports: client_secret_basic and private_key_jwt. A plan that uses this server offers them on its Security tab.
Apiable runs discovery when you save a new connection and when you change the Server URL or Realm. Use Refresh in the panel to run it again. The panel shows when it last refreshed, and the error if the realm could not be read.
How do you confirm DCR works?
On the saved connection, click Register Test Client. Apiable registers a client named test-client- followed by the connection's ID, and shows its Client ID and Client Secret once.
This confirms that Apiable can register a client with your credentials, through the DCR endpoint or, with Force Admin API for scope binding (advanced) ticked, the Admin REST API. It does not confirm the roles scope binding needs. Delete the test client from your realm when you are done, because Apiable does not remove it.
Troubleshooting
Match the status or message to the fix.
| What you see | What to do |
|---|---|
| Status Not tested | No connection test has run yet. Open the server and click Test Connection. |
| Status Error with "Keycloak returned ..." | Keycloak answered, but the realm's discovery address returned an error status. Check the Realm spelling and that the realm exists. |
| Status Error with "Failed to reach Keycloak at ..." | Apiable could not reach the URL. Check the Server URL and that Keycloak is reachable from Apiable. |
| Discovery error "Issuer must be HTTPS (plain HTTP is only allowed for loopback issuers in local development)" | Change the Server URL to its https address, save, then click Refresh. |
| Discovery error "Connection timeout after 5s" | The discovery address did not respond in time. Confirm the realm URL is reachable, then click Refresh. |
| Discovered Auth Methods shows another discovery error | Confirm the Server URL and Realm resolve to a valid .well-known/openid-configuration, then click Refresh. |
| The Name field says "An authorization server named '{name}' already exists." | Each Authorization Server needs a unique name. Choose another name and save again. |
| Register Test Client returns an error | Apiable could not register a client. Check the DCR Client ID and DCR Client Secret (or the Admin API fields, if the checkbox is ticked), the DCR Endpoint, and that the service account has create-client. |
| Tokens carry none of the plan's scopes, although the plan shows them as Active | Give the service account manage-clients and view-clients, and create the plan's scopes in the realm. Subscriptions created before the fix keep a client without those scopes until their credentials are regenerated. |
| Registration and scope binding fail after you tick Force Admin API for scope binding (advanced) | Apiable now signs in with the Admin API client. Fill in both Admin API fields and give that client the three roles. |