Remove references of statically served Keycloak JS from documentation

Closes #32821

Signed-off-by: Jon Koops <jonkoops@gmail.com>
This commit is contained in:
Jon Koops 2024-09-11 17:46:04 +02:00 committed by Marek Posolda
parent cafc905a1e
commit 188893222f
5 changed files with 34 additions and 35 deletions

View file

@ -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. 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. 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]
---- ----
<script src="http://...{kc_js_path}/keycloak-authz.js"></script> npm install keycloak-js
---- ----
Next, you can create a `KeycloakAuthorization` instance as follows: Next, you can create a `KeycloakAuthorization` instance as follows:
[source,javascript] [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); 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. * 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] [source,javascript]
---- ----
// prepare a authorization request with the permission ticket // prepare a authorization request with the permission ticket
const authorizationRequest = {}; const authorizationRequest = { ticket };
authorizationRequest.ticket = ticket;
// send the authorization request, if successful retry the request // send the authorization request, if successful retry the request
Identity.authorization.authorize(authorizationRequest).then(function (rpt) { authorization.authorize(authorizationRequest).then((rpt) => {
// onGrant // onGrant
}, function () { }, () => {
// onDeny // onDeny
}, function () { }, () => {
// onError // onError
}); });
---- ----
@ -71,13 +81,13 @@ Most applications should use the `onGrant` callback to retry a request after a 4
== Obtaining entitlements == 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. 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 .Example about how to obtain an RPT with permissions for all resources and scopes the user can access
[source,javascript] [source,javascript]
---- ----
authorization.entitlement('my-resource-server-id').then(function (rpt) { authorization.entitlement("my-resource-server-id").then((rpt) => {
// onGrant callback function. // onGrant callback function.
// If authorization was successful you'll receive an RPT // If authorization was successful you'll receive an RPT
// with the necessary permissions to access the resource server // 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 .Example about how to obtain an RPT with permissions for specific resources and scopes
[source,javascript] [source,javascript]
---- ----
authorization.entitlement('my-resource-server', { authorization.entitlement("my-resource-server", {
"permissions": [ permissions: [
{ {
"id" : "Some Resource" id: "Some Resource"
} }
] ]
}).then(function (rpt) { }).then((rpt) => {
// onGrant // onGrant
}); });
---- ----
@ -108,7 +118,7 @@ The `entitlement` function is completely asynchronous and supports a few callbac
== Authorization request == 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: properties:
* *permissions* * *permissions*
@ -118,10 +128,10 @@ An array of objects representing the resource and scopes. For instance:
[source,javascript] [source,javascript]
---- ----
const authorizationRequest = { const authorizationRequest = {
"permissions": [ permissions: [
{ {
"id" : "Some Resource", id: "Some Resource",
"scopes" : ["view", "edit"] scopes: ["view", "edit"]
} }
] ]
} }

View file

@ -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. 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] [source,javascript]
---- ----

View file

@ -29,12 +29,11 @@ To upgrade the {appserver_name} adapter, complete the following steps:
[[_upgrade_js_adapter]] [[_upgrade_js_adapter]]
== Upgrading the JavaScript 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 .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]] [[_upgrade_nodejs_adapter]]
== Upgrading the `Node.js` adapter == Upgrading the `Node.js` adapter

View file

@ -10,15 +10,13 @@ summary="Client-side JavaScript library that can be used to secure web applicati
== Installation == 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] [source,bash]
---- ----
npm install keycloak-js 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 == {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. 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.

View file

@ -94,11 +94,6 @@ The following table shows the recommended paths to expose.
|No |No
|Exposed admin paths lead to an unnecessary attack vector. |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/
|/realms/ |/realms/
|Yes |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. 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. If not, prefix the path with your desired one.