\ No newline at end of file
diff --git a/docbook/reference/en/en-US/master.xml b/docbook/reference/en/en-US/master.xml
index 56433a168c..4ad402d14e 100755
--- a/docbook/reference/en/en-US/master.xml
+++ b/docbook/reference/en/en-US/master.xml
@@ -7,6 +7,7 @@
+
@@ -21,9 +22,11 @@
+
+
@@ -104,9 +107,12 @@ This one is short
&Email;
+ &AccessTypes;
&Roles;
+ &DirectAccess;
&CORS;
&Timeouts;
+ &AdminApi;
&Audit;
&Authentication;
&Ldap;
diff --git a/docbook/reference/en/en-US/modules/MigrationFromOlderVersions.xml b/docbook/reference/en/en-US/modules/MigrationFromOlderVersions.xml
index 84b5904154..cc713f5690 100755
--- a/docbook/reference/en/en-US/modules/MigrationFromOlderVersions.xml
+++ b/docbook/reference/en/en-US/modules/MigrationFromOlderVersions.xml
@@ -22,6 +22,10 @@
JavaScript adapter has been refactored. See the JavaScript adapter section for more details.
+
+ The "Central Login Lifespan" setting no longer exists. Please see the Session Timeout section
+ for me details.
+
diff --git a/docbook/reference/en/en-US/modules/access-types.xml b/docbook/reference/en/en-US/modules/access-types.xml
new file mode 100755
index 0000000000..7d96dfba24
--- /dev/null
+++ b/docbook/reference/en/en-US/modules/access-types.xml
@@ -0,0 +1,54 @@
+
+ Application and Client Access Types
+
+ When you create an Application or OAuth Client you may be wondering what the "Access Types" are.
+
+
+
+
+ confidential
+
+
+ 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
+ Access Token Request 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!
+
+
+
+
+ public
+
+
+ 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.
+
+
+
+
+ bearer-only
+
+
+ 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.
+
+
+
+
+ direct access only
+
+
+ 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 Direct Access Grant
+ protocol to obtain access tokens.
+
+
+
+
+
+
\ No newline at end of file
diff --git a/docbook/reference/en/en-US/modules/admin-rest-api.xml b/docbook/reference/en/en-US/modules/admin-rest-api.xml
new file mode 100755
index 0000000000..74533cd4b5
--- /dev/null
+++ b/docbook/reference/en/en-US/modules/admin-rest-api.xml
@@ -0,0 +1,17 @@
+
+ Admin REST API
+
+ 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 and
+
+
+ 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.
+
+
+ There are a number of examples that come with the keycloak distribution that show you how to invoke on this REST API.
+ examples/preconfigured-demo/admin-access-app shows you how to access this api from java.
+ examples/cors/angular-product-app shows you how to invoke on it from Javascript.
+
+
\ No newline at end of file
diff --git a/docbook/reference/en/en-US/modules/direct-access.xml b/docbook/reference/en/en-US/modules/direct-access.xml
new file mode 100755
index 0000000000..1074537b27
--- /dev/null
+++ b/docbook/reference/en/en-US/modules/direct-access.xml
@@ -0,0 +1,128 @@
+
+ Direct Access Grants
+
+ Keycloak allows you to make direct REST invocations to obtain an access token.
+ (See Resource Owner Password Credentials Grant
+ 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.
+
+
+
+ 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 theme.
+
+
+ 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.
+
+
+
+
+
+ The REST URL to invoke on is /{keycloak-root}/realms/{realm-name}/tokens/grants/access.
+ 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 "public" or "confidential", you may also have to pass along
+ it's client secret as well.
+
+
+ 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:
+
+
+ The response would be this standard JSON document from the OAuth 2.0 specification.
+
+
+
+
+ For confidential applications or oauth client's, you must create a Basic Auth Authorization
+ header that contains the client_id and client secret. And pass in the form parameters for username and for
+ each user credential. For example:
+
+
+
+
+
+ Here's a Java example using Apache HTTP Client and some Keycloak utility classes.:
+ formparams = new ArrayList ();
+ 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();
+}
+]]>
+
+
+
+
+ Once you have the access token string, you can use it in REST HTTP bearer token authorized requests, i.e
+
+GET /my/rest/api
+Authorization: Bearer 2YotnFZFEjr1zCsicMWpAA
+
+
+
\ No newline at end of file
diff --git a/docbook/reference/en/en-US/modules/timeouts.xml b/docbook/reference/en/en-US/modules/timeouts.xml
index 133707aac2..8a772cc430 100755
--- a/docbook/reference/en/en-US/modules/timeouts.xml
+++ b/docbook/reference/en/en-US/modules/timeouts.xml
@@ -1,40 +1,55 @@
- Cookie Timeouts and Token Lifespans
+ Cookie settings, Session Timeouts, and Token Lifespans
- 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.
-
-
- If you turn on the Remember Me 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.
-
-
- The Central Login Lifespan 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.
-
-
- The Access Token Lifespan 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.
-
-
- The Refresh Token Lifespan 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.
-
-
- The Access Code Lifespan 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.
-
-
- The Access Code Action Lifespan 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.
+
+ Remember Me
+
+ If you go to the admin console page of Settings->General, you should see a Remember Me on/off switch.
+ Your realm sets a SSO cookie so that you only have to enter in your login credentials once.
+ This Remember Me 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.
+
+
+
+ Session Timeouts
+
+ 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.
+
+
+ The SSO Session Idle Timeout 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.
+
+
+ The SSO Session Max Lifespan 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 Remember Me
+ in that it allow you to force a relogin after a set timeframe.
+
+
+
+ Token Timeouts
+
+ The Access Token Lifespan 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.
+
+
+ The Access Code Lifespan 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.
+
+
+ The Access Code Action Lifespan 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.
+
+
\ No newline at end of file