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

Merge pull request #428 from patriot1burke/master

Browse source 
docs
This commit is contained in:
Bill Burke 2014-05-28 12:34:11 -04:00
commit 0ff992e04e
8 changed files with 275 additions and 36 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

7
distribution/examples-docs-zip/assembly.xml
View file

@ -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
View 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>

6
docbook/reference/en/en-US/master.xml
View file

@ -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;

4
docbook/reference/en/en-US/modules/MigrationFromOlderVersions.xml
View file

@ -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
View 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
View 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
View 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>

87
docbook/reference/en/en-US/modules/timeouts.xml
View file

@ -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>