From 7a8b5587d703d98a3a5d23711f9af03f8899e74d Mon Sep 17 00:00:00 2001 From: Stian Thorgersen Date: Tue, 18 Feb 2014 10:36:58 +0000 Subject: [PATCH] Minor updates to docs --- .../reference/en/en-US/modules/Overview.xml | 6 +- .../en/en-US/modules/adapter-config.xml | 36 +++++----- .../reference/en/en-US/modules/openshift.xml | 15 ++--- .../en/en-US/modules/server-installation.xml | 66 ++++++++----------- 4 files changed, 55 insertions(+), 68 deletions(-) diff --git a/docbook/reference/en/en-US/modules/Overview.xml b/docbook/reference/en/en-US/modules/Overview.xml index dda24860c3..8e970c7699 100755 --- a/docbook/reference/en/en-US/modules/Overview.xml +++ b/docbook/reference/en/en-US/modules/Overview.xml @@ -2,7 +2,7 @@ Overview - 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 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. @@ -20,7 +20,7 @@ - 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. @@ -90,7 +90,7 @@
How Does Security Work in Keycloak? - Keycloak uses access tokens. Access tokens are contains security metadata specifying the + Keycloak uses access tokens. 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 extension to the JSON Web Token specification. Each realm has a private and public key pair which it uses to digitally sign the access token using the JSON Web Signature specification. diff --git a/docbook/reference/en/en-US/modules/adapter-config.xml b/docbook/reference/en/en-US/modules/adapter-config.xml index 0152f2c858..29b03b5bd6 100755 --- a/docbook/reference/en/en-US/modules/adapter-config.xml +++ b/docbook/reference/en/en-US/modules/adapter-config.xml @@ -93,7 +93,7 @@ Ensures that all communication to and from the Keycloak server from the adapter is over HTTPS. - This isOPTIONAL. The default value is + This is OPTIONAL. The default value is false meaning 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 the user. If false, it will look at the realm level for user role mappings. - This isOPTIONAL. The default value isfalse. + This is OPTIONAL. The default value is false. @@ -117,7 +117,7 @@ This enables CORS support. It will handle CORS preflight requests. It will also look into the access token to determine valid origins. - This isOPTIONAL. The default value isfalse. + This is OPTIONAL. The default value is false. @@ -128,7 +128,7 @@ If CORS is enabled, this sets the value of the Access-Control-Max-Age header. - This isOPTIONAL. If not set, this header is not returned in CORS + This is OPTIONAL. If not set, this header is not returned in CORS responses. @@ -140,7 +140,7 @@ If CORS is enabled, this sets the value of the Access-Control-Allow-Methods header. This should be a JSON list of strings. - This isOPTIONAL. If not set, this header is not returned in CORS + This is OPTIONAL. If not set, this header is not returned in CORS responses. @@ -149,11 +149,11 @@ bearer-only - 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 Authorization header. - This isOPTIONAL. The default value isfalse. + This is OPTIONAL. The default value is false. @@ -161,9 +161,9 @@ expose-token - Iftrue, an authenticated browser client (via a Javascript HTTP invocation) - can obtain the signed access token via the URLroot/k_query_bearer_token. - This isOPTIONAL. The default value isfalse. + If true, an authenticated browser client (via a Javascript HTTP invocation) + can obtain the signed access token via the URL root/k_query_bearer_token. + This is OPTIONAL. The default value is false. @@ -175,7 +175,7 @@ is the credential type and the value if the value of the credential type. Currently only password is supported. - This isREQUIRED. + This is REQUIRED. @@ -187,7 +187,7 @@ 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 should be pooled. - This isOPTIONAL. The default value is 20. + This is OPTIONAL. The default value is 20. @@ -198,7 +198,7 @@ If the Keycloak Server requires HTTPS and this config option is set to true 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. - This isOPTIONAL. The default value is false. + This is OPTIONAL. The default value is false. @@ -209,7 +209,7 @@ If the Keycloak Server requires HTTPS and this config option is set to true 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 - This isOPTIONAL. The default value is false. + This is OPTIONAL. The default value is false. @@ -220,7 +220,7 @@ 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 - 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 host certificates or certificate authorities. You can create this truststore by extracting the public certificate of the Keycloak server's SSL @@ -233,7 +233,7 @@ false or disable-trust-manager - istrue. The default value isfalse. + is true. The default value isfalse. @@ -259,7 +259,7 @@ 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 HTTPS requests to the Keycloak server. - This isOPTIONAL. + This is OPTIONAL. @@ -293,4 +293,4 @@ -
\ No newline at end of file + diff --git a/docbook/reference/en/en-US/modules/openshift.xml b/docbook/reference/en/en-US/modules/openshift.xml index 10e4539f77..78b1b90c6b 100644 --- a/docbook/reference/en/en-US/modules/openshift.xml +++ b/docbook/reference/en/en-US/modules/openshift.xml @@ -23,15 +23,15 @@ Open - and click onAdd Application. + and click on Add Application. Scroll down to the bottom of the page to find the Code Anything section. Insert https://raw.github.com/keycloak/openshift-keycloak-cartridge/master/metadata/manifest.yml into the URL to a cartridge definition - field and click onNext. Fill in the - following form and click onCreate Application. + field and click on Next. Fill in the + following form and click on Create Application. Click on Continue to the application overview page. Under the list of applications you should @@ -56,15 +56,14 @@
Next steps - The Keycloak servers homepage should show the Keycloak logo and Welcome to Keycloak. - There should also be a link to the Administration Console. Open that and log in using username - admin and password admin. On the first login you should be asked - to reset the password. + The Keycloak servers homepage shows the Keycloak logo and Welcome to Keycloak. + There is also a link to the Administration Console. Open that and log in using username + admin and password admin. On the first login you are required to change the password. 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.
diff --git a/docbook/reference/en/en-US/modules/server-installation.xml b/docbook/reference/en/en-US/modules/server-installation.xml index 0af18587c7..208928cc49 100755 --- a/docbook/reference/en/en-US/modules/server-installation.xml +++ b/docbook/reference/en/en-US/modules/server-installation.xml @@ -175,7 +175,7 @@ keycloak-war-dist-all-1.0-alpha-1/ Besides moving the database config into the central standalone.xml 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 Wildfly, JBoss AS7, or JBoss EAP 6.x documentation on how to do this. @@ -261,29 +261,29 @@ $ keytool -genkey -alias localhost -keyalg RSA -keystore keycloak.jks -validity The first thing to do is generate a Certificate Request: - - $ keytool -certreq -alias yourdomain -keystore keycloak.jks > keycloak.careq - + +$ keytool -certreq -alias yourdomain -keystore keycloak.jks > keycloak.careq + Where yourdomain is a DNS name for which this certificate is generated for. Keytool generates the request: - -----BEGIN NEW CERTIFICATE REQUEST----- - MIIC2jCCAcICAQAwZTELMAkGA1UEBhMCVVMxCzAJBgNVBAgTAk1BMREwDwYDVQQHEwhXZXN0Zm9y - ZDEQMA4GA1UEChMHUmVkIEhhdDEQMA4GA1UECxMHUmVkIEhhdDESMBAGA1UEAxMJbG9jYWxob3N0 - MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAr7kck2TaavlEOGbcpi9c0rncY4HhdzmY - Ax2nZfq1eZEaIPqI5aTxwQZzzLDK9qbeAd8Ji79HzSqnRDxNYaZu7mAYhFKHgixsolE3o5Yfzbw1 - 29Rvy+eUVe+WZxv5oo9wolVVpdSINIMEL2LaFhtX/c1dqiqYVpfnvFshZQaIg2nL8juzZcBjj4as - H98gIS7khql/dkZKsw9NLvyxgJvp7PaXurX29fNf3ihG+oFrL22oFyV54BWWxXCKU/GPn61EGZGw - Ft2qSIGLdctpMD1aJR2bcnlhEjZKDksjQZoQ5YMXaAGkcYkG6QkgrocDE2YXDbi7GIdf9MegVJ35 - 2DQMpwIDAQABoDAwLgYJKoZIhvcNAQkOMSEwHzAdBgNVHQ4EFgQUQwlZJBA+fjiDdiVzaO9vrE/i - n2swDQYJKoZIhvcNAQELBQADggEBAC5FRvMkhal3q86tHPBYWBuTtmcSjs4qUm6V6f63frhveWHf - PzRrI1xH272XUIeBk0gtzWo0nNZnf0mMCtUBbHhhDcG82xolikfqibZijoQZCiGiedVjHJFtniDQ - 9bMDUOXEMQ7gHZg5q6mJfNG9MbMpQaUVEEFvfGEQQxbiFK7hRWU8S23/d80e8nExgQxdJWJ6vd0X - MzzFK6j4Dj55bJVuM7GFmfdNC52pNOD5vYe47Aqh8oajHX9XTycVtPXl45rrWAH33ftbrS8SrZ2S - vqIFQeuLL3BaHwpl3t7j2lMWcK1p80laAxEASib/fAwrRHpLHBXRcq6uALUOZl4Alt8= - -----END NEW CERTIFICATE REQUEST----- +-----BEGIN NEW CERTIFICATE REQUEST----- +MIIC2jCCAcICAQAwZTELMAkGA1UEBhMCVVMxCzAJBgNVBAgTAk1BMREwDwYDVQQHEwhXZXN0Zm9y +ZDEQMA4GA1UEChMHUmVkIEhhdDEQMA4GA1UECxMHUmVkIEhhdDESMBAGA1UEAxMJbG9jYWxob3N0 +MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAr7kck2TaavlEOGbcpi9c0rncY4HhdzmY +Ax2nZfq1eZEaIPqI5aTxwQZzzLDK9qbeAd8Ji79HzSqnRDxNYaZu7mAYhFKHgixsolE3o5Yfzbw1 +29Rvy+eUVe+WZxv5oo9wolVVpdSINIMEL2LaFhtX/c1dqiqYVpfnvFshZQaIg2nL8juzZcBjj4as +H98gIS7khql/dkZKsw9NLvyxgJvp7PaXurX29fNf3ihG+oFrL22oFyV54BWWxXCKU/GPn61EGZGw +Ft2qSIGLdctpMD1aJR2bcnlhEjZKDksjQZoQ5YMXaAGkcYkG6QkgrocDE2YXDbi7GIdf9MegVJ35 +2DQMpwIDAQABoDAwLgYJKoZIhvcNAQkOMSEwHzAdBgNVHQ4EFgQUQwlZJBA+fjiDdiVzaO9vrE/i +n2swDQYJKoZIhvcNAQELBQADggEBAC5FRvMkhal3q86tHPBYWBuTtmcSjs4qUm6V6f63frhveWHf +PzRrI1xH272XUIeBk0gtzWo0nNZnf0mMCtUBbHhhDcG82xolikfqibZijoQZCiGiedVjHJFtniDQ +9bMDUOXEMQ7gHZg5q6mJfNG9MbMpQaUVEEFvfGEQQxbiFK7hRWU8S23/d80e8nExgQxdJWJ6vd0X +MzzFK6j4Dj55bJVuM7GFmfdNC52pNOD5vYe47Aqh8oajHX9XTycVtPXl45rrWAH33ftbrS8SrZ2S +vqIFQeuLL3BaHwpl3t7j2lMWcK1p80laAxEASib/fAwrRHpLHBXRcq6uALUOZl4Alt8= +-----END NEW CERTIFICATE REQUEST----- @@ -312,24 +312,18 @@ $ keytool -import -alias yourdomain -keystore keycloak.jks -file your-certificat To the security-realms element add: - + - -]]> - +]]> Find the element <server name="default-server"> (it's a child element of <subsystem xmlns="urn:jboss:domain:undertow:1.0">) and add: - -]]> - + +]]> Check the Wildfly Undertow 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 standalone/configuration/standalone.xml to enable SSL/HTTPS. - + @@ -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" /> ... - -]]> - +]]> Check the JBoss 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. - + ... @@ -380,9 +370,7 @@ $ keytool -import -alias yourdomain -keystore keycloak.jks -file your-certificat CONFIDENTIAL - -]]> - +]]>