Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
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
51 changes: 51 additions & 0 deletions docs/documentation/upgrading/topics/changes/changes-27_0_0.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -362,6 +362,57 @@ String saUserId = clientResource.toRepresentation().getServiceAccountUserId();
The `getServiceAccountUser()` method has also been removed from the Java and JavaScript admin client libraries.
If you need the full user representation for the service account, use the user ID from the client representation to fetch it via the Users API.

=== Client registration `install` provider removed
// https://github.com/keycloak/keycloak/issues/53478

The `install` client registration provider, which was deprecated in {project_name} 26.8, has been removed.
Requests to `/realms/<realm>/clients-registrations/install/<clientId>` now return a `404 Not Found` response.

The following related APIs have also been removed:

* The `getAdapterConfig()` method of the `ClientRegistration` class in the Java client registration library (`keycloak-client-registration-api`).
* The `install` endpoint type (`-e install` or `-e adapter`) of the `kcreg get` command.

Retrieve the adapter configuration of a client with the Admin REST API instead, using `GET /admin/realms/<realm>/clients/<client-uuid>/installation/providers/<provider-id>`, for example with the `keycloak-oidc-keycloak-json` provider.
The same configuration is available from `kcadm.sh get clients/<client-uuid>/installation/providers/keycloak-oidc-keycloak-json`.

The removed endpoint accepted client credentials or a registration access token, and it did not require authentication for public clients.
The Admin REST API endpoint requires an access token with permission to view the client.
Applications that loaded their `keycloak.json` anonymously from the removed endpoint, such as JavaScript applications, must bundle the configuration with the application or fetch it with an authenticated call.

=== SAML Entity Descriptor client registration endpoint removed
// https://github.com/keycloak/keycloak/issues/53478

The deprecated client registration provider `saml2-entity-descriptor` has been removed.
Requests to `/realms/<realm>/clients-registrations/saml2-entity-descriptor` now return an HTTP 404 status.

The following related APIs have also been removed:

* The `ClientRegistration.saml()` method and the `ClientRegistration.SAMLClientRegistration` class in the Java client registration API.
* The `saml2` endpoint type of the `kcreg` command-line tool. `kcreg create -e saml2` is no longer accepted, and `kcreg create` no longer treats an XML input document as a SAML entity descriptor. Use JSON input with the `oidc` endpoint type.

To create a client from a SAML entity descriptor, convert the descriptor with the Admin REST API (`POST /admin/realms/<realm>/client-description-converter`), then create the returned client representation (`POST /admin/realms/<realm>/clients`).
The conversion endpoint itself is not affected by this change.

=== Default client registration provider removed
// https://github.com/keycloak/keycloak/issues/53478

The `default` client registration provider, deprecated in {project_name} 26.8, has been removed.
Requests to `/realms/<realm>/clients-registrations/default` and its client resources now return HTTP 404.
The outer `ClientRegistration` methods `create(ClientRepresentation)`, `get(String)`, `update(ClientRepresentation)`, `delete(ClientRepresentation)` and `delete(String)` have also been removed from the Java client registration API.
Use `reg.oidc()` with `OIDCClientRepresentation` for OIDC registration, or the Admin REST API for {project_name} Client Representations.
The Admin REST API requires an administrator access token with appropriate client-management permissions and does not accept initial access tokens or registration access tokens.

The `kcreg` create, get, update, delete and attrs commands now use OIDC metadata by default.
The `-e default` option is no longer accepted.
Replace fields such as `clientId`, `redirectUris` and `baseUrl` with the supported OIDC fields `client_name`, `redirect_uris` and `client_uri`, where appropriate.
`client_name` is a display name; the server generates `client_id`, which must be used for subsequent get, update and delete commands.
Use `kcreg create -i` to print that identifier, or retrieve it from the `-o` JSON output.
Use the Admin REST API or `kcadm` for internal representation settings without an OIDC equivalent.

Client registration policies that still apply to OIDC remain available, including protocol-mapper filtering after client creation.
The default-roles policy is retained for existing realm components and custom registration providers; OIDC metadata does not expose `defaultRoles`.

=== Kerberos password authentication accepts only allowed realms
// https://github.com/keycloak/keycloak/issues/54271

Expand Down
80 changes: 31 additions & 49 deletions docs/guides/securing-apps/client-registration-cli.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -14,11 +14,14 @@ You can configure application clients from a command line with the Client Regist

To allow a particular user to use `Client Registration CLI`, the {project_name} administrator typically uses the Admin Console to configure a new user with proper roles or to configure a new client and client secret to grant access to the Client Registration REST API.

[WARNING]
====
The `kcreg` CLI tool primarily uses the `default` client registration provider, which is deprecated since {project_name} 26.8 and will be removed in a future major release.
For new integrations, register and manage clients using the Admin REST API or the standards-compliant OpenID Connect dynamic client registration endpoint (`/realms/<realm>/clients-registrations/openid-connect`).
====
The CLI uses the OpenID Connect dynamic client registration endpoint by default.
JSON input uses OIDC metadata fields such as `client_name`, `redirect_uris` and `client_uri`.
The removed `default` endpoint type is no longer accepted.
Use the Admin REST API or `kcadm` for settings available only in {project_name} Client Representation format.

The server generates a `client_id`; `client_name` is a display name, not the identifier used for get, update or delete.
Use `kcreg create -i` to print only the generated identifier, or read `client_id` from the JSON returned by `kcreg create -o`.
In the examples below, replace `<client-id>` with that identifier.

[[_configuring_a_user_for_client_registration_cli]]
== Configuring a new regular user for use with Client Registration CLI
Expand Down Expand Up @@ -113,16 +116,16 @@ For example, on:
[options="npwrap",subs="attributes+"]
----
$ kcreg.sh config credentials --server http://localhost:8080 --realm demo --user user --client reg-cli
$ kcreg.sh create -s clientId=my_client -s 'redirectUris=["http://localhost:8980/myapp/*"]'
$ kcreg.sh get my_client
$ CLIENT_ID=$(kcreg.sh create -i -s client_name=my_client -s 'redirect_uris=["http://localhost:8980/myapp/*"]')
$ kcreg.sh get "$CLIENT_ID"
----
* Windows:
+
[options="npwrap",subs="attributes+"]
----
c:\> kcreg config credentials --server http://localhost:8080 --realm demo --user user --client reg-cli
c:\> kcreg create -s clientId=my_client -s "redirectUris=[\"http://localhost:8980/myapp/*\"]"
c:\> kcreg get my_client
c:\> kcreg create -i -s client_name=my_client -s "redirect_uris=[\"http://localhost:8980/myapp/*\"]"
c:\> kcreg get <client-id>
----
+
[NOTE]
Expand Down Expand Up @@ -205,28 +208,28 @@ For example, on:
[options="nowrap"]
----
$ kcreg.sh config initial-token $TOKEN
$ kcreg.sh create -s clientId=myclient
$ kcreg.sh create -s client_name=myclient
----

or

[options="nowrap"]
----
$ kcreg.sh create -s clientId=myclient -t $TOKEN
$ kcreg.sh create -s client_name=myclient -t $TOKEN
----

* Windows:
[options="nowrap"]
----
c:\> kcreg config initial-token %TOKEN%
c:\> kcreg create -s clientId=myclient
c:\> kcreg create -s client_name=myclient
----

or

[options="nowrap"]
----
c:\> kcreg create -s clientId=myclient -t %TOKEN%
c:\> kcreg create -s client_name=myclient -t %TOKEN%
----

When using an Initial Access Token, the server response includes a newly issued Registration Access Token. Any subsequent operation for that client needs to be performed by authenticating with that token, which is only valid for that client.
Expand All @@ -243,17 +246,17 @@ Run the [command]`kcreg config initial-token --help` and [command]`kcreg config

The first task after authenticating with credentials or configuring an Initial Access Token is usually to create a new client. Often you might want to use a prepared JSON file as a template and set or override some of the attributes.

The following example shows how to read a JSON file, override any client id it may contain, set any other attributes, and print the configuration to a standard output after successful creation.
The following example shows how to read a JSON file, override the client name, set any other attributes, and print the configuration to a standard output after successful creation.

* Linux:
[options="nowrap"]
----
$ kcreg.sh create -f client-template.json -s clientId=myclient -s baseUrl=/myclient -s 'redirectUris=["/myclient/*"]' -o
$ kcreg.sh create -f client-template.json -s client_name=myclient -s client_uri=http://localhost:8980/myclient -s 'redirect_uris=["http://localhost:8980/myclient/*"]' -o
----
* Windows:
[options="nowrap"]
----
C:\> kcreg create -f client-template.json -s clientId=myclient -s baseUrl=/myclient -s "redirectUris=[\"/myclient/*\"]" -o
C:\> kcreg create -f client-template.json -s client_name=myclient -s client_uri=http://localhost:8980/myclient -s "redirect_uris=[\"http://localhost:8980/myclient/*\"]" -o
----

Run the [command]`kcreg create --help` for more information about the [command]`kcreg create` command.
Expand All @@ -271,33 +274,12 @@ For example, on:
* Linux:
[options="nowrap"]
----
$ kcreg.sh get myclient
----
* Windows:
[options="nowrap"]
----
C:\> kcreg get myclient
----

[WARNING]
====
The `-e install` flag retrieves adapter configuration via the deprecated `install` client registration provider.
Use the Admin REST API (`GET /admin/realms/<realm>/clients/<client-uuid>/installation/providers/<provider-id>`) instead.
====

You can also retrieve the client configuration as an adapter configuration file, which you can package with your web application.

For example, on:

* Linux:
[options="nowrap"]
----
$ kcreg.sh get myclient -e install > keycloak.json
$ kcreg.sh get <client-id>
----
* Windows:
[options="nowrap"]
----
C:\> kcreg get myclient -e install > keycloak.json
C:\> kcreg get <client-id>
----

Run the [command]`kcreg get --help` command for more information about the [command]`kcreg get` command.
Expand All @@ -314,16 +296,16 @@ For example, on:
* Linux:
[options="nowrap"]
----
$ kcreg.sh get myclient > myclient.json
$ kcreg.sh get <client-id> > myclient.json
$ vi myclient.json
$ kcreg.sh update myclient -f myclient.json
$ kcreg.sh update <client-id> -f myclient.json
----
* Windows:
[options="nowrap"]
----
C:\> kcreg get myclient > myclient.json
C:\> kcreg get <client-id> > myclient.json
C:\> notepad myclient.json
C:\> kcreg update myclient -f myclient.json
C:\> kcreg update <client-id> -f myclient.json
----

The second method fetches the current client, sets or deletes fields on it, and posts it back in one step.
Expand All @@ -333,12 +315,12 @@ For example, on:
* Linux:
[options="nowrap"]
----
$ kcreg.sh update myclient -s enabled=false -d redirectUris
$ kcreg.sh update <client-id> -s client_name=myclient-updated -d redirect_uris
----
* Windows:
[options="nowrap"]
----
C:\> kcreg update myclient -s enabled=false -d redirectUris
C:\> kcreg update <client-id> -s client_name=myclient-updated -d redirect_uris
----

You can also use a file that contains only changes to be applied so you do not have to specify too many values as arguments. In this case, specify [command]`--merge` to tell the Client Registration CLI that rather than treating the JSON file as a full, new configuration, it should treat it as a set of attributes to be applied over the existing configuration.
Expand All @@ -348,12 +330,12 @@ For example, on:
* Linux:
[options="nowrap"]
----
$ kcreg.sh update myclient --merge -d redirectUris -f mychanges.json
$ kcreg.sh update <client-id> --merge -d redirect_uris -f mychanges.json
----
* Windows:
[options="nowrap"]
----
C:\> kcreg update myclient --merge -d redirectUris -f mychanges.json
C:\> kcreg update <client-id> --merge -d redirect_uris -f mychanges.json
----

Run the [command]`kcreg update --help` command for more information about the [command]`kcreg update` command.
Expand All @@ -366,12 +348,12 @@ Use the following example to delete a client.
* Linux:
[options="nowrap"]
----
$ kcreg.sh delete myclient
$ kcreg.sh delete <client-id>
----
* Windows:
[options="nowrap"]
----
C:\> kcreg delete myclient
C:\> kcreg delete <client-id>
----

Run the [command]`kcreg delete --help` command for more information about the [command]`kcreg delete` command.
Expand Down
Loading
Loading