From 87daf5932cc29c3239d34f42f222dd06d934cf7c Mon Sep 17 00:00:00 2001 From: --add Date: Wed, 1 Jun 2016 14:19:54 +0530 Subject: [PATCH 1/4] fixing cross-references, adding and changing attribute id's --- README.adoc | 2 +- book.json | 4 ++-- topics/MigrationFromOlderVersions.adoc | 12 +++++++++--- topics/clients/client-templates.adoc | 8 ++++---- topics/clients/oidc/confidential.adoc | 2 +- topics/clients/oidc/service-accounts.adoc | 2 +- topics/groups/default-groups.adoc | 2 +- topics/identity-broker.adoc | 2 +- topics/identity-broker/mappers.adoc | 2 +- topics/{Overview.adoc => overview.adoc} | 0 topics/realms/create.adoc | 2 +- topics/realms/ssl.adoc | 2 +- topics/realms/themes.adoc | 4 ++-- topics/roles/client-scope.adoc | 4 ++-- topics/roles/user-role-mappings/default-roles.adoc | 2 +- topics/sso-protocols/oidc.adoc | 4 +++- topics/threat/scope.adoc | 2 +- 17 files changed, 32 insertions(+), 24 deletions(-) rename topics/{Overview.adoc => overview.adoc} (100%) 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/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/MigrationFromOlderVersions.adoc b/topics/MigrationFromOlderVersions.adoc index 956b7d8aa9..ff14d5dfe0 100755 --- a/topics/MigrationFromOlderVersions.adoc +++ b/topics/MigrationFromOlderVersions.adoc @@ -112,7 +112,9 @@ Keycloak SAML SP Client Adapter now requires a specific endpoint, `/saml` to be In previous releases we shipped with a default admin user with a default password, this has now been removed. If you are doing a new installation of 1.8 you will have to create an admin user as a first step. -This can be done easily by following the steps in <<_create_admin_user,Admin User>>. +This can be done easily by following the steps in + +// DOCS REMARK: Please add the chapter as the referenced topic does not exist. <<_create_admin_user,Admin User>>. ===== OAuth2 Token Introspection @@ -257,7 +259,9 @@ There are now 3 separate adapter downloads for WildFly, JBoss EAP and JBoss AS7: Make sure you grab the correct one. You also need to update standalone.xml as the extension module and subsystem definition has changed. -See <<_jboss_adapter_installation,Adapter Installation>> for details. +See + +// DOCS REMARK: Topic not found <<_jboss_adapter_installation,Adapter Installation>> for details. ==== Migrating from 1.2.0.Beta1 to 1.2.0.RC1 @@ -339,7 +343,9 @@ Facebook admin console). ==== Migrating from 1.1.0.Beta2 to 1.1.0.Final * WEB-INF/lib -+`standalone/configuration/providers`<<_providers,+providers>> ++`standalone/configuration/providers` + +// DOCS REMARK: Cross Reference not resolved. Please check and update <<_providers,+providers>> ==== Migrating from 1.1.0.Beta1 to 1.1.0.Beta2 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..2cdfb4d13a 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 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/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/Overview.adoc b/topics/overview.adoc similarity index 100% rename from topics/Overview.adoc rename to topics/overview.adoc 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/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. From 9a0ea41618f6fb4e1ea70eb65ffc7ba83b0f83b2 Mon Sep 17 00:00:00 2001 From: --add Date: Wed, 1 Jun 2016 14:36:38 +0530 Subject: [PATCH 2/4] Replaced the instances of Keycloak with {{book.project.name}} --- topics/MigrationFromOlderVersions.adoc | 40 ++++++++++---------- topics/clients/client-link.adoc | 2 +- topics/clients/client-saml.adoc | 2 +- topics/clients/oidc/service-accounts.adoc | 2 +- topics/clients/saml/idp-initiated-login.adoc | 2 +- topics/identity-broker/first-login-flow.adoc | 2 +- topics/identity-broker/overview.adoc | 8 ++-- topics/identity-broker/session-data.adoc | 2 +- topics/identity-broker/tokens.adoc | 2 +- topics/overview/features.adoc | 2 +- topics/threat/open-redirect.adoc | 2 +- topics/threat/ssl.adoc | 2 +- topics/user-federation/ldap.adoc | 2 +- 13 files changed, 35 insertions(+), 35 deletions(-) diff --git a/topics/MigrationFromOlderVersions.adoc b/topics/MigrationFromOlderVersions.adoc index ff14d5dfe0..403d6a0be8 100755 --- a/topics/MigrationFromOlderVersions.adoc +++ b/topics/MigrationFromOlderVersions.adoc @@ -1,12 +1,12 @@ == Migration from older versions -To upgrade to a new version of Keycloak first download and install the new version of Keycloak. +To upgrade to a new version of {{book.project.name}} first download and install the new version of {{book.project.name}}. You then have to migrate the database, keycloak-server.json, providers, themes and applications from the old version. === Migrate database -Keycloak provides automatic migration of the database. -It's highly recommended that you backup your database prior to upgrading Keycloak. +{{book.project.name}} provides automatic migration of the database. +It's highly recommended that you backup your database prior to upgrading {{book.project.name}}. To enable automatic upgrading of the database if you're using a relational database make sure `databaseSchema` is set to `update` for `connectionsJpa`: @@ -54,8 +54,8 @@ If there is you may have to update your themes accordingly. === Migrate application -If you deploy applications directly to the Keycloak server you should copy them to the new server. -For any applications including those not deployed directly to the Keycloak server you should upgrade the adapter. +If you deploy applications directly to the {{book.project.name}} server you should copy them to the new server. +For any applications including those not deployed directly to the {{book.project.name}} server you should upgrade the adapter. The version specific section below will mention if any changes are required to applications. === Version specific migration @@ -68,10 +68,10 @@ We've moved the themes and providers directories from `standalone/configuration/ If you have added custom themes and providers you need to move them to the new location. You also need to update `keycloak-server.json` as it's changed due to this. -===== Adapter Subsystems only bring in dependencies if keycloak is on +===== Adapter Subsystems only bring in dependencies if {{book.project.name}} is on -Previously, if you had installed our saml or oidc keycloak subsystem adapters into Wildfly or JBoss EAP, we would automatically include Keycloak client jars into EVERY application irregardless if you were using Keycloak or not. -These libraries are now only added to your deployment if you have keycloak authentication turned on for that adapter (via the subsystem, or auth-method in web.xml +Previously, if you had installed our saml or oidc keycloak subsystem adapters into Wildfly or JBoss EAP, we would automatically include {{book.project.name}} client jars into EVERY application irregardless if you were using {{book.project.name}} or not. +These libraries are now only added to your deployment if you have {{book.project.name}} authentication turned on for that adapter (via the subsystem, or auth-method in web.xml ===== Client Registration service endpoints moved @@ -104,7 +104,7 @@ You can turn off this behavior check adapter config switches. ===== SAML SP Client Adapter Changes -Keycloak SAML SP Client Adapter now requires a specific endpoint, `/saml` to be registered with your IDP. +{{book.project.name}} SAML SP Client Adapter now requires a specific endpoint, `/saml` to be registered with your IDP. ==== Migrating to 1.8.0 @@ -139,11 +139,11 @@ The `Direct Grants Only` flag was removed as if you enable Direct Access Grants We also added builtin client `admin-cli` to each realm. This client has `Direct Access Grants` enabled. -So if you're using Admin REST API or Keycloak admin-client, you should update your configuration to use `admin-cli` instead of `security-admin-console` as the latter one doesn't have direct access grants enabled anymore by default. +So if you're using Admin REST API or {{book.project.name}} admin-client, you should update your configuration to use `admin-cli` instead of `security-admin-console` as the latter one doesn't have direct access grants enabled anymore by default. ===== Option 'Update Profile On First Login' moved from Identity provider to Review Profile authenticator -In this version, we added `First Broker Login`, which allows you to specify what exactly should be done when new user is logged through Identity provider (or Social provider), but there is no existing Keycloak user yet linked to the social account. +In this version, we added `First Broker Login`, which allows you to specify what exactly should be done when new user is logged through Identity provider (or Social provider), but there is no existing {{book.project.name}} user yet linked to the social account. As part of this work, we added option `First Login Flow` to identity providers where you can specify the flow and then you can configure this flow under `Authentication` tab in admin console. We also removed the option `Update Profile On First Login` from the Identity provider settings and moved it to the configuration of `Review Profile` authenticator. @@ -166,8 +166,8 @@ So if you want to have any attribute available in `Review Profile` page, you wou ===== Option that refresh tokens are not reusable anymore -Old versions of Keycloak allowed reusing refresh tokens multiple times. -Keycloak still permits this, but also have an option `Revoke refresh token` to disallow it. +Old versions of {{book.project.name}} allowed reusing refresh tokens multiple times. +{{book.project.name}} still permits this, but also have an option `Revoke refresh token` to disallow it. Option is in in admin console under token settings. When a refresh token is used to obtain a new access token a new refresh token is also included. When option is enabled, then this new refresh token should be used next time the access token is refreshed. @@ -243,7 +243,7 @@ Changes are really minor, but were needed to improve performance of federation. ===== WildFly 9.0.0.Final -Following on from the distribution changes that was done in the last release the standalone download of Keycloak is now based on WildFly 9.0.0.Final. +Following on from the distribution changes that was done in the last release the standalone download of {{book.project.name}} is now based on WildFly 9.0.0.Final. This als affects the overlay which can only be deployed to WildFly 9.0.0.Final or JBoss EAP 6.4.0.GA. WildFly 8.2.0.Final is no longer supported for the server. @@ -267,11 +267,11 @@ See ===== Distribution changes -Keycloak is now available in 3 downloads: standalone, overlay and demo bundle. +{{book.project.name}} is now available in 3 downloads: standalone, overlay and demo bundle. The standalone is intended for production and non-JEE developers. -Overlay is aimed at adding Keycloak to an existing WildFly 8.2 or EAP 6.4 installation and is mainly for development. -Finally we have a demo (or dev) bundle that is aimed at developers getting started with Keycloak. -This bundle contains a WildFly server, with Keycloak server and adapter included. +Overlay is aimed at adding {{book.project.name}} to an existing WildFly 8.2 or EAP 6.4 installation and is mainly for development. +Finally we have a demo (or dev) bundle that is aimed at developers getting started with {{book.project.name}}. +This bundle contains a WildFly server, with {{book.project.name}} server and adapter included. It also contains all documentation and examples. ===== Database changed @@ -336,7 +336,7 @@ Again you don't need to care about migration of database from previous version s Both configuration of social providers and "social links" to your users will be converted to corresponding Identity providers. Only required action from you would be to change allowed `Redirect URI` in the admin console of particular 3rd party social providers. -You can first go to the Keycloak admin console and copy Redirect URI from the page where you configure the identity provider. +You can first go to the {{book.project.name}} admin console and copy Redirect URI from the page where you configure the identity provider. Then you can simply paste this as allowed Redirect URI to the admin console of 3rd party provider (IE. Facebook admin console). @@ -402,7 +402,7 @@ Facebook admin console). * DB Schema has changed. We have added export of the database to Beta 1, but not the ability to import the database from older versions. This will be supported in future releases. -* For all clients except bearer-only applications, you must specify at least one redirect uri. Keycloak +* For all clients except bearer-only applications, you must specify at least one redirect uri. {{book.project.name}} will not allow you to log in unless you have specified a valid redirect uri for that application. * Direct Grant API +`ON` 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/oidc/service-accounts.adoc b/topics/clients/oidc/service-accounts.adoc index 2cdfb4d13a..e41c3ec54a 100755 --- a/topics/clients/oidc/service-accounts.adoc +++ b/topics/clients/oidc/service-accounts.adoc @@ -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/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/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/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/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/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). From 606f9b067f4b917d6394df642fca81c1381e5449 Mon Sep 17 00:00:00 2001 From: --add Date: Wed, 1 Jun 2016 15:32:16 +0530 Subject: [PATCH 3/4] made changes as per the comments by Stian for PR#4 --- topics/MigrationFromOlderVersions.adoc | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/topics/MigrationFromOlderVersions.adoc b/topics/MigrationFromOlderVersions.adoc index 403d6a0be8..49e5aa16af 100755 --- a/topics/MigrationFromOlderVersions.adoc +++ b/topics/MigrationFromOlderVersions.adoc @@ -68,10 +68,10 @@ We've moved the themes and providers directories from `standalone/configuration/ If you have added custom themes and providers you need to move them to the new location. You also need to update `keycloak-server.json` as it's changed due to this. -===== Adapter Subsystems only bring in dependencies if {{book.project.name}} is on +===== Adapter Subsystems only bring in dependencies if keycloak is on Previously, if you had installed our saml or oidc keycloak subsystem adapters into Wildfly or JBoss EAP, we would automatically include {{book.project.name}} client jars into EVERY application irregardless if you were using {{book.project.name}} or not. -These libraries are now only added to your deployment if you have {{book.project.name}} authentication turned on for that adapter (via the subsystem, or auth-method in web.xml +These libraries are now only added to your deployment if you have keycloak authentication turned on for that adapter (via the subsystem, or auth-method in web.xml ===== Client Registration service endpoints moved @@ -114,7 +114,7 @@ In previous releases we shipped with a default admin user with a default passwor If you are doing a new installation of 1.8 you will have to create an admin user as a first step. This can be done easily by following the steps in -// DOCS REMARK: Please add the chapter as the referenced topic does not exist. <<_create_admin_user,Admin User>>. +// <<_create_admin_user,Admin User>>. ===== OAuth2 Token Introspection @@ -261,7 +261,7 @@ Make sure you grab the correct one. You also need to update standalone.xml as the extension module and subsystem definition has changed. See -// DOCS REMARK: Topic not found <<_jboss_adapter_installation,Adapter Installation>> for details. +//<<_jboss_adapter_installation,Adapter Installation>> for details. ==== Migrating from 1.2.0.Beta1 to 1.2.0.RC1 From 72fd8c0d477fae8e08ed3626fdf081c5d9828171 Mon Sep 17 00:00:00 2001 From: --add Date: Wed, 1 Jun 2016 15:55:38 +0530 Subject: [PATCH 4/4] enabled communtiy flag for the migration chapter, removed all the changes from the migration topic --- SUMMARY.adoc | 3 +- topics/MigrationFromOlderVersions.adoc | 48 +++++++++++--------------- 2 files changed, 23 insertions(+), 28 deletions(-) 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/topics/MigrationFromOlderVersions.adoc b/topics/MigrationFromOlderVersions.adoc index 49e5aa16af..956b7d8aa9 100755 --- a/topics/MigrationFromOlderVersions.adoc +++ b/topics/MigrationFromOlderVersions.adoc @@ -1,12 +1,12 @@ == Migration from older versions -To upgrade to a new version of {{book.project.name}} first download and install the new version of {{book.project.name}}. +To upgrade to a new version of Keycloak first download and install the new version of Keycloak. You then have to migrate the database, keycloak-server.json, providers, themes and applications from the old version. === Migrate database -{{book.project.name}} provides automatic migration of the database. -It's highly recommended that you backup your database prior to upgrading {{book.project.name}}. +Keycloak provides automatic migration of the database. +It's highly recommended that you backup your database prior to upgrading Keycloak. To enable automatic upgrading of the database if you're using a relational database make sure `databaseSchema` is set to `update` for `connectionsJpa`: @@ -54,8 +54,8 @@ If there is you may have to update your themes accordingly. === Migrate application -If you deploy applications directly to the {{book.project.name}} server you should copy them to the new server. -For any applications including those not deployed directly to the {{book.project.name}} server you should upgrade the adapter. +If you deploy applications directly to the Keycloak server you should copy them to the new server. +For any applications including those not deployed directly to the Keycloak server you should upgrade the adapter. The version specific section below will mention if any changes are required to applications. === Version specific migration @@ -70,7 +70,7 @@ You also need to update `keycloak-server.json` as it's changed due to this. ===== Adapter Subsystems only bring in dependencies if keycloak is on -Previously, if you had installed our saml or oidc keycloak subsystem adapters into Wildfly or JBoss EAP, we would automatically include {{book.project.name}} client jars into EVERY application irregardless if you were using {{book.project.name}} or not. +Previously, if you had installed our saml or oidc keycloak subsystem adapters into Wildfly or JBoss EAP, we would automatically include Keycloak client jars into EVERY application irregardless if you were using Keycloak or not. These libraries are now only added to your deployment if you have keycloak authentication turned on for that adapter (via the subsystem, or auth-method in web.xml ===== Client Registration service endpoints moved @@ -104,7 +104,7 @@ You can turn off this behavior check adapter config switches. ===== SAML SP Client Adapter Changes -{{book.project.name}} SAML SP Client Adapter now requires a specific endpoint, `/saml` to be registered with your IDP. +Keycloak SAML SP Client Adapter now requires a specific endpoint, `/saml` to be registered with your IDP. ==== Migrating to 1.8.0 @@ -112,9 +112,7 @@ You can turn off this behavior check adapter config switches. In previous releases we shipped with a default admin user with a default password, this has now been removed. If you are doing a new installation of 1.8 you will have to create an admin user as a first step. -This can be done easily by following the steps in - -// <<_create_admin_user,Admin User>>. +This can be done easily by following the steps in <<_create_admin_user,Admin User>>. ===== OAuth2 Token Introspection @@ -139,11 +137,11 @@ The `Direct Grants Only` flag was removed as if you enable Direct Access Grants We also added builtin client `admin-cli` to each realm. This client has `Direct Access Grants` enabled. -So if you're using Admin REST API or {{book.project.name}} admin-client, you should update your configuration to use `admin-cli` instead of `security-admin-console` as the latter one doesn't have direct access grants enabled anymore by default. +So if you're using Admin REST API or Keycloak admin-client, you should update your configuration to use `admin-cli` instead of `security-admin-console` as the latter one doesn't have direct access grants enabled anymore by default. ===== Option 'Update Profile On First Login' moved from Identity provider to Review Profile authenticator -In this version, we added `First Broker Login`, which allows you to specify what exactly should be done when new user is logged through Identity provider (or Social provider), but there is no existing {{book.project.name}} user yet linked to the social account. +In this version, we added `First Broker Login`, which allows you to specify what exactly should be done when new user is logged through Identity provider (or Social provider), but there is no existing Keycloak user yet linked to the social account. As part of this work, we added option `First Login Flow` to identity providers where you can specify the flow and then you can configure this flow under `Authentication` tab in admin console. We also removed the option `Update Profile On First Login` from the Identity provider settings and moved it to the configuration of `Review Profile` authenticator. @@ -166,8 +164,8 @@ So if you want to have any attribute available in `Review Profile` page, you wou ===== Option that refresh tokens are not reusable anymore -Old versions of {{book.project.name}} allowed reusing refresh tokens multiple times. -{{book.project.name}} still permits this, but also have an option `Revoke refresh token` to disallow it. +Old versions of Keycloak allowed reusing refresh tokens multiple times. +Keycloak still permits this, but also have an option `Revoke refresh token` to disallow it. Option is in in admin console under token settings. When a refresh token is used to obtain a new access token a new refresh token is also included. When option is enabled, then this new refresh token should be used next time the access token is refreshed. @@ -243,7 +241,7 @@ Changes are really minor, but were needed to improve performance of federation. ===== WildFly 9.0.0.Final -Following on from the distribution changes that was done in the last release the standalone download of {{book.project.name}} is now based on WildFly 9.0.0.Final. +Following on from the distribution changes that was done in the last release the standalone download of Keycloak is now based on WildFly 9.0.0.Final. This als affects the overlay which can only be deployed to WildFly 9.0.0.Final or JBoss EAP 6.4.0.GA. WildFly 8.2.0.Final is no longer supported for the server. @@ -259,19 +257,17 @@ There are now 3 separate adapter downloads for WildFly, JBoss EAP and JBoss AS7: Make sure you grab the correct one. You also need to update standalone.xml as the extension module and subsystem definition has changed. -See - -//<<_jboss_adapter_installation,Adapter Installation>> for details. +See <<_jboss_adapter_installation,Adapter Installation>> for details. ==== Migrating from 1.2.0.Beta1 to 1.2.0.RC1 ===== Distribution changes -{{book.project.name}} is now available in 3 downloads: standalone, overlay and demo bundle. +Keycloak is now available in 3 downloads: standalone, overlay and demo bundle. The standalone is intended for production and non-JEE developers. -Overlay is aimed at adding {{book.project.name}} to an existing WildFly 8.2 or EAP 6.4 installation and is mainly for development. -Finally we have a demo (or dev) bundle that is aimed at developers getting started with {{book.project.name}}. -This bundle contains a WildFly server, with {{book.project.name}} server and adapter included. +Overlay is aimed at adding Keycloak to an existing WildFly 8.2 or EAP 6.4 installation and is mainly for development. +Finally we have a demo (or dev) bundle that is aimed at developers getting started with Keycloak. +This bundle contains a WildFly server, with Keycloak server and adapter included. It also contains all documentation and examples. ===== Database changed @@ -336,16 +332,14 @@ Again you don't need to care about migration of database from previous version s Both configuration of social providers and "social links" to your users will be converted to corresponding Identity providers. Only required action from you would be to change allowed `Redirect URI` in the admin console of particular 3rd party social providers. -You can first go to the {{book.project.name}} admin console and copy Redirect URI from the page where you configure the identity provider. +You can first go to the Keycloak admin console and copy Redirect URI from the page where you configure the identity provider. Then you can simply paste this as allowed Redirect URI to the admin console of 3rd party provider (IE. Facebook admin console). ==== Migrating from 1.1.0.Beta2 to 1.1.0.Final * WEB-INF/lib -+`standalone/configuration/providers` - -// DOCS REMARK: Cross Reference not resolved. Please check and update <<_providers,+providers>> ++`standalone/configuration/providers`<<_providers,+providers>> ==== Migrating from 1.1.0.Beta1 to 1.1.0.Beta2 @@ -402,7 +396,7 @@ Facebook admin console). * DB Schema has changed. We have added export of the database to Beta 1, but not the ability to import the database from older versions. This will be supported in future releases. -* For all clients except bearer-only applications, you must specify at least one redirect uri. {{book.project.name}} +* For all clients except bearer-only applications, you must specify at least one redirect uri. Keycloak will not allow you to log in unless you have specified a valid redirect uri for that application. * Direct Grant API +`ON`