ccouzens/keycloak-openapi

OpenAPI definitions for Keycloak's Admin API

Keycloak-Admin-OpenAPI-Definition

OpenAPI definitions for Keycloak's Admin API.

These can be used to generate libraries for interacting with Keycloak from any mainstream programming langauge.

OpenAPI definitions are sometimes known by their previous name of Swagger specifications.

Keycloak 22.0.0 Admin API

Keycloak 13.0 Admin API with patches

Keycloak 12.0 Admin API with patches

Other versions

Alternatives

DAHAG Rechtsservices AG provide OpenAPI definitions for recent versions of Keycloak which are more complete than what's here.

Account API

Keycloak has an undocumented Account API that is used by the internal account console to display and update user information. This can be used for building a custom account console, or building account information and editing into an application. @xgp has created a Gist of OpenAPI definitions of the Account API.

General Usage

Typically to use Keycloak's admin Rest API, you first get a token from a realm. This is done using the OAuth2 protocol.

bearer_token=$(curl -X POST 'http://localhost:8080/auth/realms/master/protocol/openid-connect/token' \
     --data-urlencode 'username=admin-user' \
     --data-urlencode 'password=admin-password' \
     --data-urlencode 'grant_type=password' \
     --data-urlencode 'client_id=admin-cli' \
      | jq -r '.access_token')

The realm used for the token is not necessarily the realm used in the API.

The endpoints in this specification can then be used with a base url of the form http://localhost:8080/auth/admin/realms and the above bearer token.

Please see the example app.

Help wanted

The definitions are computer generated, but could do with a human's input.

Please provide additional example apps.

Adding new versions

To add a new version of Keycloak perform these steps:

1. Modify the Makefile with the new version.
2. Verify you have installed the requirements.
3. Run the command make. It will automatically:
   1. download the documentation in HTML format
   2. compile the transformer
   3. create the JSON definition
   4. create the YML definition
4. Commit your changes and open a pull request.

Notable Changes

2021 Early - Renamed master branch to main. Anyone fetching the schema directly from the branch should update their reference.

2020 May - Added tags to operations. Users of OpenAPI Generator generated clients will need to swap from using the DefaultApi class to multiple classes such as UsersApi or ClientsApi.

Example App

This example uses openapi-generator to build an API-client. The app in the example is very simple and only fetches a list of Keycloak-clients.

# Create a keycloak instance to run against
docker container run --rm -e KEYCLOAK_USER=admin-user -e KEYCLOAK_PASSWORD=admin-password -p 8080:8080 docker.io/jboss/keycloak:13.0.0
# Open http://localhost:8080/ and wait for keycloak to start up

# In a second terminal run
cd example_app
npm install
npm run generate-client
npm run compile
node dist/index.js
# prints out
# The default clients:
#   account
#   account-console
#   admin-cli
#   broker
#   master-realm
#   security-admin-console

In general, clients can be generated by running a command similar to:

openapi-generator generate -i 'https://github.com/ccouzens/keycloak-openapi/raw/main/keycloak/20.0.3.json' -g 'typescript-axios' -o 'src/keycloak-client'

or using docker, if you can't install openapi-generator:

docker run --rm --user $(id -u):$(id -g) -v $PWD:/local openapitools/openapi-generator-cli generate -i 'https://github.com/ccouzens/keycloak-openapi/raw/main/keycloak/20.0.3.json' -g typescript-axios -o /local/src/keycloak-client

Keycloak OpenAPI Transformer

All the OpenAPI definitions are generated from the published HTML documentation. This tool transforms the HTML documentation into OpenAPI definitions.

HTML of the documentation is inputted through stdin and the JSON of the definition is outputted through stdout.

Requirements

Building Red Hat Single Sign-On definitions or rebuilding Keycloak's definitions requires:

• make
• Rust
• yq

Building the transformer requires Rust.

Building the example app requires Node and Java.

Running the keycloak instance that pairs with the example app requires Docker.

Licensing

The OpenAPI definitions are Apache 2.0 licensed.

The transformer is MIT licensed.

The example app has a CC0 waiver (has had its copyright waived).

keycloak-openapi's Issues

16.1.json?

Is 16.0.json compatible with Keycloak 16.1.0 or do we need a 16.1.json for that?

If 16.1.json is required, please provide it and please also provide the "patched" variant (see also #15).

Thanks a lot!

Remove Default from tagging

Related to #2

1. Visit https://petstore.swagger.io/
2. Enter https://raw.githubusercontent.com/ccouzens/keycloak-openapi/master/keycloak/10.0.json in the explore input field
3. Notice that the Default tag is duplicating the content.

I would propose to remove Default from the tagging, otherwise, it will generate duplicates in the swagger configuration, and I am not sure what is the value-added since every single operation has Default in it (unless I am missed something and I may be wrong)

OpenAPI spec file for Keycloak account API

I don't know if you want to include this, but I made a pass at an OpenAPI spec file for Keycloak account API:

https://gist.github.com/xgp/2d77cbebc6164160faae6aa77d127a57

Based on the code here: https://github.com/keycloak/keycloak/blob/main/services/src/main/java/org/keycloak/services/resources/account/AccountRestService.java

This would be useful for anyone building a custom account console, or building account info/editing into their application.

Let me know if you want to add this, and I'll put together a PR for it.

Tidying up the OpenAPI description

I probably need to be corrected on soem of my assumptions, but from what I can tell, the KeyCloak project does not publish OpenAPI descriptions, so this project was set up to generate them by parsing the KeyCloak code. This is the only OpenAPI description for KeyCloak, so it's this or nothing. Like I say, I may be wrong on that, but that's where I'm coming from.

The generated OpenAPI description is probably the best that can be generated, given its source. It lacks operation IDs, many descriptions, and most data types and validation rules. It is understandable that those cannot always be parsed from the code, and what has been achieved is remarkable.

Now, I would like to generate code from the OpenAPI description, which means a lot of the missing bits need to be filled in to create consistent and clean code. There are over 1300 errors that show as OpenAPI violations. The code generators do what they can to work around that, but it's still not quite enough.

For example, endpoint /{realm}/client-scopes/{id}/protocol-mappers/protocol/{protocol} does not have an operationId defined, so the generator constructs one from the path, coming up with realmClientScopesId1ProtocolMappersModelsId2Get. That's a bit of a mouthful, so setting an operatinoId, which must be unique, would help set that function to what the operation is really doing - getRealmClientScopesProtocolMappersModels. It could probably be shortened more - the "Models" suffix is likely redundant.

Then the function takes three parameters: a realm and two IDs. All are strings, with no defined format, presumably mandatory, no validation rules, no descriptions. All that should be in the OpenAPI description, and all that results in generated code that applies those validation rules and prevents requests from being sent if the data is not at least in the right format.

Then the results all map onto success models if the server returns a "2XX" response code. That's it a "2 followed by two more digits" - it is literally a 2XX response code. That generates code that simply will not work, because that response will never be returned by a HTTP response. The code generation templates could possibly be modified to look specifically for a "2XX" in the API description and map it to some code that looks for "200" to "299", but that's not ideal.

So, sounds like a bunch of criticisms, and I hope it does not come over negatively. However, I'm just trying to set the scene, to describe how we generally use OpenAPI descriptions to generate code. They also feed into test tools such as Prism and generated documentation. The golden rule that works for us, is that the OpenAPI description is the source of truth - it generates code that we then do not touch. If the code needs to change, then we change the generation templates, grab a new OpenAPI desription, and generate again.

So where am I going with this. It's a question: how can we fix this? There are many thousands of fixes that could or should be done to the OpenAPI description, but is there a place to do that within this project? Most will be done manually, with a decision being made by someone choosing a name, or looking up a validation rule or data format. They probably could not be done by one person, since it will involve much knowledge, and it would take time. If the descriptino file is edited directly (using a tool like Stoplight Studio perhaps) then what happens when the source file needs to be generated again?

Or perhaps for my own projects I need to take the OpenAPI file, strip out or ignore everything I am not going to use, and manually fix up what's left? That feels like a missed opportunity, and a frozen API that will drift away from reality.

Sorry for the long read - I hope it's clear what I'm looking for: a way to fix up the files to make them complete, while being able to carry those fixes forward for all to share. Do you have any thoughts or suggestions on this?

Please provide 16.0-patched.json

Please do your magic and provide 16.0-patched.json 🪄

yaml version

json is a bit hard to read,
maybe we can also generate a yaml version

OpenAPI definition for Keycloak Protection API

Hi @ccouzens, thanks for providing the OpenAPI definitions for the Keycloak Admin interface. I've been trying to find a similar OpenAPI spec for the Keycloak Protection API since we need to use both but I've not found anything so far, or I'm looking in the wrong place. Could you let me know where you sourced the JSON OAPI definitions in https://github.com/ccouzens/keycloak-openapi/tree/master/keycloak - maybe that would give me some pointers for the Protection API.

Additional example apps

There is currently one very basic example app, written in nodejs that gets a list of clients.

It would be good to have more example apps.

The examples can do more, or they could be written in a different language or framework.

The examples can be part of this repo, or they can be linked off to another repo if that's the preference of the contributor.

It would be good for any examples to have usage instructions, especially if they're using a language or tooling I'm not familiar with.

Add tags for grouping paths

Hey there,

First, thank you very much for putting this together.

It would be great to follow the documentation https://www.keycloak.org/docs-api/5.0/rest-api/index.html left section where they group the paths in a logical way using tags https://swagger.io/docs/specification/grouping-operations-with-tags/

• Attack Detection
• Authentication Management
• Client Attribute Certificate
• Client Initial Access
• Client Registration Policy
• Client Role Mappings
• Client Scopes
• Clients
• Component
• Groups
• Identity Providers
• Key
• Protocol Mappers
• Realms Admin
• Role Mapper
• Roles
• Roles (by ID)
• Scope Mappings
• User Storage Provider
• Users
• Root

{id} path parameter occurs twice in some URLs

{id} path parameter occurs twice in some URLs and parameter definition has "in path" definition for one of them. This will create problems in some applications that use open API specs. For example Azure API management does not allow two path params with same name.
eg : /{realm}/client-scopes/{id}/protocol-mappers/models/{id}

I know that this crawls the official keycloak api docs and it has urls defined in that manner..

Add Keycloak 22.0.1 -> 23.0.1

Generate OpenAPI Docs for Keycloak 22.0.1 -> 23.0.1

• https://www.keycloak.org/2023/11/keycloak-2300-released.html
• https://www.keycloak.org/2023/11/keycloak-2301-released.html
• https://www.keycloak.org/docs-api/23.0.1/rest-api/index.html

Version 12 has 'object' as type, but should be array of type.

I think it's a wider problem than only this, I think if you solve it for this, it will be solved for all:

In v12 this

Get identity providers
GET /{realm}/identity-provider/instances

becomes an object in de openapi json.

But it was in v11 still an array of IdentityProviderRepresentation as it should be.

v12:

keycloak-openapi/keycloak/12.0.json

Line 6963 in b865c66

"type": "object"

v11:

keycloak-openapi/keycloak/11.0.json

Line 7103 in b865c66

"type": "array",

Add operationId to method definition

Hi, thank you for the great project
Is it possible to add the operationId parameter to each method?

If I can contribute to this feature please tell me how

Manually patch the openapi beyond what is possible from autogeneration

The OpenAPI files are all currently auto-generated.

For example, for version 12.0, we download the HTML documentation, it gets processed and we output OpenAPI documentation.

This is great, as it allows me to support a large API and new versions of it without much ongoing effort. And I trust my laptop not to generate typos or make other human mistakes.

The problem is, it can only ever be as good as the HTML documentation. When the HTML documentation is missing information, my program cannot fill in the blanks.

There are several things the HTML documentation is missing:

• The protection API #5
• OperationIds #8
• Useful types for all responses #9 (anything that says it returns a Stream or Map in the HTML is generated to a very generic object)
• Response codes #6
• Various #6

If someone has the time and ability, I would like them to make any of the above changes (even if incomplete) to a copy of the OpenAPI definitions in this repository.

I imagine they would be given a name like keycloak/12.0-patched.json.

If possible, please keep the formatting and order the same to make it easier to diff with the original versions.

Thanks in advance!
Chris