Remove references of statically served Keycloak JS from documentation
Closes #32821 Signed-off-by: Jon Koops <jonkoops@gmail.com>
This commit is contained in:
parent
cafc905a1e
commit
188893222f
5 changed files with 34 additions and 35 deletions
|
@ -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"]
|
||||||
}
|
}
|
||||||
]
|
]
|
||||||
}
|
}
|
||||||
|
|
|
@ -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]
|
||||||
----
|
----
|
||||||
|
|
|
@ -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
|
||||||
|
|
|
@ -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.
|
||||||
|
|
|
@ -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.
|
||||||
|
|
||||||
|
|
Loading…
Reference in a new issue