From 188893222fe4899af09074748c5b2ce569b798fa Mon Sep 17 00:00:00 2001 From: Jon Koops Date: Wed, 11 Sep 2024 17:46:04 +0200 Subject: [PATCH] Remove references of statically served Keycloak JS from documentation Closes #32821 Signed-off-by: Jon Koops --- .../topics/enforcer-js-adapter.adoc | 50 +++++++++++-------- .../topics/identity-broker/suggested.adoc | 2 +- .../upgrading/topics/upgrade_adapters.adoc | 5 +- .../securing-apps/javascript-adapter.adoc | 4 +- docs/guides/server/reverseproxy.adoc | 8 --- 5 files changed, 34 insertions(+), 35 deletions(-) diff --git a/docs/documentation/authorization_services/topics/enforcer-js-adapter.adoc b/docs/documentation/authorization_services/topics/enforcer-js-adapter.adoc index 08f4674597..52241221ac 100644 --- a/docs/documentation/authorization_services/topics/enforcer-js-adapter.adoc +++ b/docs/documentation/authorization_services/topics/enforcer-js-adapter.adoc @@ -4,20 +4,31 @@ The {project_name} Server comes with a JavaScript library you can use to interact with a resource server protected by a policy enforcer. This library is based on the {project_name} JavaScript adapter, which can be integrated to allow your client to obtain permissions from a {project_name} Server. -You can obtain this library from a running a {project_name} Server instance by including the following `script` tag in your web page: +You can obtain this library by installing it https://www.npmjs.com/package/keycloak-js[from NPM]: -[source,html,subs="attributes+"] +[source,bash] ---- - +npm install keycloak-js ---- + Next, you can create a `KeycloakAuthorization` instance as follows: [source,javascript] ---- -const keycloak = ... // obtain a Keycloak instance from keycloak.js library +import Keycloak from "keycloak-js"; +import KeycloakAuthorization from "keycloak-js/authz"; + +const keycloak = new Keycloak({ + // Replace this with your own configuration. + url: "http://keycloak-server", + realm: "myrealm", + clientId: "myapp" +}); + const authorization = new KeycloakAuthorization(keycloak); ---- -The *keycloak-authz.js* library provides two main features: + +The `keycloak-js/authz` library provides two main features: * Obtain permissions from the server using a permission ticket, if you are accessing a UMA protected resource server. @@ -48,15 +59,14 @@ and use the library to send an authorization request as follows: [source,javascript] ---- // prepare a authorization request with the permission ticket -const authorizationRequest = {}; -authorizationRequest.ticket = ticket; +const authorizationRequest = { ticket }; // send the authorization request, if successful retry the request -Identity.authorization.authorize(authorizationRequest).then(function (rpt) { +authorization.authorize(authorizationRequest).then((rpt) => { // onGrant -}, function () { +}, () => { // onDeny -}, function () { +}, () => { // onError }); ---- @@ -71,13 +81,13 @@ Most applications should use the `onGrant` callback to retry a request after a 4 == Obtaining entitlements -The ```keycloak-authz.js``` library provides an `entitlement` function that you can use to obtain an RPT from the server by providing +The `keycloak-js/authz` library provides an `entitlement` function that you can use to obtain an RPT from the server by providing the resources and scopes your client wants to access. .Example about how to obtain an RPT with permissions for all resources and scopes the user can access [source,javascript] ---- -authorization.entitlement('my-resource-server-id').then(function (rpt) { +authorization.entitlement("my-resource-server-id").then((rpt) => { // onGrant callback function. // If authorization was successful you'll receive an RPT // with the necessary permissions to access the resource server @@ -87,13 +97,13 @@ authorization.entitlement('my-resource-server-id').then(function (rpt) { .Example about how to obtain an RPT with permissions for specific resources and scopes [source,javascript] ---- -authorization.entitlement('my-resource-server', { - "permissions": [ +authorization.entitlement("my-resource-server", { + permissions: [ { - "id" : "Some Resource" + id: "Some Resource" } ] -}).then(function (rpt) { +}).then((rpt) => { // onGrant }); ---- @@ -108,7 +118,7 @@ The `entitlement` function is completely asynchronous and supports a few callbac == Authorization request -Both ```authorize``` and ```entitlement``` functions accept an authorization request object. This object can be set with the following +Both `authorize` and `entitlement` functions accept an authorization request object. This object can be set with the following properties: * *permissions* @@ -118,10 +128,10 @@ An array of objects representing the resource and scopes. For instance: [source,javascript] ---- const authorizationRequest = { - "permissions": [ + permissions: [ { - "id" : "Some Resource", - "scopes" : ["view", "edit"] + id: "Some Resource", + scopes: ["view", "edit"] } ] } diff --git a/docs/documentation/server_admin/topics/identity-broker/suggested.adoc b/docs/documentation/server_admin/topics/identity-broker/suggested.adoc index 3c48e308f8..85a4d992e8 100644 --- a/docs/documentation/server_admin/topics/identity-broker/suggested.adoc +++ b/docs/documentation/server_admin/topics/identity-broker/suggested.adoc @@ -16,7 +16,7 @@ Host: localhost:8080 In this case, your realm must have an identity provider with a `facebook` alias. If this provider does not exist, the login form is displayed. -If you are using the `keycloak.js` adapter, you can also achieve the same behavior as follows: +If you are using the JavaScript adapter, you can also achieve the same behavior as follows: [source,javascript] ---- diff --git a/docs/documentation/upgrading/topics/upgrade_adapters.adoc b/docs/documentation/upgrading/topics/upgrade_adapters.adoc index 7f7be9b09a..0a82495c33 100644 --- a/docs/documentation/upgrading/topics/upgrade_adapters.adoc +++ b/docs/documentation/upgrading/topics/upgrade_adapters.adoc @@ -29,12 +29,11 @@ To upgrade the {appserver_name} adapter, complete the following steps: [[_upgrade_js_adapter]] == Upgrading the JavaScript adapter -To upgrade a JavaScript adapter that has been copied to your web application, perform the following procedure. +To upgrade a JavaScript adapter, install the latest version https://www.npmjs.com/package/keycloak-js[from NPM]. .Procedure +. `npm install keycloak-js@latest` -. Download the new adapter archive. -. Overwrite the `keycloak.js` file in your application with the `keycloak.js` file from the downloaded archive. [[_upgrade_nodejs_adapter]] == Upgrading the `Node.js` adapter diff --git a/docs/guides/securing-apps/javascript-adapter.adoc b/docs/guides/securing-apps/javascript-adapter.adoc index df4ba8c6f4..8ab30e980b 100644 --- a/docs/guides/securing-apps/javascript-adapter.adoc +++ b/docs/guides/securing-apps/javascript-adapter.adoc @@ -10,15 +10,13 @@ summary="Client-side JavaScript library that can be used to secure web applicati == Installation -The adapter is distributed in several ways, but we recommend that you install the https://www.npmjs.com/package/keycloak-js[`keycloak-js`] package from NPM: +We recommend that you install the https://www.npmjs.com/package/keycloak-js[`keycloak-js`] package from NPM: [source,bash] ---- npm install keycloak-js ---- -Alternatively, the library can be retrieved directly from the {project_name} server at `{kc_js_path}/keycloak.js` and is also distributed as a ZIP archive. We are however considering the inclusion of the adapter directly from the Keycloak server as deprecated, and this functionality might be removed in the future. - == {project_name} server configuration One important thing to consider about using client-side applications is that the client has to be a public client as there is no secure way to store client credentials in a client-side application. This consideration makes it very important to make sure the redirect URIs you have configured for the client are correct and as specific as possible. diff --git a/docs/guides/server/reverseproxy.adoc b/docs/guides/server/reverseproxy.adoc index e0b9806176..3fc23ed288 100644 --- a/docs/guides/server/reverseproxy.adoc +++ b/docs/guides/server/reverseproxy.adoc @@ -94,11 +94,6 @@ The following table shows the recommended paths to expose. |No |Exposed admin paths lead to an unnecessary attack vector. -|/js/ -| - -|Yes (see note below) -|Access to keycloak.js needed for "internal" clients, e.g. the account console - |/realms/ |/realms/ |Yes @@ -126,9 +121,6 @@ The following table shows the recommended paths to expose. |=== -[NOTE] -As it's true that the `js` path is needed for internal clients like the account console, it's good practice to use `keycloak.js` from a JavaScript package manager like npm or yarn for your external clients. - We assume you run {project_name} on the root path `/` on your reverse proxy/gateway's public API. If not, prefix the path with your desired one.