libre.sh/keycloak-scim
3
0
Fork 0
Code Issues 15 Pull requests Releases Packages Activity Actions

[KEYCLOAK-11436] Update JavaScript adapter documentation to prefer native promises

Browse source
This commit is contained in:
Jon Koops 2019-10-05 16:53:12 +02:00 committed by Stian Thorgersen
parent 77d4447d18
commit cd7309ddaf
1 changed files with 69 additions and 32 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

81
securing_apps/topics/oidc/javascript-adapter.adoc
View file

@ -27,10 +27,10 @@ The following example shows how to initialize the JavaScript adapter:
<head> <head>
<script src="keycloak.js"></script> <script src="keycloak.js"></script>
<script> <script>
var keycloak = Keycloak(); var keycloak = new Keycloak();
keycloak.init().success(function(authenticated) { keycloak.init({ promiseType: 'native' }).then(function(authenticated) {
alert(authenticated ? 'authenticated' : 'not authenticated'); alert(authenticated ? 'authenticated' : 'not authenticated');
}).error(function() { }).catch(function() {
alert('failed to initialize'); alert('failed to initialize');
}); });
</script> </script>
@ -41,14 +41,14 @@ If the `keycloak.json` file is in a different location you can specify it:
[source,javascript] [source,javascript]
---- ----
var keycloak = Keycloak('http://localhost:8080/myapp/keycloak.json'); var keycloak = new Keycloak('http://localhost:8080/myapp/keycloak.json');
---- ----
Alternatively, you can pass in a JavaScript object with the required configuration instead: Alternatively, you can pass in a JavaScript object with the required configuration instead:
[source,javascript] [source,javascript]
---- ----
var keycloak = Keycloak({ var keycloak = new Keycloak({
url: 'http://keycloak-server/auth', url: 'http://keycloak-server/auth',
realm: 'myrealm', realm: 'myrealm',
clientId: 'myapp' clientId: 'myapp'
@ -69,7 +69,11 @@ This URI needs to be a valid endpoint in the application (and of course it must
[source,javascript] [source,javascript]
---- ----
keycloak.init({ onLoad: 'check-sso', silentCheckSsoRedirectUri: window.location.origin + '/silent-check-sso.html'}) keycloak.init({
onLoad: 'check-sso',
silentCheckSsoRedirectUri: window.location.origin + '/silent-check-sso.html',
promiseType: 'native',
})
---- ----
The page at the silent check-sso redirect uri is loaded in the iframe after successfully checking your authentication state and retrieving the tokens from the {project_name} server. The page at the silent check-sso redirect uri is loaded in the iframe after successfully checking your authentication state and retrieving the tokens from the {project_name} server.
@ -93,7 +97,10 @@ To enable `login-required` set `onLoad` to `login-required` and pass to the init
[source,javascript] [source,javascript]
---- ----
keycloak.init({ onLoad: 'login-required' }) keycloak.init({
onLoad: 'login-required',
promiseType: 'native',
})
---- ----
After the user is authenticated the application can make requests to RESTful services secured by {project_name} by including the bearer token in the After the user is authenticated the application can make requests to RESTful services secured by {project_name} by including the bearer token in the
@ -126,14 +133,14 @@ var loadData = function () {
---- ----
One thing to keep in mind is that the access token by default has a short life expiration so you may need to refresh the access token prior to sending the One thing to keep in mind is that the access token by default has a short life expiration so you may need to refresh the access token prior to sending the
request. You can do this by the `updateToken` method. The `updateToken` method returns a promise object which makes it easy to invoke the service only if the request. You can do this by the `updateToken` method. The `updateToken` method returns a promise which makes it easy to invoke the service only if the
token was successfully refreshed and for example display an error to the user if it wasn't. For example: token was successfully refreshed and display an error to the user if it wasn't. For example:
[source,javascript] [source,javascript]
---- ----
keycloak.updateToken(30).success(function() { keycloak.updateToken(30).then(function() {
loadData(); loadData();
}).error(function() { }).catch(function() {
alert('Failed to refresh token'); alert('Failed to refresh token');
}); });
---- ----
@ -167,7 +174,10 @@ You also need to pass the parameter `flow` with value `implicit` to `init` metho
[source,javascript] [source,javascript]
---- ----
keycloak.init({ flow: 'implicit' }) keycloak.init({
flow: 'implicit',
promiseType: 'native',
})
---- ----
One thing to note is that only an access token is provided and there is no refresh token. This means that once the access token has expired the application One thing to note is that only an access token is provided and there is no refresh token. This means that once the access token has expired the application
@ -187,7 +197,10 @@ For the Hybrid flow, you need to pass the parameter `flow` with value `hybrid` t
[source,javascript] [source,javascript]
---- ----
keycloak.init({ flow: 'hybrid' }) keycloak.init({
flow: 'hybrid',
promiseType: 'native',
})
---- ----
[#hybrid-apps-with-cordova] [#hybrid-apps-with-cordova]
@ -215,7 +228,10 @@ You can activate the native mode by passing the adapter type `cordova-native` to
[source,javascript] [source,javascript]
---- ----
keycloak.init({ adapter: 'cordova-native' }) keycloak.init({
adapter: 'cordova-native',
promiseType: 'native',
})
---- ----
This adapter required two additional plugins: This adapter required two additional plugins:
@ -254,6 +270,27 @@ Example polyfill libraries:
* HTML5 History - https://github.com/devote/HTML5-History-API * HTML5 History - https://github.com/devote/HTML5-History-API
* Promise - https://github.com/stefanpenner/es6-promise * Promise - https://github.com/stefanpenner/es6-promise
==== A note about `promiseType`
Throughout the examples in the documentation you will find `promiseType: 'native'` specified wherever {project_name} is initialized.
Historically {project_name} has used its own implementation of promises that is not compatible with native promises as provided by the browser.
By default {project_name}'s own promise implementation (also known as `promiseType: 'legacy'`) will be used if no promise type is specified.
In future versions of {project_name} the default promise type will change from `legacy` to `native`. Eventually, support for legacy promises will be removed entirely. It is therefore highly recommended that you always specify `promiseType: 'native'` to future-proof your code.
==== Native promises and TypeScript
If you want to use native promises and get correct type information when using TypeScript you will have to specify the `promiseType` when constructing a new instance of Keycloak.
[source,javascript]
----
// Typescript assumes this is a 'legacy' promise, all methods return .success() and .error()
const keycloak = new Keycloak();
// Typescript assumes this is a native promise, all methods return standard promises
const keycloak = new Keycloak<'native'>();
----
==== JavaScript Adapter Reference ==== JavaScript Adapter Reference
===== Constructor ===== Constructor
@ -345,7 +382,7 @@ Options is an Object, where:
* promiseType - If set to `native` all methods returning a promise will return a native JavaScript promise. If not set will return Keycloak specific promise objects. * promiseType - If set to `native` all methods returning a promise will return a native JavaScript promise. If not set will return Keycloak specific promise objects.
* enableLogging - Enables logging messages from Keycloak to the console (default is false). * enableLogging - Enables logging messages from Keycloak to the console (default is false).
Returns promise to set functions to be invoked on success or error. Returns a promise that resolves when initialization completes.
====== login(options) ====== login(options)
@ -424,16 +461,15 @@ Returns true if the token has the given role for the resource (resource is optio
Loads the users profile. Loads the users profile.
Returns promise to set functions to be invoked if the profile was loaded successfully, or if the profile could not be Returns a promise that resolves with the profile.
loaded.
For example: For example:
[source,javascript] [source,javascript]
---- ----
keycloak.loadUserProfile().success(function(profile) { keycloak.loadUserProfile().then(function(profile) {
alert(JSON.stringify(profile, null, " ")); alert(JSON.stringify(profile, null, " "));
}).error(function() { }).catch(function() {
alert('Failed to load user profile'); alert('Failed to load user profile');
}); });
---- ----
@ -447,18 +483,19 @@ Returns true if the token has less than minValidity seconds left before it expir
If the token expires within minValidity seconds (minValidity is optional, if not specified 5 is used) the token is refreshed. If the token expires within minValidity seconds (minValidity is optional, if not specified 5 is used) the token is refreshed.
If the session status iframe is enabled, the session status is also checked. If the session status iframe is enabled, the session status is also checked.
Returns promise to set functions that can be invoked if the token is still valid, or if the token is no longer valid. Returns a promise that resolves with a boolean indicating whether or not the token has been refreshed.
For example: For example:
[source,javascript] [source,javascript]
---- ----
keycloak.updateToken(5).success(function(refreshed) { keycloak.updateToken(5).then(function(refreshed) {
if (refreshed) { if (refreshed) {
alert('Token was successfully refreshed'); alert('Token was successfully refreshed');
} else { } else {
alert('Token is still valid'); alert('Token is still valid');
} }
}).error(function() { }).catch(function() {
alert('Failed to refresh the token, or the session has expired'); alert('Failed to refresh the token, or the session has expired');
}); });
---- ----