diff --git a/README.adoc b/README.adoc index 2f3391b7d4..b405f3a8fb 100755 --- a/README.adoc +++ b/README.adoc @@ -1,5 +1,5 @@ -Keycloak Server Adminstration Guide Documentation +Keycloak Server Administration Guide Documentation ====================== image:images/keycloak_logo.png[alt="Keycloak"] diff --git a/SUMMARY.adoc b/SUMMARY.adoc index c64062b217..5a4af888e2 100755 --- a/SUMMARY.adoc +++ b/SUMMARY.adoc @@ -101,6 +101,7 @@ .. link:topics/threat/password-db-compromised.adoc[Password database compromised] .. link:topics/threat/scope.adoc[Limiting Scope] .. link:topics/threat/sql.adoc[SQL Injection Attacks] + {% if book.community %} . link:topics/MigrationFromOlderVersions.adoc[Migration from older versions] - + {% endif %} diff --git a/book.json b/book.json index 0acc68fe94..01807c04cb 100755 --- a/book.json +++ b/book.json @@ -65,7 +65,7 @@ }, "adminguide": { - "name": "Keycloak Adminstration Guide", + "name": "Keycloak Administration Guide", "link": "https://keycloak.gitbooks.io/server-adminstration-guide/content/" }, "installguide": { @@ -81,4 +81,4 @@ "version": "1.9.3.Final" } } -} \ No newline at end of file +} diff --git a/topics/clients/client-link.adoc b/topics/clients/client-link.adoc index a608cd1f42..1ab2142653 100755 --- a/topics/clients/client-link.adoc +++ b/topics/clients/client-link.adoc @@ -3,7 +3,7 @@ For scenarios where one wants to link from one client to another, {{book.project.name}} provides a special redirect endpoint: `/realms/realm_name/clients/\{client-id}/redirect`. -If a client accesses this endpoint via an `HTTP GET` request, Keycloak returns the configured base URL for the provided Client and Realm in the form of an `HTTP 307` (Temporary Redirect) via the response's `Location` header. +If a client accesses this endpoint via an `HTTP GET` request, {{book.project.name}} returns the configured base URL for the provided Client and Realm in the form of an `HTTP 307` (Temporary Redirect) via the response's `Location` header. Thus, a client only needs to know the Realm name and the Client ID in order to link to them. This indirection helps avoid hard-coding client base URLs. diff --git a/topics/clients/client-saml.adoc b/topics/clients/client-saml.adoc index f536cc0bc0..c80f1dac34 100755 --- a/topics/clients/client-saml.adoc +++ b/topics/clients/client-saml.adoc @@ -56,7 +56,7 @@ Include AuthnStatement:: Setting this to on will include that statement in the response document. Sign Documents:: - When turned on, Keycloak will sign the document using the realm's private key. + When turned on, {{book.project.name}} will sign the document using the realm's private key. Sign Assertions:: The `Sign Documents` switch signs the whole document. diff --git a/topics/clients/client-templates.adoc b/topics/clients/client-templates.adoc index 1dae08a972..75d4f1d972 100644 --- a/topics/clients/client-templates.adoc +++ b/topics/clients/client-templates.adoc @@ -1,18 +1,18 @@ - +[[_client_templates]] === Client Templates If you have a lot of applications you need to secure and register within your organization it can become quite tedious -to configure the <> and <> +to configure the <> and <> for each of these clients. {{book.project.name}} allows you to define shared client configuration in an entity called a _client template_. To create a client template, go to the `Client Templates` left menu item. This initial screen shows you a list of currently defined templates. To create a template click the `Create` button. This brings you to a simple screen in which you name the template and hit save. A _client template_ will have similar tabs to regular clients. You'll be able to define <> -and <> which can be inherited by other clients. +and <> which can be inherited by other clients. Having a client inherit from a template is as simple as choosing the template from the `Client Template` drop down list on either the `Add Client` or client `Settings` tab. You will see the `Mappers` and `Scope` tabs get additional switches which allow you to turn on or off inheriting from the parent template. -Future versions of client templating may get more inheritable configuration options, but for now, that's all there is to talk about. \ No newline at end of file +Future versions of client templating may get more inheritable configuration options, but for now, that's all there is to talk about. diff --git a/topics/clients/oidc/confidential.adoc b/topics/clients/oidc/confidential.adoc index e1b2e982fe..745ae4d196 100644 --- a/topics/clients/oidc/confidential.adoc +++ b/topics/clients/oidc/confidential.adoc @@ -2,7 +2,7 @@ ==== Confidential Client Credentials -If you've set the client's <> to `confidential` in the client's +If you've set the client's <> to `confidential` in the client's `Settings` tab, a new `Credentials` tab will show up. As part of dealing with this type of client you have to configure the client's credentials. diff --git a/topics/clients/oidc/service-accounts.adoc b/topics/clients/oidc/service-accounts.adoc index 18d0b683cf..e41c3ec54a 100755 --- a/topics/clients/oidc/service-accounts.adoc +++ b/topics/clients/oidc/service-accounts.adoc @@ -1,4 +1,4 @@ -[[_service-accounts]] +[[_service_accounts]] === Service Accounts @@ -8,7 +8,7 @@ To use this feature you must set the <>. -To use it you must have registered a valid `confidential` Client and you need to check the switch `Service Accounts Enabled` in Keycloak admin console for this client. +To use it you must have registered a valid `confidential` Client and you need to check the switch `Service Accounts Enabled` in {{book.project.name}} admin console for this client. In tab `Service Account Roles` you can configure the roles available to the service account retrieved on behalf of this client. Don't forget that you need those roles to be available in Scopes of this client as well (unless you have `Full Scope Allowed` on). As in normal login, roles from access token are intersection of scopes and the service account roles. diff --git a/topics/clients/saml/idp-initiated-login.adoc b/topics/clients/saml/idp-initiated-login.adoc index c2de9791b7..781d469383 100644 --- a/topics/clients/saml/idp-initiated-login.adoc +++ b/topics/clients/saml/idp-initiated-login.adoc @@ -1,7 +1,7 @@ ==== IDP Initiated Login -IDP Initiated Login is a feature that where you can set up a URL on the Keycloak server that will log you into a specific application/client. +IDP Initiated Login is a feature that where you can set up a URL on the {{book.project.name}} server that will log you into a specific application/client. In the `Settings` tab for your client, you need to specify the `IDP Initiated SSO URL Name`. This is a simple string with no whitespace in it. After this you can reference your client at the following URL: `root/auth/realms/{realm}/protocol/saml/clients/{url-name}` diff --git a/topics/groups/default-groups.adoc b/topics/groups/default-groups.adoc index f7dd8fec42..d17b063986 100644 --- a/topics/groups/default-groups.adoc +++ b/topics/groups/default-groups.adoc @@ -2,7 +2,7 @@ ==== Default Groups Default groups allow you to automatically assign group membership whenever any new user is created or imported through -<> or <>. +<> or <>. To specify _default groups go to the `Groups` left menu item, and click the `Default Groups` tab. .Default Roles diff --git a/topics/identity-broker.adoc b/topics/identity-broker.adoc index d4152ea146..83ce9afe59 100755 --- a/topics/identity-broker.adoc +++ b/topics/identity-broker.adoc @@ -1,4 +1,4 @@ -[[_identity-brokering]] +[[_identity_broker]] == Identity Brokering diff --git a/topics/identity-broker/first-login-flow.adoc b/topics/identity-broker/first-login-flow.adoc index 458663b284..5b4c5ee6ad 100644 --- a/topics/identity-broker/first-login-flow.adoc +++ b/topics/identity-broker/first-login-flow.adoc @@ -22,7 +22,7 @@ The flow itself is configured in admin console under `Authentication` tab. When you choose `First Broker Login` flow, you will see what authenticators are used by default. You can either re-configure existing flow (For example disable some authenticators, mark some of them as `required`, configure some authenticators etc). Or you can even create new authentication flow and/or write your own Authenticator implementations and use it in your flow. -See link:{{book.developerguide.link}}[{{book.developerguide.name}} for more details. +See link:{{book.developerguide.link}}[{{book.developerguide.name}}] for more details. ==== Default First Login Flow diff --git a/topics/identity-broker/mappers.adoc b/topics/identity-broker/mappers.adoc index 45e5b1a1d1..cdc26e0d02 100644 --- a/topics/identity-broker/mappers.adoc +++ b/topics/identity-broker/mappers.adoc @@ -1,4 +1,4 @@ - +[[_mappers]] === Mapping Claims and Assertions You can import the SAML and OpenID Connect metadata provided by the external IDP you are authenticating with into the environment diff --git a/topics/identity-broker/overview.adoc b/topics/identity-broker/overview.adoc index 7e4c30ad0e..b96be784a1 100644 --- a/topics/identity-broker/overview.adoc +++ b/topics/identity-broker/overview.adoc @@ -26,11 +26,11 @@ image:../../images/identity_broker_flow.png[] If valid, it will import and create a new user or just skip that if the user already exists. If it is a new user, {{book.project.name}} may ask the identity provider for information about the user if that info doesn't already exist in the token. This is what we call _identity federation_. - If the user already exists Keycloak may ask him to link the identity returned from the identity provider with his existing account. + If the user already exists {{book.project.name}} may ask him to link the identity returned from the identity provider with his existing account. A process that we call _account linking_. - What exactly is done is configurable and can be specified by setup of <> . At the end of this step, Keycloak authenticates the user and issues its own token in order to access the requested resource in the service provider. -. Once the user is locally authenticated, Keycloak redirects the user to the service provider by sending the token previously issued during the local authentication. -. The service provider receives the token from Keycloak and allows access to the protected resource. + What exactly is done is configurable and can be specified by setup of <> . At the end of this step, {{book.project.name}} authenticates the user and issues its own token in order to access the requested resource in the service provider. +. Once the user is locally authenticated, {{book.project.name}} redirects the user to the service provider by sending the token previously issued during the local authentication. +. The service provider receives the token from {{book.project.name}} and allows access to the protected resource. There are some variations of this flow that we will talk about later. For instance, instead of presenting a list of identity providers, the client application request a specific one. diff --git a/topics/identity-broker/session-data.adoc b/topics/identity-broker/session-data.adoc index b6b9602c82..72c3a65325 100644 --- a/topics/identity-broker/session-data.adoc +++ b/topics/identity-broker/session-data.adoc @@ -1,7 +1,7 @@ === Available User Session Data -After a user logs in from the external IDP, there's some additional user session note data that Keycloak stores that you can access. +After a user logs in from the external IDP, there's some additional user session note data that {{book.project.name}} stores that you can access. This data can be propagated to the client requesting a login via the token or SAML assertion being passed back to it by using an appropriate client mapper. BROKER_PROVIDER_ID:: diff --git a/topics/identity-broker/tokens.adoc b/topics/identity-broker/tokens.adoc index b987e45542..c2978b2c9e 100644 --- a/topics/identity-broker/tokens.adoc +++ b/topics/identity-broker/tokens.adoc @@ -18,7 +18,7 @@ Authorization: Bearer {keycloak_access_token} An application must have authenticated with {{book.project.name}} and have received an access token. This access token will need to have the `broker` client-level role `read-token` set. This means that the user must have a role mapping for this role and the client application must have that role within its scope. -In this case, given that you are accessing an protected service in Keycloak, you need to send the access token issued by Keycloak during the user authentication. +In this case, given that you are accessing an protected service in {{book.project.name}}, you need to send the access token issued by {{book.project.name}} during the user authentication. In the broker configuration page you can automatically assign this role to newly imported users by turning on the `Stored Tokens Readable` switch. diff --git a/topics/Overview.adoc b/topics/overview.adoc similarity index 100% rename from topics/Overview.adoc rename to topics/overview.adoc diff --git a/topics/overview/features.adoc b/topics/overview/features.adoc index 8d8c814f6f..028405b4d2 100644 --- a/topics/overview/features.adoc +++ b/topics/overview/features.adoc @@ -26,7 +26,7 @@ * Deployable as a WAR, appliance, or on Openshift. Completely clusterable. * Multitenancy support. You can host and manage multiple realms for multiple organizations. In the same auth server and even within the same deployed application. -* Identity brokering/chaining. You can make the Keycloak server a child IDP to another SAML 2.0 or OpenID Connect IDP. +* Identity brokering/chaining. You can make the {{book.project.name}} server a child IDP to another SAML 2.0 or OpenID Connect IDP. * Token claim, assertion, and attribute mappings. You can map user attributes, roles, and role names however you want into a OIDC ID Token, Access Token, SAML attribute statements, etc. This feature allows you to basically tailor how you want auth responses to look. diff --git a/topics/realms/create.adoc b/topics/realms/create.adoc index 445bbc0124..b534338f4f 100644 --- a/topics/realms/create.adoc +++ b/topics/realms/create.adoc @@ -12,7 +12,7 @@ image:../../{{book.images}}/add-realm-menu.png[] This menu option will bring you to the `Add Realm` page. Specify the realm name you want to define and click the `Create` button. Alternatively you and import a JSON document that defines your new realm. We'll go over this in more detail in the -<> chapter. +<> chapter. .Create Realm image:../../{{book.images}}/create-realm.png[] diff --git a/topics/realms/ssl.adoc b/topics/realms/ssl.adoc index 2c6cbcd73b..c3fcf97249 100644 --- a/topics/realms/ssl.adoc +++ b/topics/realms/ssl.adoc @@ -1,4 +1,4 @@ -[[_ssl-mode]] +[[_ssl_modes]] === SSL Mode diff --git a/topics/realms/themes.adoc b/topics/realms/themes.adoc index 11a9c49223..70d7a171d5 100644 --- a/topics/realms/themes.adoc +++ b/topics/realms/themes.adoc @@ -1,4 +1,4 @@ - +[[_themes]] === Themes and Internationalization Themes allow you to change the look and feel of any UI in {{book.project.name}}. Themes are configured per realm. To change @@ -29,4 +29,4 @@ Every UI screen is internationalized in {{book.project.name}}. The default lang `Internationalization` switch on the `Theme` tab you can choose which locales you want to support and what the default locale will be. The next time a user logs in, they will be able to choose a language on the login page to use for the login screens, User Account Management UI, and Admin Console. The link:{{book.developerguide.link}}[{{book.developerguide.name}}] explains -how you can offer additional languages. \ No newline at end of file +how you can offer additional languages. diff --git a/topics/roles/client-scope.adoc b/topics/roles/client-scope.adoc index 4df5f938b4..46c589d8d5 100644 --- a/topics/roles/client-scope.adoc +++ b/topics/roles/client-scope.adoc @@ -1,4 +1,4 @@ -[[_client-scope]] +[[_client_scope]] === Client Scope @@ -20,7 +20,7 @@ image:../../{{book.images}}/full-client-scope.png[] As you can see from the picture, you can see that the effect roles of the scope are every declared role in the realm. To change this default behavior, you must explicitly turn off the `Full Scope Allowed` switch and declare the specific roles you want in each individual -client. Alternatively, you can also use <> +client. Alternatively, you can also use <> to define the scope for a whole set of clients. .Partial Scope diff --git a/topics/roles/user-role-mappings/default-roles.adoc b/topics/roles/user-role-mappings/default-roles.adoc index fa082d1361..dc5317c32d 100644 --- a/topics/roles/user-role-mappings/default-roles.adoc +++ b/topics/roles/user-role-mappings/default-roles.adoc @@ -2,7 +2,7 @@ ==== Default Roles Default roles allow you to automatically assign user role mappings when any user is newly created or imported through -<> or <>. +<> or <>. To specify _default roles_ go to the `Roles` left menu item, and click the `Default Roles` tab. .Default Roles diff --git a/topics/sso-protocols/oidc.adoc b/topics/sso-protocols/oidc.adoc index 1d1a3d001f..aface00786 100644 --- a/topics/sso-protocols/oidc.adoc +++ b/topics/sso-protocols/oidc.adoc @@ -55,7 +55,9 @@ to provide a client secret when they exchange the temporary codes for tokens. _ _Public_ clients are perfectly fine so long as HTTPS is strictly enforced and you are very strict about what redirect URIs are registered for the client. HTML5/Javascript clients actually always have to be _public_ clients because there is no way to transmit the client secret to them in a secure manner. Again, this is ok so long as you use HTTPS and strictly enforce redirect URI registration. This guide goes more detail -into this in the <> chapter. +into this in the + +// DOCS REMARK: Please update the cross-reference as it does not resolve correctly. <> chapter. ===== Implicit Flow diff --git a/topics/threat/open-redirect.adoc b/topics/threat/open-redirect.adoc index a070331aa6..b9925578f6 100644 --- a/topics/threat/open-redirect.adoc +++ b/topics/threat/open-redirect.adoc @@ -5,7 +5,7 @@ An attacker could use the end-user authorization endpoint and the redirect URI p An open redirector is an endpoint using a parameter to automatically redirect a user agent to the location specified by the parameter value without any validation. An attacker could utilize a user's trust in an authorization server to launch a phishing attack. -Keycloak requires that all registered applications and clients register at least one redirection uri pattern. +{{book.project.name}} requires that all registered applications and clients register at least one redirection uri pattern. Any time a client asks {{book.project.name}} to perform a redirect (on login or logout for example), {{book.project.name}} will check the redirect uri vs. the list of valid registered uri patterns. It is important that clients and applications register as specific a URI pattern as possible to mitigate open redirector attacks. diff --git a/topics/threat/scope.adoc b/topics/threat/scope.adoc index f15df59e71..3e69e6527e 100644 --- a/topics/threat/scope.adoc +++ b/topics/threat/scope.adoc @@ -4,5 +4,5 @@ By default, each new client applications has an unlimited scope. This means that every access token that is created for that client will contain all the permissions the user has. If the client gets compromised and the access token is leaked, then each system that the user has permission to access is now also compromised. It is highly suggested -that you limit the roles an access token is assigned by using the <> for each client. +that you limit the roles an access token is assigned by using the <> for each client. diff --git a/topics/threat/ssl.adoc b/topics/threat/ssl.adoc index 14f8e46bb2..76c32c8909 100644 --- a/topics/threat/ssl.adoc +++ b/topics/threat/ssl.adoc @@ -6,7 +6,7 @@ OAuth 2.0/OpenID Connect uses access tokens for security. Without SSL/HTTPS, attackers can sniff your network and obtain an access token. Once they have an access token they can do any operation that the token has been given permission for. -Keycloak has <>. +{{book.project.name}} has <>. SSL can be hard to set up, so out of the box, {{book.project.name}} allows non-HTTPS communication over private IP addresses like localhost, 192.168.x.x, and other private IP addresses. In production, you should make sure SSL is enabled and required across the board. diff --git a/topics/user-federation/ldap.adoc b/topics/user-federation/ldap.adoc index 3efaa5b3e6..9201162055 100755 --- a/topics/user-federation/ldap.adoc +++ b/topics/user-federation/ldap.adoc @@ -57,7 +57,7 @@ When you configure a secured connection URL to your LDAP store(for example `ldap The important thing is to properly configure a truststore on the {{book.project.name}} server side, because SSL won't work if {{book.project.name}} can't trust the SSL connection with LDAP ({{book.project.name}}. -The global truststore for the {{book.project.name}} can be configured with Truststore SPI. Please check out the link:{{book.installguide.link}}[book.installguide.name}} for more detail. +The global truststore for the {{book.project.name}} can be configured with Truststore SPI. Please check out the link:{{book.installguide.link}}[book.installguide.name}}] for more detail. If you don't configure truststore SPI, the truststore will fallback to the default mechanism provided by Java (either the file provided by system property `javax.net.ssl.trustStore` or the cacerts file from JDK if the system property is not set).