Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[KEYCLOAK-19303] - Allow managing providers through CLI #328

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
+83 −0
Open

[KEYCLOAK-19303] - Allow managing providers through CLI #328

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
83 changes: 83 additions & 0 deletions design/keycloak.x/configuration.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -563,6 +563,89 @@ Examples of commands are:
Commands may support additional options to change how they are executed and behavior. For that, commands should provide the
help and usage messages to document how they can be used as well as the different options they support.

### The `provider` command

The `provider` command provides utilities to query, (un)install, and enable/disable providers. The usage of this command is the following:
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Does provider install command allow to add custom provider implementation with java classes in some jar file or source repo into the KC image?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah, that is the idea. It would be a more clean alternative to deploying jars directly into the providers directory.

We could also:

  • Support fetching providers via HTTP (e.g.: maven artifact)
  • Provide some nice repository for oficial extensions (similar to what quarkus does) and use this repository for listing and installing additional features

But initially, I'm not sure if it makes sense to provide the installation commands. But focus on troubleshooting and querying the distribution for details about what is installed.


```
kc.[sh|bat] spi [list-spi|list] [
```

By running `kc.[sh|bat] provider`, the CLI should list all installed providers:

```
Listing installed providers (see --help for more options):

hostname
Default: default
Provider (name: default, factory: class org.keycloak.url.DefaultHostnameProviderFactory)

localeSelector
Default: default
Provider (name: default, factory: class org.keycloak.locale.DefaultLocaleSelectorProviderFactory)

localeUpdater
Default: default
Provider (name: default, factory: class org.keycloak.locale.DefaultLocaleUpdaterProviderFactory)

To get more information, including the complete list of providers for a SPI, append `--full` to your command line.
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

maybe "...including a complete list of available providers..." is more concise here? Also: What does "all installed" mean. All "used at the moment", or "all which are installed in general for Keycloak.X" - from the result I think it's the former, which I'd also prefer. Just want to double-check.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Installed means those Keycloak is using, those you have at runtime. The available providers (even those not installed) should be there when using --all.


To get information about providers for a specific SPI, append `--spi <spi>` to your command line.
```

To get more information about each SPI, it should be possible to run `kc.[sh|bat] list-spi`:

```
Listing available SPI (see --help for more options)
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not sure if this makes sense at all without the information provided by --full. Can you clarify the use case of just running kc.sh list-spi?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah, it kinds of lacks some value. But the design is based on incremental steps:

  • What are the SPI offered by Keycloak that I can customize? Run list-spi.
  • How can I customize that SPI? Run with --full.
  • What are all the SPI offered by Keycloak even those I'm not supposed to customize? Run -all.

Note that regardless of the approach, the value-added is still not great. IMO, the reasons are:

  • Although Keycloak is very often customized, most of the SPI people use is marked as internal. That is kind of contradictory. Most of our SPIs are marked as private and never managed to get as public.
  • We lack a description and documentation for most SPIs. It would be nice if we could show to people at least a description and give them a link to our doc about how to use an SPI (e.g.: https://www.keycloak.org/docs/latest/server_development/)
  • One of the improvements we discussed to Developer Experience is abstract the complexities of our SPIs and allow people to write extensions based on CDI and Annotations. Possibly using archetypes for creating projects with some example code. Showing interfaces you can use is not so user-friendly.

I'm also not sure about list-spi. If you guys think we can live without it, I'm fine to removing it.


role

loginFailure

userCache SPI

cekmanagement SPI

To get more information, append `--full` to your command line.
```

When running `list-spi` with the `--full` option, more details are displayed as follows:

```
localeUpdater
Factory: interface org.keycloak.locale.LocaleUpdaterProviderFactory
Interface: interface org.keycloak.locale.LocaleUpdaterProvider
Enabled: true

storage
Factory: interface org.keycloak.storage.UserStorageProviderFactory
Interface: interface org.keycloak.storage.UserStorageProvider
Enabled: true

themeSelector
Factory: interface org.keycloak.theme.ThemeSelectorProviderFactory
Interface: interface org.keycloak.theme.ThemeSelectorProvider
Enabled: true
```

In order to obtain details about providers for a specific SPI, it should be possible to run `kc.[sh|bat] provider --spi cekmanagement --full`:

```
Current providers installed for "cekmanagement" SPI:

Default: undefined
Provider (name: RSA-OAEP, factory: class org.keycloak.crypto.RsaesOaepCekManagementProviderFactory)
Provider (name: RSA-OAEP-256, factory: class org.keycloak.crypto.RsaesOaep256CekManagementProviderFactory)
Provider (name: RSA1_5, factory: class org.keycloak.crypto.RsaesPkcs1CekManagementProviderFactory)
```

The `provider` command should provide the following sub-commands:

* `enable`, to enabled providers
* `disable`, to disabled providers
* 'install', to install a provider
* 'uninstall', to install a provider
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

typo: "to _un_install"


## Documentation

All options and commands should be documented properly to make it easy for users to discover what can be configured and which actions can be performed. This
Expand Down