commit
0ff992e04e
8 changed files with 275 additions and 36 deletions
|
@ -14,6 +14,13 @@
|
|||
</includes>
|
||||
<outputDirectory></outputDirectory>
|
||||
</fileSet>
|
||||
<fileSet>
|
||||
<directory>.</directory>
|
||||
<includes>
|
||||
<include>index.html</include>
|
||||
</includes>
|
||||
<outputDirectory>docs</outputDirectory>
|
||||
</fileSet>
|
||||
<fileSet>
|
||||
<directory>../../target/site/apidocs</directory>
|
||||
<outputDirectory>docs/javadocs</outputDirectory>
|
||||
|
|
8
distribution/examples-docs-zip/index.html
Executable file
8
distribution/examples-docs-zip/index.html
Executable file
|
@ -0,0 +1,8 @@
|
|||
<h1>Keyloak Documentation</h1>
|
||||
<ul>
|
||||
<li><a href="userguide/html/index.html">Userguide HTML</a></li>
|
||||
<li><a href="userguide/html_single/index.html">Userguide HTML Single Page</a></li>
|
||||
<li><a href="userguide/pdf/keycloak-reference-guide-en-US.pdf">Userguide PDF</a></li>
|
||||
<li><a href="rest-api/overview-index.html">Admin REST API</a></li>
|
||||
<li><a href="javadocs/index.html">Javadocs</a></li>
|
||||
</ul>
|
|
@ -7,6 +7,7 @@
|
|||
<!ENTITY OpenShift SYSTEM "modules/openshift.xml">
|
||||
<!ENTITY AdminPermissions SYSTEM "modules/admin-permissions.xml">
|
||||
<!ENTITY PerRealmAdminPermissions SYSTEM "modules/per-realm-admin-permissions.xml">
|
||||
<!ENTITY AccessTypes SYSTEM "modules/access-types.xml">
|
||||
<!ENTITY AdapterConfig SYSTEM "modules/adapter-config.xml">
|
||||
<!ENTITY JBossAdapter SYSTEM "modules/jboss-adapter.xml">
|
||||
<!ENTITY JavascriptAdapter SYSTEM "modules/javascript-adapter.xml">
|
||||
|
@ -21,9 +22,11 @@
|
|||
<!ENTITY Migration SYSTEM "modules/MigrationFromOlderVersions.xml">
|
||||
<!ENTITY Email SYSTEM "modules/email.xml">
|
||||
<!ENTITY Roles SYSTEM "modules/roles.xml">
|
||||
<!ENTITY DirectAccess SYSTEM "modules/direct-access.xml">
|
||||
<!ENTITY CORS SYSTEM "modules/cors.xml">
|
||||
<!ENTITY Timeouts SYSTEM "modules/timeouts.xml">
|
||||
<!ENTITY Audit SYSTEM "modules/audit.xml">
|
||||
<!ENTITY AdminApi SYSTEM "modules/admin-rest-api.xml">
|
||||
<!ENTITY Authentication SYSTEM "modules/authentication-spi.xml">
|
||||
<!ENTITY Ldap SYSTEM "modules/ldap.xml">
|
||||
<!ENTITY ExportImport SYSTEM "modules/export-import.xml">
|
||||
|
@ -104,9 +107,12 @@ This one is short
|
|||
</para>
|
||||
&Email;
|
||||
</chapter>
|
||||
&AccessTypes;
|
||||
&Roles;
|
||||
&DirectAccess;
|
||||
&CORS;
|
||||
&Timeouts;
|
||||
&AdminApi;
|
||||
&Audit;
|
||||
&Authentication;
|
||||
&Ldap;
|
||||
|
|
|
@ -22,6 +22,10 @@
|
|||
<listitem>
|
||||
JavaScript adapter has been refactored. See the <link linkend='javascript-adapter'>JavaScript adapter</link> section for more details.
|
||||
</listitem>
|
||||
<listitem>
|
||||
The "Central Login Lifespan" setting no longer exists. Please see the <link linkend='session-timeouts'>Session Timeout</link> section
|
||||
for me details.
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
</sect1>
|
||||
<sect1>
|
||||
|
|
54
docbook/reference/en/en-US/modules/access-types.xml
Executable file
54
docbook/reference/en/en-US/modules/access-types.xml
Executable file
|
@ -0,0 +1,54 @@
|
|||
<chapter id="access-types">
|
||||
<title>Application and Client Access Types</title>
|
||||
<para>
|
||||
When you create an Application or OAuth Client you may be wondering what the "Access Types" are.
|
||||
</para>
|
||||
<para>
|
||||
<variablelist>
|
||||
<varlistentry>
|
||||
<term>confidential</term>
|
||||
<listitem>
|
||||
<para>
|
||||
Confidential access type is for clients that need to perform a browser login and that you want
|
||||
to require a client secret when they turn an access code into an access token, (see
|
||||
<ulink url="http://tools.ietf.org/html/rfc6749#section-4.1.3">Access Token Request</ulink> in
|
||||
the OAuth 2.0 spec for more details). The advantages of this is that it is a little extra security.
|
||||
Since Keycloak requires you to register valid redirect-uris, I'm not exactly sure what this little
|
||||
extra security is though. :)
|
||||
The disadvantages of this access type is that confidential access type is pointless for pure
|
||||
Javascript clients as anybody could easily figure out your client's secret!
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term>public</term>
|
||||
<listitem>
|
||||
<para>
|
||||
Public access type is for clients that need to perform a browser login and that you feel
|
||||
that the added extra security of confidential access type is not needed. FYI, Pure javascript
|
||||
clients are by nature public.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term>bearer-only</term>
|
||||
<listitem>
|
||||
<para>
|
||||
Bearer-only access type means that the application only allows bearer token requests. If this
|
||||
is turned on, this application cannot participate in browser logins.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term>direct access only</term>
|
||||
<listitem>
|
||||
<para>
|
||||
For OAuth clients, you would also see a "Direct Access Only" switch when creating the OAuth Client.
|
||||
This switch is for oauth clients that only use the <link linkend='direct-access-grant'>Direct Access Grant</link>
|
||||
protocol to obtain access tokens.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
</variablelist>
|
||||
</para>
|
||||
</chapter>
|
17
docbook/reference/en/en-US/modules/admin-rest-api.xml
Executable file
17
docbook/reference/en/en-US/modules/admin-rest-api.xml
Executable file
|
@ -0,0 +1,17 @@
|
|||
<chapter id="admin-rest-api">
|
||||
<title>Admin REST API</title>
|
||||
<para>
|
||||
The Keycloak Admin Console is implemented entirely with a fully functional REST admin API. You can invoke this
|
||||
REST API from your Java applications by obtaining an access token. You must have the appropriate
|
||||
permissions set up as describe in <xref linkend="admin-permissions" /> and <xref linkend="per-realm-admin-permissions" />
|
||||
</para>
|
||||
<para>
|
||||
The documentation for this REST API is auto-generated and is contained in the distribution of keycloak under
|
||||
the docs/rest-api/overview-index.html directory, or directly from the docs page at the keycloak website.
|
||||
</para>
|
||||
<para>
|
||||
There are a number of examples that come with the keycloak distribution that show you how to invoke on this REST API.
|
||||
<literal>examples/preconfigured-demo/admin-access-app</literal> shows you how to access this api from java.
|
||||
<literal>examples/cors/angular-product-app</literal> shows you how to invoke on it from Javascript.
|
||||
</para>
|
||||
</chapter>
|
128
docbook/reference/en/en-US/modules/direct-access.xml
Executable file
128
docbook/reference/en/en-US/modules/direct-access.xml
Executable file
|
@ -0,0 +1,128 @@
|
|||
<chapter id="direct-access-grants">
|
||||
<title>Direct Access Grants</title>
|
||||
<para>
|
||||
Keycloak allows you to make direct REST invocations to obtain an access token.
|
||||
(See <ulink url="http://tools.ietf.org/html/rfc6749#section-4.3">Resource Owner Password Credentials Grant</ulink>
|
||||
from OAuth 2.0 spec). To use it, Direct Access Grants must be allowed by your realm. This is a configuration switch
|
||||
in the admin console under Settings->General, specifically the "Direct Grant API" switch. You must also have
|
||||
registered a valid OAuth Client or Application to use as the "client_id" for this grant request.
|
||||
</para>
|
||||
<warning>
|
||||
<para>
|
||||
It is highly recommended that you do not use Direct Access Grants to write your own login pages for your application.
|
||||
You will lose a lot of features that Keycloak has if you do this. Specifically all the account management, remember me,
|
||||
lost password, account reset features of Keycloak. Instead, if you want to tailor the look and feel of Keycloak login
|
||||
pages, you should create your own <link linkend="themes">theme</link>.
|
||||
</para>
|
||||
<para>
|
||||
It is even highly recommended that you use the browser to log in for native mobile applications! Android
|
||||
and iPhone applications allow you to redirect to and from the browser. You can use this to redirect the user
|
||||
from your native mobile app to the web browser to perform login, then the browser will redirect back to your
|
||||
native application.
|
||||
</para>
|
||||
</warning>
|
||||
|
||||
|
||||
<para>
|
||||
The REST URL to invoke on is <literal>/{keycloak-root}/realms/{realm-name}/tokens/grants/access</literal>.
|
||||
Invoking on this URL is a POST request and requires you to post the username and credentials of the user you want
|
||||
an access token for. You must also pass along the "client_id" of the application or oauth client you are creating
|
||||
an access token for. This "client_id" is the application or oauth client name (not it's id!). Depending on
|
||||
whether your application/oauth client is <link linkend='access-types'>"public" or "confidential"</link>, you may also have to pass along
|
||||
it's client secret as well.
|
||||
</para>
|
||||
<para>
|
||||
For public applications or oauth client's, the POST invocation requires form parameters that contain the username,
|
||||
credentials, and client_id of your application. For example:
|
||||
<programlisting><![CDATA[
|
||||
POST /auth/realms/demo/tokens/grants/access
|
||||
Content-Type: application/x-www-form-urlencoded
|
||||
|
||||
username=bburke&password=geheim&client_id=customer-portal]]>
|
||||
</programlisting>
|
||||
The response would be this <ulink url="http://tools.ietf.org/html/rfc6749#section-4.3.3">standard JSON document</ulink> from the OAuth 2.0 specification.
|
||||
<programlisting><![CDATA[
|
||||
HTTP/1.1 200 OK
|
||||
Content-Type: application/json;charset=UTF-8
|
||||
Cache-Control: no-store
|
||||
Pragma: no-cache
|
||||
|
||||
{
|
||||
"access_token":"2YotnFZFEjr1zCsicMWpAA",
|
||||
"token_type":"bearer",
|
||||
"expires_in":3600,
|
||||
"refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA",
|
||||
"id_token":"tGzv3JOkF0XG5Qx2TlKWIA",
|
||||
"session-state":"234234-234234-234234"
|
||||
}]]>
|
||||
</programlisting>
|
||||
</para>
|
||||
<para>
|
||||
For confidential applications or oauth client's, you must create a Basic Auth <literal>Authorization</literal>
|
||||
header that contains the client_id and client secret. And pass in the form parameters for username and for
|
||||
each user credential. For example:
|
||||
<programlisting><![CDATA[
|
||||
POST /auth/realms/demo/tokens/grants/access
|
||||
Authorization: Basic atasdf023l2312023
|
||||
Content-Type: application/x-www-form-urlencoded
|
||||
|
||||
username=bburke&password=geheim]]>
|
||||
</programlisting>
|
||||
|
||||
</para>
|
||||
<para>
|
||||
Here's a Java example using Apache HTTP Client and some Keycloak utility classes.:
|
||||
<programlisting><![CDATA[
|
||||
HttpClient client = new HttpClientBuilder()
|
||||
.disableTrustManager().build();
|
||||
|
||||
|
||||
try {
|
||||
HttpPost post = new HttpPost(
|
||||
KeycloakUriBuilder.fromUri("http://localhost:8080/auth")
|
||||
.path(ServiceUrlConstants.TOKEN_SERVICE_DIRECT_GRANT_PATH).build("demo"));
|
||||
List <NameValuePair> formparams = new ArrayList <NameValuePair>();
|
||||
formparams.add(new BasicNameValuePair("username", "bburke"));
|
||||
formparams.add(new BasicNameValuePair("password", "password"));
|
||||
|
||||
if (isPublic()) { // if client is public access type
|
||||
formparams.add(new BasicNameValuePair(OAuth2Constants.CLIENT_ID, "customer-portal"));
|
||||
} else {
|
||||
String authorization = BasicAuthHelper.createHeader("customer-portal", "secret-secret-secret);
|
||||
post.setHeader("Authorization", authorization);
|
||||
}
|
||||
UrlEncodedFormEntity form = new UrlEncodedFormEntity(formparams, "UTF-8");
|
||||
post.setEntity(form);
|
||||
|
||||
HttpResponse response = client.execute(post);
|
||||
int status = response.getStatusLine().getStatusCode();
|
||||
HttpEntity entity = response.getEntity();
|
||||
if (status != 200) {
|
||||
throw new IOException("Bad status: " + status);
|
||||
}
|
||||
if (entity == null) {
|
||||
throw new IOException("No Entity");
|
||||
}
|
||||
InputStream is = entity.getContent();
|
||||
try {
|
||||
AccessTokenResponse tokenResponse = JsonSerialization.readValue(is, AccessTokenResponse.class);
|
||||
} finally {
|
||||
try {
|
||||
is.close();
|
||||
} catch (IOException ignored) { }
|
||||
}
|
||||
} finally {
|
||||
client.getConnectionManager().shutdown();
|
||||
}
|
||||
]]>
|
||||
|
||||
</programlisting>
|
||||
</para>
|
||||
<para>
|
||||
Once you have the access token string, you can use it in REST HTTP bearer token authorized requests, i.e
|
||||
<programlisting>
|
||||
GET /my/rest/api
|
||||
Authorization: Bearer 2YotnFZFEjr1zCsicMWpAA
|
||||
</programlisting>
|
||||
</para>
|
||||
</chapter>
|
|
@ -1,40 +1,55 @@
|
|||
<chapter id="timeouts">
|
||||
<title>Cookie Timeouts and Token Lifespans</title>
|
||||
<title>Cookie settings, Session Timeouts, and Token Lifespans</title>
|
||||
<para>
|
||||
If you go to the Settings->Token page of the Keycloak adminstration console there is a bunch of fine tuning
|
||||
you can do as far as login session timeouts go.
|
||||
</para>
|
||||
<para>
|
||||
If you turn on the <literal>Remember Me</literal> switch in the admin console, your login pages will show a
|
||||
"Remember Me" checkbox. This will set the central login SSO cookie to be a persistent cookie rather than a session
|
||||
cookie. So, if you close your browser, you may still be logged in if you've checked the "Remember Me" checkbox.
|
||||
</para>
|
||||
<para>
|
||||
The <literal>Central Login Lifespan</literal> sets how long a central login is valid for. When you are redirected
|
||||
to the Keycloak Server for authentication, and you have already logged in, the Keycloak Server will refresh the
|
||||
cookie used to remember you by between visits. So, the lifespan time is reset. If you have "Remember Me"
|
||||
set up, you may want to set this lifespan to be days, weeks, or even months. Usually though you want it long
|
||||
enough so users can browser various applications that are secured centrally by keycloak in one login session.
|
||||
</para>
|
||||
<para>
|
||||
The <literal>Access Token Lifespan</literal> is how long an access token is valid for. An access token contains everything
|
||||
an application needs to authorize a client. It contains roles allowed as well as other user information. When
|
||||
an access token expires, your application will attempt to refresh it using a refresh token that it obtained in the
|
||||
initial login. The value of this configuration option should be however long you feel comfortable with the
|
||||
application not knowing if the user's permissions have changed. This value is usually in minutes or hours.
|
||||
</para>
|
||||
<para>
|
||||
The <literal>Refresh Token Lifespan</literal> is how long a refresh token is valid for. The value of this is relative
|
||||
to how comfortable you feel with how long you want an application's session to be valid. This value is usually
|
||||
measured in minutes or hours and should be longer than the Access Token Lifespan.
|
||||
</para>
|
||||
<para>
|
||||
The <literal>Access Code Lifespan</literal> is how long an access code is valid for. An access code is obtained
|
||||
on the 1st leg of the OAuth 2.0 redirection protocol. This should be a short time limit. Usually seconds.
|
||||
</para>
|
||||
<para>
|
||||
The <literal>Access Code Action Lifespan</literal> is how long a user is allowed to attempt a login. When a user tries
|
||||
to login, they may have to change their password, set up TOTP, or perform some other action before they are redirected
|
||||
back to your application as an authentnicated user. This value is relatively short and is usually measured in minutes.
|
||||
Keycloak has a bunch of fine-grain settings to manage browser cookies, user login sessions, and token lifespans.
|
||||
Sessions can be viewed and managed within the admin console for all users, and individually in the user's account
|
||||
management pages. This chapter goes over configuration options for cookies, sessions, and tokens.
|
||||
</para>
|
||||
<section>
|
||||
<title>Remember Me</title>
|
||||
<para>
|
||||
If you go to the admin console page of Settings->General, you should see a <literal>Remember Me</literal> on/off switch.
|
||||
Your realm sets a SSO cookie so that you only have to enter in your login credentials once.
|
||||
This <literal>Remember Me</literal> admin config option, when turned on, will show a "Remember Me" checkbox on the user's login page.
|
||||
If the user clicks this, the realm's SSO. cookie will be persistent. This means that if the user closes their browser
|
||||
they will still be logged in the next time they start up their browser.
|
||||
</para>
|
||||
</section>
|
||||
<section id="session-timeouts">
|
||||
<title>Session Timeouts</title>
|
||||
<para>
|
||||
If you go to the Sesions and Tokens->Token Settings page of the Keycloak adminstration console there is a bunch of fine tuning
|
||||
you can do as far as login session timeouts go.
|
||||
</para>
|
||||
<para>
|
||||
The <literal>SSO Session Idle Timeout</literal> is the idle time of a user session. If there is no activity
|
||||
in the user's session for this amount of time, the user session will be destroyed, and the user will become logged
|
||||
out. The idle time is refreshed with every action against the keycloak server for that session, i.e.: a user login,
|
||||
SSO, a refresh token grant, etc.
|
||||
</para>
|
||||
<para>
|
||||
The <literal>SSO Session Max Lifespan</literal> setting is the maximum time a user session is allowed to be alive. This
|
||||
max lifespan countdown starts from when the user first logs in and is never refreshed. This works great with <literal>Remember Me</literal>
|
||||
in that it allow you to force a relogin after a set timeframe.
|
||||
</para>
|
||||
</section>
|
||||
<section>
|
||||
<title>Token Timeouts</title>
|
||||
<para>
|
||||
The <literal>Access Token Lifespan</literal> is how long an access token is valid for. An access token contains everything
|
||||
an application needs to authorize a client. It contains roles allowed as well as other user information. When
|
||||
an access token expires, your application will attempt to refresh it using a refresh token that it obtained in the
|
||||
initial login. The value of this configuration option should be however long you feel comfortable with the
|
||||
application not knowing if the user's permissions have changed. This value is usually in minutes.
|
||||
</para>
|
||||
<para>
|
||||
The <literal>Access Code Lifespan</literal> is how long an access code is valid for. An access code is obtained
|
||||
on the 1st leg of the OAuth 2.0 redirection protocol. This should be a short time limit. Usually seconds.
|
||||
</para>
|
||||
<para>
|
||||
The <literal>Access Code Action Lifespan</literal> is how long a user is allowed to attempt a login. When a user tries
|
||||
to login, they may have to change their password, set up TOTP, or perform some other action before they are redirected
|
||||
back to your application as an authentnicated user. This value is relatively short and is usually measured in minutes.
|
||||
</para>
|
||||
</section>
|
||||
</chapter>
|
Loading…
Reference in a new issue