diff --git a/.gitignore b/.gitignore index 06811d568b..5953f758d6 100644 --- a/.gitignore +++ b/.gitignore @@ -27,7 +27,7 @@ catalog.xml # Packages # ############ # it's better to unpack these files and commit the raw source -# git has its own built in compression methods +# git has its own built-in compression methods *.7z *.dmg *.gz diff --git a/topics/MigrationFromOlderVersions.adoc b/topics/MigrationFromOlderVersions.adoc index 9f974b6723..f0e343e103 100644 --- a/topics/MigrationFromOlderVersions.adoc +++ b/topics/MigrationFromOlderVersions.adoc @@ -15,14 +15,14 @@ migration for a CR so we can resolve any potential issues before the Final is re === Migrate and convert keycloak-server.json You should copy `standalone/configuration/keycloak-server.json` from the old version to make sure any configuration changes you've done are added to the new installation. -The version specific section below will list any changes done to this file that you have to do when upgrading from one version to another. +The version specific section below will list any changes done to this file that you have to do when upgrading from one version to another. Keycloak is moving away from the use of keycloak-server.json. For this release, the server will still work if this file is in `standalone/configuration/keycloak-server.json`, but it is highly recommended that you convert to using standalone.xml, standalone-ha.xml, or domain.xml for configuration. We may soon remove support for keycloak-server.json. -To convert your keycloak-server.json, you will use a new jboss-cli operation called `migrate-json`. +To convert your keycloak-server.json, you will use a new jboss-cli operation called `migrate-json`. It is recommended that you run this operation while the server is not running. The `migrate-json` operation assumes you are migrating with an xml configuration file from an old version. For example, @@ -35,7 +35,7 @@ tags under the keycloak subsystem. Before migration, your keycloak subsystem sh auth ----- +---- The jboss-cli tool is discussed in detail in link:{{book.installguide.link}}[{{book.installguide.name}}]. @@ -62,7 +62,7 @@ issue the `migrate-json` operation against the running domain controller. If you choose not to stop the Keycloak server, the operation will still work, but your changes will not take affect until the Keycloak server is restarted. -Domain mode migration requires that you use the `file` parameter to upload your +Domain mode migration requires that you use the `file` parameter to upload your keycloak-server.json from a local directory. The example below shows connecting to localhost. You will need to substitute the address of your domain controller. @@ -96,7 +96,7 @@ the default `connectionsJpa` provider: ----- +---- .Equivalent CLI command for above [source] @@ -148,19 +148,19 @@ the database will be checked at startup and if it is not migrated the server wil If you have implemented any SPI providers you need to copy them to the new server. The version specific section below will mention if any of the SPI's have changed. -If they have you may have to update your code accordingly. +If they have you may have to update your code accordingly. === Migrate themes If you have created a custom theme you need to copy them to the new server. The version specific section below will mention if changes have been made to themes. -If there is you may have to update your themes accordingly. +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. -The version specific section below will mention if any changes are required to applications. +The version specific section below will mention if any changes are required to applications. === Version specific migration @@ -266,45 +266,45 @@ through loadbalancer but send them to local Keycloak server directly) you may ne We've moved the themes and providers directories from `standalone/configuration/themes` and `standalone/configuration/providers` to `themes` and `providers` respectively. 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. +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 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 +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 -The Client Registration service endpoints have been moved from `{realm}/clients` to `{realm}/clients-registrations`. +The Client Registration service endpoints have been moved from `{realm}/clients` to `{realm}/clients-registrations`. ===== Session state parameter in authentication response renamed -In the OpenID Connect authentication response we used to return the session state as `session-state` this is not correct according to the specification and has been renamed to `session_state`. +In the OpenID Connect authentication response we used to return the session state as `session-state` this is not correct according to the specification and has been renamed to `session_state`. ===== Deprecated OpenID Connect endpoints In 1.2 we deprecated a number of endpoints that where not consistent with the OpenID Connect specifications, these have now been removed. -This also applies to the validate token endpoints that was replaced with the new introspect endpoint in 1.8. +This also applies to the validate token endpoints that was replaced with the new introspect endpoint in 1.8. ===== Updates to theme templates -Feedback in template.ftl has been moved and format has changed slightly. +Feedback in template.ftl has been moved and format has changed slightly. ===== Module and Source Code Re-org Most of our modules and source code have been consolidated into two maven modules: keycloak-server-spi and keycloak-services. SPI interfaces are in server-spi, implementations are in keycloak-services. All JPA dependent modules have been consolidated under keycloak-model-jpa. -Same goes with mongo and Infinispan under modules keycloak-model-mongo and keycloak-model-infinispan. +Same goes with mongo and Infinispan under modules keycloak-model-mongo and keycloak-model-infinispan. ===== For adapters, session id changed after login To plug a security attack vector, for platforms that support it (Tomcat 8, Undertow/Wildfly, Jetty 9), the Keycloak OIDC and SAML adapters will change the session id after login. -You can turn off this behavior check adapter config switches. +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. +Keycloak SAML SP Client Adapter now requires a specific endpoint, `/saml` to be registered with your IDP. ==== Migrating to 1.8.0 @@ -312,53 +312,53 @@ 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 <<_create_admin_user,Admin User>>. ===== OAuth2 Token Introspection In order to add more compliance with OAuth2 specification, we added a new endpoint for token introspection. -The new endpoint can reached at `/realms/{realm}/protocols/openid-connect/token/introspect` and it is solely based on `RFC-7662.` +The new endpoint can reached at `/realms/{realm}/protocols/openid-connect/token/introspect` and it is solely based on `RFC-7662.` The `/realms/{realm}/protocols/openid-connect/validate` endpoint is now deprecated and we strongly recommend you to move to the new introspection endpoint as soon as possible. -The reason for this change is that RFC-7662 provides a more standard and secure introspection endpoint. +The reason for this change is that RFC-7662 provides a more standard and secure introspection endpoint. The new token introspection URL can now be obtained from OpenID Connect Provider's configuration at `/realms/{realm}/.well-known/openid-configuration`. There you will find a claim with name `token_introspection_endpoint` within the response. -Only `confidential clients` are allowed to invoke the new endpoint, where these clients will be usually acting as a resource server and looking for token metadata in order to perform local authorization checks. +Only `confidential clients` are allowed to invoke the new endpoint, where these clients will be usually acting as a resource server and looking for token metadata in order to perform local authorization checks. ==== Migrating to 1.7.0.CR1 ===== Direct access grants disabled by default for clients -In order to add more compliance with OpenID Connect specification, we added flags into admin console to Client Settings page, where you can enable/disable various kinds of OpenID Connect/OAuth2 flows (Standard flow, Implicit flow, Direct Access Grants, Service Accounts). As part of this, we have `Direct Access Grants` (corresponds to OAuth2 `Resource Owner Password Credentials Grant`) disabled by default for new clients. +In order to add more compliance with OpenID Connect specification, we added flags into admin console to Client Settings page, where you can enable/disable various kinds of OpenID Connect/OAuth2 flows (Standard flow, Implicit flow, Direct Access Grants, Service Accounts). As part of this, we have `Direct Access Grants` (corresponds to OAuth2 `Resource Owner Password Credentials Grant`) disabled by default for new clients. Clients migrated from previous version have `Direct Access Grants` enabled just if they had flag `Direct Grants Only` on. -The `Direct Grants Only` flag was removed as if you enable Direct Access Grants and disable both Standard+Implicit flow, you will achieve same effect. +The `Direct Grants Only` flag was removed as if you enable Direct Access Grants and disable both Standard+Implicit flow, you will achieve same effect. -We also added builtin client `admin-cli` to each realm. +We also added built-in 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 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 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. +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. -So once you specify which flow should be used for your Identity provider (by default it's `First Broker Login` flow), you go to `Authentication` tab, select the flow and then you configure the option under `Review Profile` authenticator. +So once you specify which flow should be used for your Identity provider (by default it's `First Broker Login` flow), you go to `Authentication` tab, select the flow and then you configure the option under `Review Profile` authenticator. ===== Element 'form-error-page' in web.xml not supported anymore form-error-page in web.xml will no longer work for client adapter authentication errors. You must define an error-page for the various HTTP error codes. -See documentation for more details if you want to catch and handle adapter error conditions. +See documentation for more details if you want to catch and handle adapter error conditions. ===== IdentityProviderMapper changes There is no change in the interface itself or method signatures. However there is some change in behavior. We added `First Broker Login` flow in this release and the method `IdentityProviderMapper.importNewUser` is now called after `First Broker Login` flow is finished. -So if you want to have any attribute available in `Review Profile` page, you would need to use the method `preprocessFederatedIdentity` instead of `importNewUser` . You can set any attribute by invoke `BrokeredIdentityContext.setUserAttribute` and that will be available on `Review profile` page. +So if you want to have any attribute available in `Review Profile` page, you would need to use the method `preprocessFederatedIdentity` instead of `importNewUser` . You can set any attribute by invoke `BrokeredIdentityContext.setUserAttribute` and that will be available on `Review profile` page. ==== Migrating to 1.6.0.Final @@ -369,7 +369,7 @@ Keycloak still permits this, but also have an option `Revoke refresh token` to d 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. -It won't be possible to reuse old refresh token multiple times. +It won't be possible to reuse old refresh token multiple times. ===== Some packages renamed @@ -377,21 +377,21 @@ We did a bit of restructure and renamed some packages. It is mainly about renaming internal packages of util classes. The most important classes used in your application ( for example AccessToken or KeycloakSecurityContext ) as well as the SPI are still unchanged. However there is slight chance that you will be affected and will need to update imports of your classes. -For example if you are using multitenancy and KeycloakConfigResolver, you will be affected as for example class HttpFacade was moved to different package - it is `org.keycloak.adapters.spi.HttpFacade` now. +For example if you are using multitenancy and KeycloakConfigResolver, you will be affected as for example class HttpFacade was moved to different package - it is `org.keycloak.adapters.spi.HttpFacade` now. ===== Persisting user sessions We added support for offline tokens in this release, which means that we are persisting "offline" user sessions into database now. If you are not using offline tokens, nothing will be persisted for you, so you don't need to care about worse performance for more DB writes. -However in all cases, you will need to update `standalone/configuration/keycloak-server.json` and add `userSessionPersister` like this: +However in all cases, you will need to update `standalone/configuration/keycloak-server.json` and add `userSessionPersister` like this: [source] ---- "userSessionPersister": { "provider": "jpa" }, ----- -If you want sessions to be persisted in Mongo instead of classic RDBMS, use provider `mongo` instead. +---- +If you want sessions to be persisted in Mongo instead of classic RDBMS, use provider `mongo` instead. ==== Migrating to 1.5.0.Final @@ -401,7 +401,7 @@ Infinispan is now the default and only realm and user cache providers. In non-clustered mode a local Infinispan cache is used. We've also removed our custom in-memory cache and the no cache providers. If you have realmCache or userCache set in keycloak-server.json to mem or none please remove these. -As Infinispan is the only provider there's no longer any need for the realmCache and userCache objects so these can be removed. +As Infinispan is the only provider there's no longer any need for the realmCache and userCache objects so these can be removed. ===== Uses Session providers @@ -409,55 +409,55 @@ Infinispan is now the default and only user session provider. In non-clustered mode a local Infinispan cache is used. We've also removed the JPA and Mongo user session providers. If you have userSession set in keycloak-server.json to mem, jpa or mongo please remove it. -As Infinispan is the only provider there's no longer any need for the userSession object so it can be removed. +As Infinispan is the only provider there's no longer any need for the userSession object so it can be removed. For anyone that wants to achieve increased durability of user sessions this can be achieved by configuring the user session cache with more than one owner or use a replicated cache. -It's also possible to configure Infinispan to persist caches, although that would have impacts on performance. +It's also possible to configure Infinispan to persist caches, although that would have impacts on performance. ===== Contact details removed from registration and account management In the default theme we have now removed the contact details from the registration page and account management. The admin console now lists all the users attributes, not just contact specific attributes. The admin console also has the ability to add/remove attributes to a user. -If you want to add contact details, please refer to the address theme included in the examples. +If you want to add contact details, please refer to the address theme included in the examples. ==== Migrating to 1.3.0.Final ===== Direct Grant API always enabled In the past Direct Grant API (or Resource Owner Password Credentials) was disabled by default and there was an option on a realm to enable it. -The Direct Grant API is now always enabled and the option to enable/disable for a realm is removed. +The Direct Grant API is now always enabled and the option to enable/disable for a realm is removed. ===== Database changed There are again few database changes. -Remember to backup your database prior to upgrading. +Remember to backup your database prior to upgrading. ===== UserFederationProvider changed There are few minor changes in UserFederationProvider interface. You may need to sync your implementation when upgrade to newer version and upgrade few methods, which has changed signature. -Changes are really minor, but were needed to improve performance of federation. +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. This also 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. +WildFly 8.2.0.Final is no longer supported for the server. ===== WildFly, JBoss EAP and JBoss AS7 adapters -There are now 3 separate adapter downloads for WildFly, JBoss EAP and JBoss AS7: +There are now 3 separate adapter downloads for WildFly, JBoss EAP and JBoss AS7: * eap6 * wf9 * wf8 -* as7 +* as7 -Make sure you grab the correct one. +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 @@ -468,73 +468,73 @@ 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. -It also contains all documentation and examples. +It also contains all documentation and examples. ===== Database changed This release contains again a number of changes to the database. The biggest one is Application and OAuth client merge. -Remember to backup your database prior to upgrading. +Remember to backup your database prior to upgrading. ===== Application and OAuth client merge Application and OAuth clients are now merged into `Clients`. The UI of admin console is updated and database as well. Your data from database should be automatically updated. -The previously set Applications will be converted into Clients with `Consent required` switch off and OAuth Clients will be converted into Clients with this switch on. +The previously set Applications will be converted into Clients with `Consent required` switch off and OAuth Clients will be converted into Clients with this switch on. ==== Migrating from 1.1.0.Final to 1.2.0.Beta1 ===== Database changed This release contains a number of changes to the database. -Remember to backup your database prior to upgrading. +Remember to backup your database prior to upgrading. ===== `iss` in access and id tokens The value of `iss` claim in access and id tokens have changed from `realm name` to `realm url`. This is required by OpenID Connect specification. If you're using our adapters there's no change required, other than if you've been using bearer-only without specifying `auth-server-url` you have to add it now. -If you're using another library (or RSATokenVerifier) you need to make the corresponding changes when verifying `iss`. +If you're using another library (or RSATokenVerifier) you need to make the corresponding changes when verifying `iss`. ===== OpenID Connect endpoints To comply with OpenID Connect specification the authentication and token endpoints have been changed to having a single authentication endpoint and a single token endpoint. As per-spec `response_type` and `grant_type` parameters are used to select the required flow. -The old endpoints (`/realms/{realm}/protocols/openid-connect/login`, `/realms/{realm}/protocols/openid-connect/grants/access`, `/realms/{realm}/protocols/openid-connect/refresh`, `/realms/{realm}/protocols/openid-connect/access/codes)` are now deprecated and will be removed in a future version. +The old endpoints (`/realms/{realm}/protocols/openid-connect/login`, `/realms/{realm}/protocols/openid-connect/grants/access`, `/realms/{realm}/protocols/openid-connect/refresh`, `/realms/{realm}/protocols/openid-connect/access/codes)` are now deprecated and will be removed in a future version. ===== Theme changes The layout of themes have changed. The directory hierarchy used to be `type/name` this is now changed to `name/type`. For example a login theme named `sunrise` used to be deployed to `standalone/configuration/themes/login/sunrise`, which is now moved to `standalone/configuration/themes/sunrise/login`. -This change was done to make it easier to have group the different types for the same theme into one folder. +This change was done to make it easier to have group the different types for the same theme into one folder. If you deployed themes as a JAR in the past you had to create a custom theme loader which required Java code. This has been simplified to only requiring a plain text file (`META-INF/keycloak-themes.json`) to describe the themes included in a JAR. -See the <<_themes,themes>> section in the docs for more information. +See the <<_themes,themes>> section in the docs for more information. ===== Claims changes Previously there was `Claims` tab in admin console for application and OAuth clients. This was used to configure which attributes should go into access token for particular application/client. -This was removed and replaced with <<_mappers,Protocol mappers>>, which are more flexible. +This was removed and replaced with <<_mappers,Protocol mappers>>, which are more flexible. You don't need to care about migration of database from previous version. -We did migration scripts for both RDBMS and Mongo, which should ensure that claims configured for particular application/client will be converted into corresponding protocol mappers (Still it's safer to backup DB before migrating to newer version though). Same applies for exported JSON representation from previous version. +We did migration scripts for both RDBMS and Mongo, which should ensure that claims configured for particular application/client will be converted into corresponding protocol mappers (Still it's safer to backup DB before migrating to newer version though). Same applies for exported JSON representation from previous version. ===== Social migration to identity brokering We refactored social providers SPI and replaced it with <<_identity_broker,identity brokering SPI>>, which is more flexible. -The `Social` tab in admin console is renamed to `Identity Provider` tab. +The `Social` tab in admin console is renamed to `Identity Provider` tab. Again you don't need to care about migration of database from previous version similarly like for Claims/protocol mappers. -Both configuration of social providers and "social links" to your users will be converted to corresponding Identity providers. +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. Then you can simply paste this as allowed Redirect URI to the admin console of 3rd party provider (IE. -Facebook admin console). +Facebook admin console). ==== Migrating from 1.1.0.Beta2 to 1.1.0.Final diff --git a/topics/account.adoc b/topics/account.adoc index 9d5a774937..0c5f082838 100644 --- a/topics/account.adoc +++ b/topics/account.adoc @@ -2,7 +2,7 @@ == User Account Service -{{book.project.name}} has a built in User Account Service which every user has access to. This service allows users to manage their account, +{{book.project.name}} has a built-in User Account Service which every user has access to. This service allows users to manage their account, change their credentials, update their profile, and view their login sessions. The URL to this service is `/auth/realms/\{realm-name}/account`. .Account Service diff --git a/topics/authentication.adoc b/topics/authentication.adoc index f4e6a26c71..db4ebcaf12 100644 --- a/topics/authentication.adoc +++ b/topics/authentication.adoc @@ -4,4 +4,4 @@ There are a few features you should be aware of when configuring authentication for your realm. Many organizations have strict password and OTP policies that you can enforce via settings in the Admin Console. You may or may not want to require different credential types for authentication. You may want to give users the option to login via -Kerberos or disable or enable various built in credential types. This chapter covers all of these topics. \ No newline at end of file +Kerberos or disable or enable various built-in credential types. This chapter covers all of these topics. diff --git a/topics/authentication/kerberos.adoc b/topics/authentication/kerberos.adoc index b92e8e0794..a2b9538e86 100644 --- a/topics/authentication/kerberos.adoc +++ b/topics/authentication/kerberos.adoc @@ -7,9 +7,9 @@ SPNEGO (Simple and Protected GSSAPI Negotiation Mechanism) is used to authentica has been authenticated when logging-in his session. For non-web cases or when ticket is not available during login, {{book.project.name}} also supports login with Kerberos username/password. -A typical use case for web authentication is the following: +A typical use case for web authentication is the following: -. User logs into his desktop (Such as a Windows machine in Active Directory domain or Linux machine with Kerberos integration enabled). +. User logs into his desktop (Such as a Windows machine in Active Directory domain or Linux machine with Kerberos integration enabled). . User then uses his browser (IE/Firefox/Chrome) to access a web application secured by {{book.project.name}}. . Application redirects to {{book.project.name}} login. . {{book.project.name}} renders HTML login screen together with status 401 and HTTP header `WWW-Authenticate: Negotiate` @@ -23,58 +23,58 @@ A typical use case for web authentication is the following: The fact that {{book.project.name}} was authenticated through Kerberos is hidden from the application. So {{book.project.name}} acts as broker to Kerberos/SPNEGO login. -For setup there are 3 main parts: +For setup there are 3 main parts: -. Setup and configuration of Kerberos server (KDC) +. Setup and configuration of Kerberos server (KDC) . Setup and configuration of {{book.project.name}} server -. Setup and configuration of client machines +. Setup and configuration of client machines ==== Setup of Kerberos server This is platform dependent. Exact steps depend on your OS and the Kerberos vendor you're going to use. -Consult Windows Active Directory, MIT Kerberos and your OS documentation for how exactly to setup and configure Kerberos server. +Consult Windows Active Directory, MIT Kerberos and your OS documentation for how exactly to setup and configure Kerberos server. -At least you will need to: +At least you will need to: * Add some user principals to your Kerberos database. - You can also integrate your Kerberos with LDAP, which means that user accounts will be provisioned from LDAP server. + You can also integrate your Kerberos with LDAP, which means that user accounts will be provisioned from LDAP server. * Add service principal for "HTTP" service. For example if your {{book.project.name}} server will be running on `www.mydomain.org` you may need to add principal `HTTP/www.mydomain.org@MYDOMAIN.ORG` assuming that MYDOMAIN.ORG will be your Kerberos realm. + For example on MIT Kerberos you can run a "kadmin" session. -If you are on the same machine where is MIT Kerberos, you can simply use the command: +If you are on the same machine where is MIT Kerberos, you can simply use the command: [source] ---- sudo kadmin.local ----- -Then add HTTP principal and export his key to a keytab file with the commands like: +---- +Then add HTTP principal and export his key to a keytab file with the commands like: [source] ---- addprinc -randkey HTTP/www.mydomain.org@MYDOMAIN.ORG ktadd -k /tmp/http.keytab HTTP/www.mydomain.org@MYDOMAIN.ORG ----- +---- The Keytab file `/tmp/http.keytab` will need to be accessible on the host where {{book.project.name}} server will be running. - + ==== Setup and configuration of {{book.project.name}} server You need to install a kerberos client on your machine. This is also platform dependent. If you are on Fedora, Ubuntu or RHEL, you can install the package `freeipa-client`, which contains a Kerberos client and several other utilities. Configure the kerberos client (on linux it's in file `/etc/krb5.conf` ). You need to put your Kerberos realm and at least configure the HTTP domains your server will be running on. -For the example realm MYDOMAIN.ORG you may configure the `domain_realm` section like this: +For the example realm MYDOMAIN.ORG you may configure the `domain_realm` section like this: [source] ---- [domain_realm] .mydomain.org = MYDOMAIN.ORG mydomain.org = MYDOMAIN.ORG ----- - +---- + Next you need to export the keytab file with the HTTP principal and make sure the file is accessible to the process under which {{book.project.name}} server is running. For production, it's ideal if it's readable just by this process and not by someone else. For the MIT Kerberos example above, we already exported keytab to `/tmp/http.keytab` . If your KDC and {{book.project.name}} are running on same host, @@ -107,7 +107,7 @@ Turning on the switch `Allow Kerberos authentication` will make {{book.project.n be imported into the {{book.project.name}} environment. If your Kerberos solution is not backed by an LDAP server, you have to use the `Kerberos` User Storage Federation Provider. Go to the `User Federation` -left menu item and select `Kerberos` from the right `Add provider` select box. +left menu item and select `Kerberos` from the `Add provider` select box. .Kerberos User Storage Provider image:../../{{book.images}}/kerberos-provider.png[] @@ -122,19 +122,19 @@ Additionally they need to enable SPNEGO login support in their browser. See link:http://www.microhowto.info/howto/configure_firefox_to_authenticate_using_spnego_and_kerberos.html[configuring Firefox for Kerberos] if you are using that browser. URI `.mydomain.org` must be allowed in the `network.negotiate-auth.trusted-uris` config option. -In a Windows domain, clients usually don't need to configure anything special as IE is already able to participate in SPNEGO authentication for the Windows domain. +In a Windows domain, clients usually don't need to configure anything special as IE is already able to participate in SPNEGO authentication for the Windows domain. {% if book.community %} ==== Example setups -For easier testing with Kerberos, we provided some example setups to test. +For easier testing with Kerberos, we provided some example setups to test. ===== {{book.project.name}} and FreeIPA docker image Once you install https://www.docker.com/[docker], you can run docker image with http://www.freeipa.org/[FreeIPA] server installed. FreeIPA provides integrated security solution with MIT Kerberos and 389 LDAP server among other things . The image provides also {{book.project.name}} server configured with LDAP Federation provider and enabled SPNEGO/Kerberos authentication against the FreeIPA server. -See details https://github.com/mposolda/keycloak-freeipa-docker/blob/master/README.md[here] . +See details https://github.com/mposolda/keycloak-freeipa-docker/blob/master/README.md[here] . ===== ApacheDS testing Kerberos server @@ -192,6 +192,6 @@ WARNING: Credential delegation has some security implications so only use it if If you have issues, we recommend that you enable additional logging to debug the problem: -* Enable `Debug` flag in admin console for Kerberos or LDAP federation providers -* Enable TRACE logging for category `org.keycloak` in logging section of `standalone/configuration/standalone.xml` to receive more info `standalone/log/server.log` -* Add system properties `-Dsun.security.krb5.debug=true` and `-Dsun.security.spnego.debug=true` +* Enable `Debug` flag in admin console for Kerberos or LDAP federation providers +* Enable TRACE logging for category `org.keycloak` in logging section of `standalone/configuration/standalone.xml` to receive more info `standalone/log/server.log` +* Add system properties `-Dsun.security.krb5.debug=true` and `-Dsun.security.spnego.debug=true` diff --git a/topics/clients/oidc/service-accounts.adoc b/topics/clients/oidc/service-accounts.adoc index 874dff3366..32a73ac347 100644 --- a/topics/clients/oidc/service-accounts.adoc +++ b/topics/clients/oidc/service-accounts.adoc @@ -2,7 +2,7 @@ === Service Accounts -Each OIDC client has a built in _service account_ which allows it to obtain an access token. +Each OIDC client has a built-in _service account_ which allows it to obtain an access token. This is covered in the OAuth 2.0 specifiation under <>. To use this feature you must set the <> of your client to `confidential`. When you do this, the `Service Accounts Enabled` switch will appear. You need to turn on this switch. Also make sure that you have diff --git a/topics/events.adoc b/topics/events.adoc index 1d6a2a0cc4..a2f465de0f 100644 --- a/topics/events.adoc +++ b/topics/events.adoc @@ -3,6 +3,5 @@ {{book.project.name}} provides a rich set of auditing capabilities. Every single login action can be recorded and stored in the database and reviewed in the Admin Console. All admin actions can also be recorded and reviewed. There is also a Listener SPI -with which plugins can listen for these events and perform some action. Built in listeners include a simple log file and the ability +with which plugins can listen for these events and perform some action. Built-in listeners include a simple log file and the ability to send an email if an event occurs. - diff --git a/topics/events/login.adoc b/topics/events/login.adoc index 5dd9d633cc..b71438aa2d 100644 --- a/topics/events/login.adoc +++ b/topics/events/login.adoc @@ -60,7 +60,7 @@ For all events there is a corresponding error event. ==== Event Listener -Event listeners listen for events and perform an action based on that event. There are two built in +Event listeners listen for events and perform an action based on that event. There are two built-in listeners that come with {{book.project.name}}: Logging Event Listener and Email Event Listener. The Logging Event Listener writes to a log file whenever an error event occurs and is enabled by default. @@ -90,7 +90,7 @@ The Email Event Listener only supports the following events at the moment: To enable the Email Listener go to the `Config` tab and click on the `Event Listeners` field. This will show a drop down list box where you can select email. -You can exclude one or more events by editing the `standalone.xml`, `standalone-ha.xml`, or `domain.xml` +You can exclude one or more events by editing the `standalone.xml`, `standalone-ha.xml`, or `domain.xml` that comes with your distribution and adding for example: [source,xml] @@ -104,8 +104,5 @@ that comes with your distribution and adding for example: ---- -See the link:{{book.installguide.link}}[{{book.installguide.name}}] for more details on +See the link:{{book.installguide.link}}[{{book.installguide.name}}] for more details on where the `standalone.xml`, `standalone-ha.xml`, or `domain.xml` file lives. - - - diff --git a/topics/login-settings.adoc b/topics/login-settings.adoc index 794d5d8888..43311d91fa 100644 --- a/topics/login-settings.adoc +++ b/topics/login-settings.adoc @@ -1,4 +1,4 @@ == Login Page Settings -There are several nice built in login page features you can enable if you need the functionality. \ No newline at end of file +There are several nice built-in login page features you can enable if you need the functionality. diff --git a/topics/overview/concepts.adoc b/topics/overview/concepts.adoc index 35a0282ca4..16c0d051a3 100755 --- a/topics/overview/concepts.adoc +++ b/topics/overview/concepts.adoc @@ -56,7 +56,7 @@ assertion:: Information about a user. This usually pertains to an XML blob that is included in a SAML authentication response that provided identity metadata about an authenticated user. service account:: - Each client has a built in service account which allows it to obtain an access token. + Each client has a built-in service account which allows it to obtain an access token. direct grant:: A way for a client to obtain an access token on behalf of a user via a REST invocation. protocol mappers:: diff --git a/topics/user-federation/ldap.adoc b/topics/user-federation/ldap.adoc index 07e27a1154..ce9d936aef 100644 --- a/topics/user-federation/ldap.adoc +++ b/topics/user-federation/ldap.adoc @@ -21,10 +21,10 @@ have the ability to modify user metadata. Depending on your setup you may or ma READONLY:: Username, email, first name, last name, and other mapped attributes will be unchangeable. {{book.project.name}} will show an error anytime anybody tries to update these fields. - Also, password updates will not be supported. + Also, password updates will not be supported. WRITABLE:: - Username, email, first name, last name, and other mapped attributes and passwords can all be updated and will be synchronized automatically with your LDAP store. + Username, email, first name, last name, and other mapped attributes and passwords can all be updated and will be synchronized automatically with your LDAP store. UNSYNCED:: Any changes to username, email, first name, last name, and passwords will be stored in {{book.project.name}} local storage. @@ -34,13 +34,13 @@ UNSYNCED:: ==== Other config options Console Display Name:: - Name used when this provider is referenced in the admin console + Name used when this provider is referenced in the admin console Priority:: - The priority of this provider when looking up users or for adding registrations. + The priority of this provider when looking up users or for adding registrations. Sync Registrations:: - If a new user is added through a registration page or admin console, should the user be eligible to be synchronized to this provider? + If a new user is added through a registration page or admin console, should the user be eligible to be synchronized to this provider? Allow Kerberos authentication:: Enable Kerberos/SPNEGO authentication in realm with users data provisioned from LDAP. @@ -91,8 +91,8 @@ then set up a periodic sync of changed users. The configuration page for your L LDAP mappers are `listeners`, which are triggered by the LDAP Federation provider at various points, provide another extension point to LDAP integration. They are triggered when a user logs in via LDAP and needs to be imported, during {{book.project.name}} initiated registration, or when a user is queried from the Admin Console. -When you create an LDAP Federation provider, {{book.project.name}} will automatically provide set of builtin `mappers` for this provider. -You are free to change this set and create a new mapper or update/delete existing ones. +When you create an LDAP Federation provider, {{book.project.name}} will automatically provide set of built-in `mappers` for this provider. +You are free to change this set and create a new mapper or update/delete existing ones. User Attribute Mapper:: This allows you to specify which LDAP attribute is mapped to which attribute of {{book.project.name}} user. @@ -101,7 +101,7 @@ User Attribute Mapper:: FullName Mapper:: This allows you to specify that the full name of the user, which is saved in some LDAP attribute (usually `cn` ) will be mapped to `firstName` and `lastname` attributes in the {{book.project.name}} database. - Having `cn` to contain full name of user is a common case for some LDAP deployments. + Having `cn` to contain full name of user is a common case for some LDAP deployments. Role Mapper:: This allows you to configure role mappings from LDAP into {{book.project.name}} role mappings. @@ -129,5 +129,4 @@ MSAD User Account Mapper:: By default, there is set of User Attribute mappers that map basic {{book.project.name}} user attributes like username, first name, lastname, and email to corresponding LDAP attributes. You are free to extend these and provide additional attribute mappings. -Admin console provides tooltips, which should help with configuring the corresponding mappers. - +Admin console provides tooltips, which should help with configuring the corresponding mappers. diff --git a/topics/users/credentials.adoc b/topics/users/credentials.adoc index 08f102df3f..42b1195a71 100644 --- a/topics/users/credentials.adoc +++ b/topics/users/credentials.adoc @@ -14,7 +14,7 @@ If the `Temporary` switch is on, this new password can only be used once and the logged in. Alternatively, if you have <> set up, you can send an email to the user that asks -them to reset their password. Choose `Update Password` from the `Reset Actions` list box and click the `Send Email`. +them to reset their password. Choose `Update Password` from the `Reset Actions` list box and click `Send Email`. The sent email contains a link that will bring the user to the update password screen. ==== Changing OTPs diff --git a/topics/users/required-actions.adoc b/topics/users/required-actions.adoc index 534f2d1151..de126c6579 100644 --- a/topics/users/required-actions.adoc +++ b/topics/users/required-actions.adoc @@ -3,7 +3,7 @@ Required Actions are tasks that a user must finish before they are allowed to log in. A user must provide their credentials before required actions are executed. Once a required action is completed, the user will not have to perform the action again. -Here are an explanation of some of the built in required action types: +Here are an explanation of some of the built-in required action types: Update Password:: When set, a user must change their password.