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

Minor updates to docs

Browse source
This commit is contained in:
Stian Thorgersen 2014-02-18 10:36:58 +00:00
parent cbb6ec8b2c
commit 7a8b5587d7
4 changed files with 55 additions and 68 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

6
docbook/reference/en/en-US/modules/Overview.xml
View file

@ -2,7 +2,7 @@
<title>Overview</title> <title>Overview</title>
<para> <para>
Keycloak is an SSO solution for web apps and RESTful web services. It is an authentication server where users Keycloak is an SSO solution for web apps, mobile and RESTful web services. It is an authentication server where users
can centrally login, logout, register, and manage their user accounts. The Keycloak admin UI can manage roles can centrally login, logout, register, and manage their user accounts. The Keycloak admin UI can manage roles
and role mappings for any application secured by Keycloak. The Keycloak Server can also be used to perform and role mappings for any application secured by Keycloak. The Keycloak Server can also be used to perform
social logins via the user's favorite social media site i.e. Google, Facebook, Twitter etc. social logins via the user's favorite social media site i.e. Google, Facebook, Twitter etc.
@ -20,7 +20,7 @@
</listitem> </listitem>
<listitem> <listitem>
Social Broker. Enable Google, Facebook, Yahoo, Twitter social login with no code required. Social Broker. Enable Google, GitHub, Facebook, Twitter social login with no code required.
</listitem> </listitem>
<listitem> <listitem>
@ -90,7 +90,7 @@
<section> <section>
<title>How Does Security Work in Keycloak?</title> <title>How Does Security Work in Keycloak?</title>
<para> <para>
Keycloak uses <emphasis>access tokens</emphasis>. Access tokens are contains security metadata specifying the Keycloak uses <emphasis>access tokens</emphasis>. Access tokens contains security metadata specifying the
identity of the user as well as the role mappings for that user. The format of these tokens is a Keycloak identity of the user as well as the role mappings for that user. The format of these tokens is a Keycloak
extension to the <ulink url="http://tools.ietf.org/html/draft-ietf-oauth-json-web-token-14">JSON Web Token</ulink> specification. Each realm has a private and public key pair extension to the <ulink url="http://tools.ietf.org/html/draft-ietf-oauth-json-web-token-14">JSON Web Token</ulink> specification. Each realm has a private and public key pair
which it uses to digitally sign the access token using the <ulink url="http://tools.ietf.org/html/draft-ietf-jose-json-web-signature-19">JSON Web Signature</ulink> specification. which it uses to digitally sign the access token using the <ulink url="http://tools.ietf.org/html/draft-ietf-jose-json-web-signature-19">JSON Web Signature</ulink> specification.

36
docbook/reference/en/en-US/modules/adapter-config.xml
View file

@ -93,7 +93,7 @@
<listitem> <listitem>
<para> <para>
Ensures that all communication to and from the Keycloak server from the adapter is over HTTPS. Ensures that all communication to and from the Keycloak server from the adapter is over HTTPS.
This is<emphasis>OPTIONAL</emphasis>. The default value is This is <emphasis>OPTIONAL</emphasis>. The default value is
<emphasis>false</emphasis> <emphasis>false</emphasis>
meaning meaning
that HTTPS is required by default. that HTTPS is required by default.
@ -107,7 +107,7 @@
If set to true, the adapter will look inside the token for application level role mappings for If set to true, the adapter will look inside the token for application level role mappings for
the the
user. If false, it will look at the realm level for user role mappings. user. If false, it will look at the realm level for user role mappings.
This is<emphasis>OPTIONAL</emphasis>. The default value is<emphasis>false</emphasis>. This is <emphasis>OPTIONAL</emphasis>. The default value is <emphasis>false</emphasis>.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -117,7 +117,7 @@
<para> <para>
This enables CORS support. It will handle CORS preflight requests. It will also look into This enables CORS support. It will handle CORS preflight requests. It will also look into
the access token to determine valid origins. the access token to determine valid origins.
This is<emphasis>OPTIONAL</emphasis>. The default value is<emphasis>false</emphasis>. This is <emphasis>OPTIONAL</emphasis>. The default value is <emphasis>false</emphasis>.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -128,7 +128,7 @@
If CORS is enabled, this sets the value of the If CORS is enabled, this sets the value of the
<literal>Access-Control-Max-Age</literal> <literal>Access-Control-Max-Age</literal>
header. header.
This is<emphasis>OPTIONAL</emphasis>. If not set, this header is not returned in CORS This is <emphasis>OPTIONAL</emphasis>. If not set, this header is not returned in CORS
responses. responses.
</para> </para>
</listitem> </listitem>
@ -140,7 +140,7 @@
If CORS is enabled, this sets the value of the If CORS is enabled, this sets the value of the
<literal>Access-Control-Allow-Methods</literal> <literal>Access-Control-Allow-Methods</literal>
header. This should be a JSON list of strings. header. This should be a JSON list of strings.
This is<emphasis>OPTIONAL</emphasis>. If not set, this header is not returned in CORS This is <emphasis>OPTIONAL</emphasis>. If not set, this header is not returned in CORS
responses. responses.
</para> </para>
</listitem> </listitem>
@ -149,11 +149,11 @@
<term>bearer-only</term> <term>bearer-only</term>
<listitem> <listitem>
<para> <para>
This tells the adapter to only to bearer token authentication. That is, it will not do This tells the adapter to only do bearer token authentication. That is, it will not do
OAuth 2.0 redirects, but only accept bearer tokens through the OAuth 2.0 redirects, but only accept bearer tokens through the
<literal>Authorization</literal> <literal>Authorization</literal>
header. header.
This is<emphasis>OPTIONAL</emphasis>. The default value is<emphasis>false</emphasis>. This is <emphasis>OPTIONAL</emphasis>. The default value is <emphasis>false</emphasis>.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -161,9 +161,9 @@
<term>expose-token</term> <term>expose-token</term>
<listitem> <listitem>
<para> <para>
If<literal>true</literal>, an authenticated browser client (via a Javascript HTTP invocation) If <literal>true</literal>, an authenticated browser client (via a Javascript HTTP invocation)
can obtain the signed access token via the URL<literal>root/k_query_bearer_token</literal>. can obtain the signed access token via the URL <literal>root/k_query_bearer_token</literal>.
This is<emphasis>OPTIONAL</emphasis>. The default value is<emphasis>false</emphasis>. This is <emphasis>OPTIONAL</emphasis>. The default value is <emphasis>false</emphasis>.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -175,7 +175,7 @@
is the credential type and the value if the value of the credential type. Currently only is the credential type and the value if the value of the credential type. Currently only
<literal>password</literal> <literal>password</literal>
is supported. is supported.
This is<emphasis>REQUIRED</emphasis>. This is <emphasis>REQUIRED</emphasis>.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -187,7 +187,7 @@
Adapters will make separate HTTP invocations to the Keycloak Server to turn an access code Adapters will make separate HTTP invocations to the Keycloak Server to turn an access code
into an access token. This config option defines how many connections to the Keycloak Server into an access token. This config option defines how many connections to the Keycloak Server
should be pooled. should be pooled.
This is<emphasis>OPTIONAL</emphasis>. The default value is <literal>20</literal>. This is <emphasis>OPTIONAL</emphasis>. The default value is <literal>20</literal>.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -198,7 +198,7 @@
If the Keycloak Server requires HTTPS and this config option is set to <literal>true</literal> If the Keycloak Server requires HTTPS and this config option is set to <literal>true</literal>
you do not have to specify a truststore. While convenient, this setting is not recommended you do not have to specify a truststore. While convenient, this setting is not recommended
as you will not be verifying the host name of the Keycloak Server. as you will not be verifying the host name of the Keycloak Server.
This is<emphasis>OPTIONAL</emphasis>. The default value is <literal>false</literal>. This is <emphasis>OPTIONAL</emphasis>. The default value is <literal>false</literal>.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -209,7 +209,7 @@
If the Keycloak Server requires HTTPS and this config option is set to <literal>true</literal> If the Keycloak Server requires HTTPS and this config option is set to <literal>true</literal>
the Keycloak Server's certificate is validated via the truststore, but host name validation is the Keycloak Server's certificate is validated via the truststore, but host name validation is
not done. This is not a recommended. This seting may be useful in test environments not done. This is not a recommended. This seting may be useful in test environments
This is<emphasis>OPTIONAL</emphasis>. The default value is <literal>false</literal>. This is <emphasis>OPTIONAL</emphasis>. The default value is <literal>false</literal>.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -220,7 +220,7 @@
<para> <para>
This setting is for Java adapters. This is the file path to a Java keystore file. This setting is for Java adapters. This is the file path to a Java keystore file.
Used for outgoing HTTPS communications to the Keycloak server. Client making HTTPS Used for outgoing HTTPS communications to the Keycloak server. Client making HTTPS
requests need a way to verify the host of the server they are talking to. THis is requests need a way to verify the host of the server they are talking to. This is
what the trustore does. The keystore contains one or more trusted what the trustore does. The keystore contains one or more trusted
host certificates or certificate authorities. You can host certificates or certificate authorities. You can
create this truststore by extracting the public certificate of the Keycloak server's SSL create this truststore by extracting the public certificate of the Keycloak server's SSL
@ -233,7 +233,7 @@
<literal>false</literal> <literal>false</literal>
or or
<literal>disable-trust-manager</literal> <literal>disable-trust-manager</literal>
is<literal>true</literal>. The default value is<emphasis>false</emphasis>. is <literal>true</literal>. The default value is<emphasis>false</emphasis>.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -259,7 +259,7 @@
This setting is for Java adapters. This is the file path to a Java keystore file. This setting is for Java adapters. This is the file path to a Java keystore file.
This keystore contains client certificate for two-way SSL when the adapter makes This keystore contains client certificate for two-way SSL when the adapter makes
HTTPS requests to the Keycloak server. HTTPS requests to the Keycloak server.
This is<emphasis>OPTIONAL</emphasis>. This is <emphasis>OPTIONAL</emphasis>.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -293,4 +293,4 @@
</varlistentry> </varlistentry>
</variablelist> </variablelist>
</para> </para>
</section> </section>

15
docbook/reference/en/en-US/modules/openshift.xml
View file

@ -23,15 +23,15 @@
<para> <para>
Open Open
<ulink url="https://openshift.redhat.com/app/console/applications"/> <ulink url="https://openshift.redhat.com/app/console/applications"/>
and click on<literal>Add Application</literal>. and click on <literal>Add Application</literal>.
Scroll down to the bottom of the page to find the Scroll down to the bottom of the page to find the
<literal>Code Anything</literal> <literal>Code Anything</literal>
section. Insert section. Insert
<literal>https://raw.github.com/keycloak/openshift-keycloak-cartridge/master/metadata/manifest.yml</literal> <literal>https://raw.github.com/keycloak/openshift-keycloak-cartridge/master/metadata/manifest.yml</literal>
into the into the
<literal>URL to a cartridge definition</literal> <literal>URL to a cartridge definition</literal>
field and click on<literal>Next</literal>. Fill in the field and click on <literal>Next</literal>. Fill in the
following form and click on<literal>Create Application</literal>. following form and click on <literal>Create Application</literal>.
</para> </para>
<para> <para>
Click on <literal>Continue to the application overview page</literal>. Under the list of applications you should Click on <literal>Continue to the application overview page</literal>. Under the list of applications you should
@ -56,15 +56,14 @@
<section> <section>
<title>Next steps</title> <title>Next steps</title>
<para> <para>
The Keycloak servers homepage should show the Keycloak logo and <literal>Welcome to Keycloak</literal>. The Keycloak servers homepage shows the Keycloak logo and <literal>Welcome to Keycloak</literal>.
There should also be a link to the <literal>Administration Console</literal>. Open that and log in using username There is also a link to the <literal>Administration Console</literal>. Open that and log in using username
<literal>admin</literal> and password <literal>admin</literal>. On the first login you should be asked <literal>admin</literal> and password <literal>admin</literal>. On the first login you are required to change the password.
to reset the password.
</para> </para>
<tip> <tip>
<para> <para>
On OpenShift Keycloak has been configured to only accept requests over https. If you try to use http On OpenShift Keycloak has been configured to only accept requests over https. If you try to use http
you should be redirected to https. you will be redirected to https.
</para> </para>
</tip> </tip>
</section> </section>

66
docbook/reference/en/en-US/modules/server-installation.xml
View file

@ -175,7 +175,7 @@ keycloak-war-dist-all-1.0-alpha-1/
</para> </para>
<para> <para>
Besides moving the database config into the central <literal>standalone.xml</literal> configuration file Besides moving the database config into the central <literal>standalone.xml</literal> configuration file
you might want to use a better relational database for Keycloak like Oracle or something. You might also you might want to use a better relational database for Keycloak like PostgreSQL or MySQL. You might also
want to tweak the configuration settings of the datasource. Please see the <ulink url="https://docs.jboss.org/author/display/WFLY8/DataSource+configuration">Wildfly</ulink>, want to tweak the configuration settings of the datasource. Please see the <ulink url="https://docs.jboss.org/author/display/WFLY8/DataSource+configuration">Wildfly</ulink>,
<ulink url="https://docs.jboss.org/author/display/AS71/DataSource+configuration">JBoss AS7</ulink>, <ulink url="https://docs.jboss.org/author/display/AS71/DataSource+configuration">JBoss AS7</ulink>,
or <ulink url="https://docs.jboss.org/author/display/AS71/DataSource+configuration">JBoss EAP 6.x</ulink> documentation on how to do this. or <ulink url="https://docs.jboss.org/author/display/AS71/DataSource+configuration">JBoss EAP 6.x</ulink> documentation on how to do this.
@ -261,29 +261,29 @@ $ keytool -genkey -alias localhost -keyalg RSA -keystore keycloak.jks -validity
</para> </para>
<para> <para>
The first thing to do is generate a Certificate Request: The first thing to do is generate a Certificate Request:
<programlisting> <programlisting>
$ keytool -certreq -alias yourdomain -keystore keycloak.jks > keycloak.careq $ keytool -certreq -alias yourdomain -keystore keycloak.jks > keycloak.careq
</programlisting> </programlisting>
</para> </para>
<para> <para>
Where <literal>yourdomain</literal> is a DNS name for which this certificate is generated for. Where <literal>yourdomain</literal> is a DNS name for which this certificate is generated for.
Keytool generates the request: Keytool generates the request:
<programlisting> <programlisting>
-----BEGIN NEW CERTIFICATE REQUEST----- -----BEGIN NEW CERTIFICATE REQUEST-----
MIIC2jCCAcICAQAwZTELMAkGA1UEBhMCVVMxCzAJBgNVBAgTAk1BMREwDwYDVQQHEwhXZXN0Zm9y MIIC2jCCAcICAQAwZTELMAkGA1UEBhMCVVMxCzAJBgNVBAgTAk1BMREwDwYDVQQHEwhXZXN0Zm9y
ZDEQMA4GA1UEChMHUmVkIEhhdDEQMA4GA1UECxMHUmVkIEhhdDESMBAGA1UEAxMJbG9jYWxob3N0 ZDEQMA4GA1UEChMHUmVkIEhhdDEQMA4GA1UECxMHUmVkIEhhdDESMBAGA1UEAxMJbG9jYWxob3N0
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAr7kck2TaavlEOGbcpi9c0rncY4HhdzmY MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAr7kck2TaavlEOGbcpi9c0rncY4HhdzmY
Ax2nZfq1eZEaIPqI5aTxwQZzzLDK9qbeAd8Ji79HzSqnRDxNYaZu7mAYhFKHgixsolE3o5Yfzbw1 Ax2nZfq1eZEaIPqI5aTxwQZzzLDK9qbeAd8Ji79HzSqnRDxNYaZu7mAYhFKHgixsolE3o5Yfzbw1
29Rvy+eUVe+WZxv5oo9wolVVpdSINIMEL2LaFhtX/c1dqiqYVpfnvFshZQaIg2nL8juzZcBjj4as 29Rvy+eUVe+WZxv5oo9wolVVpdSINIMEL2LaFhtX/c1dqiqYVpfnvFshZQaIg2nL8juzZcBjj4as
H98gIS7khql/dkZKsw9NLvyxgJvp7PaXurX29fNf3ihG+oFrL22oFyV54BWWxXCKU/GPn61EGZGw H98gIS7khql/dkZKsw9NLvyxgJvp7PaXurX29fNf3ihG+oFrL22oFyV54BWWxXCKU/GPn61EGZGw
Ft2qSIGLdctpMD1aJR2bcnlhEjZKDksjQZoQ5YMXaAGkcYkG6QkgrocDE2YXDbi7GIdf9MegVJ35 Ft2qSIGLdctpMD1aJR2bcnlhEjZKDksjQZoQ5YMXaAGkcYkG6QkgrocDE2YXDbi7GIdf9MegVJ35
2DQMpwIDAQABoDAwLgYJKoZIhvcNAQkOMSEwHzAdBgNVHQ4EFgQUQwlZJBA+fjiDdiVzaO9vrE/i 2DQMpwIDAQABoDAwLgYJKoZIhvcNAQkOMSEwHzAdBgNVHQ4EFgQUQwlZJBA+fjiDdiVzaO9vrE/i
n2swDQYJKoZIhvcNAQELBQADggEBAC5FRvMkhal3q86tHPBYWBuTtmcSjs4qUm6V6f63frhveWHf n2swDQYJKoZIhvcNAQELBQADggEBAC5FRvMkhal3q86tHPBYWBuTtmcSjs4qUm6V6f63frhveWHf
PzRrI1xH272XUIeBk0gtzWo0nNZnf0mMCtUBbHhhDcG82xolikfqibZijoQZCiGiedVjHJFtniDQ PzRrI1xH272XUIeBk0gtzWo0nNZnf0mMCtUBbHhhDcG82xolikfqibZijoQZCiGiedVjHJFtniDQ
9bMDUOXEMQ7gHZg5q6mJfNG9MbMpQaUVEEFvfGEQQxbiFK7hRWU8S23/d80e8nExgQxdJWJ6vd0X 9bMDUOXEMQ7gHZg5q6mJfNG9MbMpQaUVEEFvfGEQQxbiFK7hRWU8S23/d80e8nExgQxdJWJ6vd0X
MzzFK6j4Dj55bJVuM7GFmfdNC52pNOD5vYe47Aqh8oajHX9XTycVtPXl45rrWAH33ftbrS8SrZ2S MzzFK6j4Dj55bJVuM7GFmfdNC52pNOD5vYe47Aqh8oajHX9XTycVtPXl45rrWAH33ftbrS8SrZ2S
vqIFQeuLL3BaHwpl3t7j2lMWcK1p80laAxEASib/fAwrRHpLHBXRcq6uALUOZl4Alt8= vqIFQeuLL3BaHwpl3t7j2lMWcK1p80laAxEASib/fAwrRHpLHBXRcq6uALUOZl4Alt8=
-----END NEW CERTIFICATE REQUEST----- -----END NEW CERTIFICATE REQUEST-----
</programlisting> </programlisting>
</para> </para>
<para> <para>
@ -312,24 +312,18 @@ $ keytool -import -alias yourdomain -keystore keycloak.jks -file your-certificat
</para> </para>
<para> <para>
To the <literal>security-realms</literal> element add: To the <literal>security-realms</literal> element add:
<programlisting><![CDATA[] <programlisting><![CDATA[<security-realm name="UndertowRealm">
<security-realm name="UndertowRealm">
<server-identities> <server-identities>
<ssl> <ssl>
<keystore path="keycloak.jks" relative-to="jboss.server.config.dir" keystore-password="secret" /> <keystore path="keycloak.jks" relative-to="jboss.server.config.dir" keystore-password="secret" />
</ssl> </ssl>
</server-identities> </server-identities>
</security-realm> </security-realm>]]></programlisting>
]]>
</programlisting>
</para> </para>
<para> <para>
Find the element <literal>&lt;server name="default-server"&gt;</literal> (it's a child element of <literal>&lt;subsystem xmlns="urn:jboss:domain:undertow:1.0"&gt;</literal>) and add: Find the element <literal>&lt;server name="default-server"&gt;</literal> (it's a child element of <literal>&lt;subsystem xmlns="urn:jboss:domain:undertow:1.0"&gt;</literal>) and add:
<programlisting><![CDATA[]<![CDATA[] <programlisting><![CDATA[<https-listener name="https" socket-binding="https" security-realm="UndertowRealm"/>
< ]]></programlisting>
<https-listener name="https" socket-binding="https" security-realm="UndertowRealm"/>
]]>
</programlisting>
</para> </para>
<para> <para>
Check the <ulink url="https://docs.jboss.org/author/display/WFLY8/Undertow+(web)+subsystem+configuration">Wildfly Undertow</ulink> documentation for more information on fine tuning the socket connections. Check the <ulink url="https://docs.jboss.org/author/display/WFLY8/Undertow+(web)+subsystem+configuration">Wildfly Undertow</ulink> documentation for more information on fine tuning the socket connections.
@ -344,8 +338,7 @@ $ keytool -import -alias yourdomain -keystore keycloak.jks -file your-certificat
Then you need to edit <literal>standalone/configuration/standalone.xml</literal> to enable SSL/HTTPS. Then you need to edit <literal>standalone/configuration/standalone.xml</literal> to enable SSL/HTTPS.
</para> </para>
<para> <para>
<programlisting><![CDATA[] <programlisting><![CDATA[<subsystem xmlns="urn:jboss:domain:web:1.1" default-virtual-server="default-host" native="false">
<subsystem xmlns="urn:jboss:domain:web:1.1" default-virtual-server="default-host" native="false">
<connector name="http" protocol="HTTP/1.1" scheme="http" socket-binding="http" redirect-port="443" /> <connector name="http" protocol="HTTP/1.1" scheme="http" socket-binding="http" redirect-port="443" />
<connector name="https" scheme="https" protocol="HTTP/1.1" socket-binding="https" <connector name="https" scheme="https" protocol="HTTP/1.1" socket-binding="https"
enable-lookups="false" secure="true"> enable-lookups="false" secure="true">
@ -353,9 +346,7 @@ $ keytool -import -alias yourdomain -keystore keycloak.jks -file your-certificat
key-alias="localhost" certificate-key-file="${jboss.server.config.dir}/keycloak.jks" /> key-alias="localhost" certificate-key-file="${jboss.server.config.dir}/keycloak.jks" />
</connector> </connector>
... ...
</subsystem> </subsystem>]]></programlisting>
]]>
</programlisting>
</para> </para>
<para> <para>
Check the <ulink url="https://docs.jboss.org/author/display/AS71/SSL+setup+guide">JBoss</ulink> documentation for more information on fine tuning the socket connections. Check the <ulink url="https://docs.jboss.org/author/display/AS71/SSL+setup+guide">JBoss</ulink> documentation for more information on fine tuning the socket connections.
@ -369,8 +360,7 @@ $ keytool -import -alias yourdomain -keystore keycloak.jks -file your-certificat
uncomment out the security constraint. uncomment out the security constraint.
</para> </para>
<para> <para>
<programlisting><![CDATA[] <programlisting><![CDATA[<web-app>
<web-app>
... ...
<security-constraint> <security-constraint>
<web-resource-collection> <web-resource-collection>
@ -380,9 +370,7 @@ $ keytool -import -alias yourdomain -keystore keycloak.jks -file your-certificat
<transport-guarantee>CONFIDENTIAL</transport-guarantee> <transport-guarantee>CONFIDENTIAL</transport-guarantee>
</user-data-constraint> </user-data-constraint>
</security-constraint> </security-constraint>
</web-app> </web-app>]]></programlisting>
]]>
</programlisting>
</para> </para>
</section> </section>
<section> <section>