194 lines
No EOL
10 KiB
XML
Executable file
194 lines
No EOL
10 KiB
XML
Executable file
<section>
|
|
<title>Pure Client Javascript Adapter</title>
|
|
<para>
|
|
The Keycloak Server comes with a Javascript library you can use to secure pure HTML/Javascript applications. It
|
|
works in the same way as other application adapters except that your browser is driving the OAuth redirect protocol
|
|
rather than the server.
|
|
</para>
|
|
<para>
|
|
The
|
|
disadvantage of using this approach is that you end up having a non-confidential, public client. This can be mitigated
|
|
by registering valid redirect URLs. You are still vulnerable if somebody hijacks the IP/DNS name of your pure
|
|
HTML/Javascript application though.
|
|
</para>
|
|
<para>
|
|
To use this adapter, you must first configure an application (or client) through the <literal>Keycloak Admin Console</literal>.
|
|
You should select <literal>public</literal> for the <literal>Client Type</literal> field. As public clients can't
|
|
be verified with a client secret you are required to configure one or more valid redirect uris as well.
|
|
Once you've configured the application click on the <literal>Installation</literal> tab and download the <literal>keycloak.json</literal>
|
|
file. This file should be hosted in your web-server at the same root as your HTML pages. Alternatively you can either
|
|
specify the URL for this file, or manually configure the adapter.
|
|
</para>
|
|
<para>
|
|
Next you have to initialize the adapter in your application. An example on how to do this is shown below.
|
|
<programlisting><![CDATA[
|
|
<head>
|
|
<script src="http://<keycloak server>/auth/js/keycloak.js"></script>
|
|
<script>
|
|
var keycloak = Keycloak();
|
|
keycloak.init().success(function(authenticated) {
|
|
alert(authenticated ? 'authenticated' : 'not authenticated');
|
|
}).error(function() {
|
|
alert('failed to initialize');
|
|
});
|
|
</script>
|
|
</head>
|
|
]]></programlisting>
|
|
To specify the location of the keycloak.json file:
|
|
<programlisting><![CDATA[
|
|
var keycloak = Keycloak('http://localhost:8080/myapp/keycloak.json'));
|
|
]]></programlisting>
|
|
Or finally to manually configure the adapter:
|
|
<programlisting><![CDATA[
|
|
var keycloak = Keycloak({
|
|
url: 'http://keycloak-server/auth',
|
|
realm: 'myrealm',
|
|
clientId: 'myapp'
|
|
});
|
|
]]></programlisting>
|
|
You can also pass <literal>login-required</literal> or <literal>check-sso</literal> to the init function. Login
|
|
required will redirect to the login form on the server, while check-sso will redirect to the auth server to check
|
|
if the user is already logged in to the realm. For example:
|
|
<programlisting><![CDATA[
|
|
keycloak.init('login-required')
|
|
]]></programlisting>
|
|
</para>
|
|
|
|
<para>
|
|
After you login, your application will be able to make REST calls using bearer token authentication. Here's
|
|
an example pulled from the <literal>customer-portal-js</literal> example that comes with the distribution.
|
|
<programlisting><![CDATA[
|
|
<script>
|
|
var loadData = function () {
|
|
document.getElementById('username').innerText = keycloak.username;
|
|
|
|
var url = 'http://localhost:8080/database/customers';
|
|
|
|
var req = new XMLHttpRequest();
|
|
req.open('GET', url, true);
|
|
req.setRequestHeader('Accept', 'application/json');
|
|
req.setRequestHeader('Authorization', 'Bearer ' + keycloak.token);
|
|
|
|
req.onreadystatechange = function () {
|
|
if (req.readyState == 4) {
|
|
if (req.status == 200) {
|
|
var users = JSON.parse(req.responseText);
|
|
var html = '';
|
|
for (var i = 0; i < users.length; i++) {
|
|
html += '<p>' + users[i] + '</p>';
|
|
}
|
|
document.getElementById('customers').innerHTML = html;
|
|
console.log('finished loading data');
|
|
}
|
|
}
|
|
}
|
|
|
|
req.send();
|
|
};
|
|
|
|
var loadFailure = function () {
|
|
document.getElementById('customers').innerHTML = '<b>Failed to load data. Check console log</b>';
|
|
|
|
};
|
|
|
|
var reloadData = function () {
|
|
keycloak.updateToken().success(loadData).error(loadFailure);
|
|
}
|
|
</script>
|
|
|
|
<button onclick="loadData()">Submit</button>
|
|
]]></programlisting>
|
|
</para>
|
|
<para>
|
|
The <literal>loadData()</literal> method builds an HTTP request setting the <literal>Authorization</literal>
|
|
header to a bearer token. The <literal>keycloak.token</literal> points to the access token the browser obtained
|
|
when it logged you in. The <literal>loadFailure()</literal> method is invoked on a failure. The <literal>reloadData()</literal>
|
|
function calls <literal>keycloak.onValidAccessToken()</literal> passing in the <literal>loadData()</literal> and
|
|
<literal>loadFailure()</literal> callbacks. The <literal>keycloak.onValidAcessToken()</literal> method checks to
|
|
see if the access token hasn't expired. If it hasn't, and your oauth login returned a refresh token, this method
|
|
will refresh the access token. Finally, if successful, it will invoke the success callback, which in this case
|
|
is the <literal>loadData()</literal> method.
|
|
</para>
|
|
|
|
<para>
|
|
To refresh the token if it's expired call the <literal>updateToken</literal> method. This method returns a promise
|
|
object which can be used to invoke a function on success or failure. This method can be used to wrap functions
|
|
that should only be called with a valid token. For example the following method will refresh the token if it
|
|
expires within 30 seconds, and then invoke the specified function. If the token is valid for more than 30 seconds it
|
|
will just call the specified function.
|
|
<programlisting><![CDATA[
|
|
keycloak.updateToken(30).success(function() {
|
|
// send request with valid token
|
|
}).error(function() {
|
|
alert('failed to refresh token');
|
|
);
|
|
]]></programlisting>
|
|
</para>
|
|
|
|
<section>
|
|
<title>JavaScript Adapter reference</title>
|
|
|
|
<section>
|
|
<title>Constructor</title>
|
|
<programlisting><![CDATA[
|
|
new Keycloak();
|
|
new Keycloak('http://localhost/keycloak.json');
|
|
new Keycloak({ url: 'http://localhost/auth', realm: 'myrealm', clientId: 'myApp' });
|
|
]]></programlisting>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Properties</title>
|
|
|
|
<itemizedlist>
|
|
<listitem>authenticated - true if the user is authenticated</listitem>
|
|
<listitem>token - the base64 encoded token that can be sent in the <literal>Authorization</literal> header in requests to services</listitem>
|
|
<listitem>tokenParsed - the parsed token</listitem>
|
|
<listitem>subject - the user id</listitem>
|
|
<listitem>idToken - the id token if claims is enabled for the application, null otherwise</listitem>
|
|
<listitem>realmAccess - the realm roles associated with the token</listitem>
|
|
<listitem>resourceAccess - the resource roles assocaited with the token</listitem>
|
|
<listitem>refreshToken - the base64 encoded token that can be used to retrieve a new token</listitem>
|
|
<listitem>refreshTokenParsed - the parsed refresh token</listitem>
|
|
</itemizedlist>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Methods</title>
|
|
|
|
<itemizedlist>
|
|
<listitem>init - called to initialize the adapter. Returns promise to set functions to be invoked on success or error</listitem>
|
|
<listitem>login(options) - redirects to login form on (options is an optional object with redirectUri and/or prompt fields)</listitem>
|
|
<listitem>createLoginUrl(options) - returns the url to login form on (options is an optional object with redirectUri and/or prompt fields)</listitem>
|
|
<listitem>logout(options) - redirects to logout (options is an optional object with redirectUri)</listitem>
|
|
<listitem>createLogoutUrl(options) - returns the url to logout (options is an optional object with redirectUri)</listitem>
|
|
<listitem>accountManagement - redirects to account management</listitem>
|
|
<listitem>createAccountUrl - returns the url to account management</listitem>
|
|
<listitem>hasRealmRole(role) - returns true if the token has the given realm role</listitem>
|
|
<listitem>hasResourceRole(role, resource) - returns true if the token has the given role for the resource (resource is optional, if not specified clientId is used)</listitem>
|
|
<listitem>loadUserProfile() - loads the users profile. Returns promise to set functions to be invoked on success or error</listitem>
|
|
<listitem>isTokenExpired(minValidity) - returns true if the token has less than minValidity seconds left before it expires (minValidity is optional, if not specified 0 is used)</listitem>
|
|
<listitem>updateToken(minValidity) - refreshes the token if the token expires within minValidity seconds (minValidity is optional, if not specified 0 is used). Returns promise to set functions to be invoked on success or error</listitem>
|
|
</itemizedlist>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Callback Events</title>
|
|
|
|
<para>The adapter supports setting callback listeners for certain events. For example:
|
|
<programlisting><![CDATA[
|
|
keycloak.onAuthSuccess = function() { alert('authenticated'); }
|
|
]]></programlisting>
|
|
</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>onReady(authenticated) - called when the adapter is initialized</listitem>
|
|
<listitem>onAuthSuccess - called when a user is successfully authenticated</listitem>
|
|
<listitem>onAuthError - called if there was an error during authentication</listitem>
|
|
<listitem>onAuthRefreshSuccess - called when the token is refreshed</listitem>
|
|
<listitem>onAuthRefreshError - called if there was an error while trying to refresh the token</listitem>
|
|
<listitem>onAuthLogout - called when the user is logged out (only relevant to Cordova)</listitem>
|
|
</itemizedlist>
|
|
</section>
|
|
</section>
|
|
</section> |