From 44c6a3ca649fdd23e61874c81994c1858bbd6cbb Mon Sep 17 00:00:00 2001 From: Stian Thorgersen Date: Mon, 28 Aug 2017 14:50:14 +0200 Subject: [PATCH] Convert documentation to AsciiDoctor --- .force_build | 1 - OVERVIEW.adoc | 9 - README.md | 36 +--- SUMMARY.adoc | 19 -- aggregation/pom.xml | 179 ++++++++++++++++++ aggregation/src/frames-index.html | 17 ++ aggregation/src/frames-links.html | 46 +++++ aggregation/src/frames.html | 11 ++ aggregation/src/index.html | 45 +++++ {images => aggregation/src}/keycloak_logo.png | Bin assembly.xml | 14 ++ authorization_services/README.adoc | 8 - authorization_services/SUMMARY.adoc | 109 ----------- authorization_services/book-product.json | 54 ------ authorization_services/buildGuide.sh | 80 -------- authorization_services/gitlab-conversion.py | 113 ----------- authorization_services/index.adoc | 6 + authorization_services/master-docinfo.xml | 10 +- authorization_services/master.adoc | 6 + authorization_services/pom.xml | 29 +++ authorization_services/topics.adoc | 106 +++++++++++ .../enforcer/authorization-context.adoc | 10 +- .../topics/enforcer/https.adoc | 4 +- .../topics/enforcer/js-adapter.adoc | 16 +- .../enforcer/keycloak-enforcement-bearer.adoc | 2 +- .../enforcer/keycloak-enforcement-filter.adoc | 12 +- .../topics/enforcer/overview.adoc | 6 +- .../topics/example/overview.adoc | 14 +- .../hello-world/before-start.adoc | 10 +- .../hello-world/create-realm.adoc | 8 +- .../hello-world/create-resource-server.adoc | 10 +- .../getting-started/hello-world/deploy.adoc | 30 +-- .../getting-started/hello-world/overview.adoc | 4 +- .../topics/getting-started/overview.adoc | 10 +- .../topics/overview/architecture.adoc | 48 ++--- .../topics/overview/overview.adoc | 14 +- .../topics/overview/terminology.adoc | 16 +- .../topics/permission/create-resource.adoc | 4 +- .../topics/permission/create-scope.adoc | 4 +- .../topics/permission/decision-strategy.adoc | 0 .../topics/permission/overview.adoc | 2 +- .../permission/typed-resource-permission.adoc | 6 +- .../policy-evaluation-tool/overview.adoc | 2 +- .../topics/policy/aggregated-policy.adoc | 6 +- .../topics/policy/client-policy.adoc | 4 +- .../topics/policy/drools-policy.adoc | 8 +- .../topics/policy/evaluation-api.adoc | 12 +- .../topics/policy/js-policy.adoc | 8 +- .../topics/policy/overview.adoc | 2 +- .../policy/role-policy-required-role.adoc | 2 +- .../topics/policy/role-policy.adoc | 8 +- .../topics/policy/time-policy.adoc | 6 +- .../topics/policy/user-policy.adoc | 4 +- .../topics/resource-server/create-client.adoc | 8 +- .../resource-server/default-config.adoc | 20 +- .../resource-server/enable-authorization.adoc | 14 +- .../topics/resource-server/import-config.adoc | 4 +- .../topics/resource-server/overview.adoc | 2 +- .../topics/resource/create.adoc | 8 +- .../topics/resource/overview.adoc | 0 .../topics/resource/view.adoc | 2 +- .../authorization/authorization-api-aapi.adoc | 6 +- .../authorization/authorization-api.adoc | 0 .../authorization/whatis-obtain-aat.adoc | 8 +- .../topics/service/client-api.adoc | 4 +- .../entitlement/entitlement-api-aapi.adoc | 12 +- .../service/entitlement/entitlement-api.adoc | 0 .../entitlement-request-metadata.adoc | 0 .../entitlement/whatis-obtain-eat.adoc | 4 +- .../topics/service/overview.adoc | 2 +- .../protection/permission-api-papi.adoc | 10 +- .../service/protection/protection-api.adoc | 2 +- .../protection/resources-api-papi.adoc | 0 .../service/protection/whatis-obtain-pat.adoc | 8 +- .../topics/service/rpt/overview.adoc | 2 +- .../service/rpt/token-introspection.adoc | 8 +- build-product.sh => convert.sh | 20 +- document-attributes-community.adoc | 52 +++++ document-attributes-product.adoc | 52 +++++ getting_started/README.adoc | 9 - getting_started/SUMMARY.adoc | 24 --- getting_started/book-product.json | 47 ----- getting_started/buildGuide.sh | 80 -------- getting_started/gitlab-conversion.py | 113 ----------- getting_started/index.adoc | 6 + getting_started/master-docinfo.xml | 12 +- getting_started/master.adoc | 6 + getting_started/pom.xml | 29 +++ getting_started/topics.adoc | 22 +++ getting_started/topics/first-boot.adoc | 2 +- .../topics/first-boot/admin-console.adoc | 6 +- getting_started/topics/first-boot/boot.adoc | 4 +- .../distribution-files-community.adoc | 8 +- .../distribution-files-product.adoc | 8 +- .../topics/first-boot/initial-user.adoc | 8 +- getting_started/topics/first-realm.adoc | 2 +- .../topics/first-realm/account.adoc | 4 +- .../topics/first-realm/before.adoc | 4 +- getting_started/topics/first-realm/realm.adoc | 8 +- getting_started/topics/first-realm/user.adoc | 6 +- getting_started/topics/overview.adoc | 2 +- getting_started/topics/secure-jboss-app.adoc | 6 +- .../topics/secure-jboss-app/before.adoc | 16 +- .../secure-jboss-app/create-client.adoc | 16 +- .../download-quickstarts.adoc | 14 +- .../install-client-adapter.adoc | 18 +- .../topics/secure-jboss-app/subsystem.adoc | 2 +- gitlab-conversion.py | 111 ----------- pom.xml | 135 +++++++++++++ scripts/buildGuides.sh | 119 ------------ securing_apps/README.adoc | 9 - securing_apps/SUMMARY.adoc | 92 --------- securing_apps/book-product.json | 35 ---- securing_apps/buildGuide.sh | 80 -------- securing_apps/gitlab-conversion.py | 113 ----------- securing_apps/index.adoc | 6 + securing_apps/master-docinfo.xml | 10 +- securing_apps/master.adoc | 6 + securing_apps/pom.xml | 29 +++ securing_apps/topics.adoc | 90 +++++++++ securing_apps/topics/client-registration.adoc | 34 ++-- .../client-registration-cli.adoc | 12 +- .../topics/docker/docker-overview.adoc | 16 +- .../topics/oidc/java/adapter-context.adoc | 2 +- .../oidc/java/adapter_error_handling.adoc | 8 +- .../oidc/java/application-clustering.adoc | 48 ++--- .../oidc/java/client-authentication.adoc | 26 +-- .../topics/oidc/java/fuse-adapter.adoc | 20 +- .../topics/oidc/java/fuse/camel.adoc | 6 +- .../topics/oidc/java/fuse/classic-war.adoc | 12 +- .../topics/oidc/java/fuse/cxf-builtin.adoc | 10 +- .../topics/oidc/java/fuse/cxf-separate.adoc | 4 +- .../topics/oidc/java/fuse/fuse-admin.adoc | 16 +- .../topics/oidc/java/fuse/hawtio.adoc | 36 ++-- .../oidc/java/fuse/install-feature.adoc | 34 ++-- .../oidc/java/fuse/servlet-whiteboard.adoc | 16 +- securing_apps/topics/oidc/java/jaas.adoc | 12 +- .../topics/oidc/java/java-adapter-config.adoc | 48 ++--- .../topics/oidc/java/java-adapters.adoc | 4 +- .../topics/oidc/java/jboss-adapter.adoc | 64 +++---- .../topics/oidc/java/jetty8-adapter.adoc | 2 +- .../topics/oidc/java/jetty9-adapter.adoc | 2 +- securing_apps/topics/oidc/java/logout.adoc | 0 .../topics/oidc/java/multi-tenancy.adoc | 6 +- .../topics/oidc/java/params_forwarding.adoc | 10 +- .../oidc/java/servlet-filter-adapter.adoc | 12 +- .../topics/oidc/java/spring-boot-adapter.adoc | 2 +- .../oidc/java/spring-security-adapter.adoc | 4 +- .../topics/oidc/java/tomcat-adapter.adoc | 2 +- .../topics/oidc/javascript-adapter.adoc | 38 ++-- securing_apps/topics/oidc/nodejs-adapter.adoc | 36 ++-- securing_apps/topics/oidc/oidc-generic.adoc | 22 +-- securing_apps/topics/oidc/oidc-overview.adoc | 2 +- securing_apps/topics/overview/overview.adoc | 4 +- .../topics/overview/supported-platforms.adoc | 80 ++++---- .../topics/overview/supported-protocols.adoc | 14 +- .../overview/what-are-client-adapters.adoc | 2 +- .../topics/saml/java/assertion-api.adoc | 2 +- securing_apps/topics/saml/java/debugging.adoc | 2 +- .../topics/saml/java/error_handling.adoc | 2 +- .../topics/saml/java/general-config.adoc | 2 +- .../idp_httpclient_subelement.adoc | 18 +- .../general-config/idp_keys_subelement.adoc | 12 +- .../topics/saml/java/java-adapters.adoc | 2 +- .../jboss_adapter_installation.adoc | 20 +- .../required_per_war_configuration.adoc | 2 +- .../java/jboss-adapter/securing_wars.adoc | 8 +- .../topics/saml/java/jetty-adapter.adoc | 2 +- .../jetty-adapter/jetty8-per_war_config.adoc | 2 +- .../jetty-adapter/jetty9_per_war_config.adoc | 2 +- .../topics/saml/java/saml-jboss-adapter.adoc | 20 +- .../saml/java/servlet-filter-adapter.adoc | 10 +- .../tomcat_adapter_per_war_config.adoc | 2 +- .../topics/saml/mod-auth-mellon.adoc | 30 +-- securing_apps/topics/saml/saml-overview.adoc | 2 +- server_admin/README.adoc | 9 - server_admin/SUMMARY.adoc | 113 ----------- server_admin/book-product.json | 45 ----- server_admin/buildGuide.sh | 80 -------- server_admin/gitlab-conversion.py | 113 ----------- server_admin/index.adoc | 6 + server_admin/master-docinfo.xml | 10 +- server_admin/master.adoc | 6 + server_admin/pom.xml | 29 +++ server_admin/topics.adoc | 111 +++++++++++ server_admin/topics/License.adoc | 0 .../topics/MigrationFromOlderVersions.adoc | 14 +- server_admin/topics/account.adoc | 22 +-- server_admin/topics/admin-cli.adoc | 14 +- .../topics/admin-console-permissions.adoc | 2 +- .../admin-console-permissions/fine-grain.adoc | 46 ++--- .../master-realm.adoc | 8 +- server_admin/topics/admin-console.adoc | 8 +- server_admin/topics/authentication/flows.adoc | 8 +- .../topics/authentication/kerberos.adoc | 80 ++++---- .../topics/authentication/otp-policies.adoc | 10 +- .../authentication/password-policies.adoc | 18 +- server_admin/topics/authentication/x509.adoc | 12 +- server_admin/topics/clients.adoc | 2 +- server_admin/topics/clients/client-link.adoc | 4 +- server_admin/topics/clients/client-oidc.adoc | 40 ++-- server_admin/topics/clients/client-saml.adoc | 40 ++-- .../topics/clients/client-templates.adoc | 8 +- server_admin/topics/clients/installation.adoc | 6 +- .../topics/clients/oidc/confidential.adoc | 22 +-- .../topics/clients/oidc/service-accounts.adoc | 8 +- .../topics/clients/protocol-mappers.adoc | 10 +- .../clients/saml/entity-descriptors.adoc | 2 +- .../clients/saml/idp-initiated-login.adoc | 2 +- server_admin/topics/events.adoc | 2 +- server_admin/topics/events/admin.adoc | 12 +- server_admin/topics/events/login.adoc | 12 +- server_admin/topics/export-import.adoc | 4 +- server_admin/topics/groups.adoc | 10 +- .../topics/groups/default-groups.adoc | 4 +- .../topics/groups/groups-vs-roles.adoc | 4 +- server_admin/topics/identity-broker.adoc | 2 +- .../topics/identity-broker/configuration.adoc | 16 +- .../identity-broker/default-provider.adoc | 2 +- .../identity-broker/first-login-flow.adoc | 36 ++-- .../topics/identity-broker/mappers.adoc | 6 +- server_admin/topics/identity-broker/oidc.adoc | 26 +-- .../topics/identity-broker/overview.adoc | 34 ++-- server_admin/topics/identity-broker/saml.adoc | 10 +- .../topics/identity-broker/session-data.adoc | 8 +- .../topics/identity-broker/social-login.adoc | 2 +- .../identity-broker/social/facebook.adoc | 18 +- .../topics/identity-broker/social/github.adoc | 16 +- .../topics/identity-broker/social/google.adoc | 32 ++-- .../identity-broker/social/linked-in.adoc | 16 +- .../identity-broker/social/microsoft.adoc | 14 +- .../identity-broker/social/openshift.adoc | 8 +- .../social/stack-overflow.adoc | 10 +- .../identity-broker/social/twitter.adoc | 16 +- .../topics/identity-broker/suggested.adoc | 4 +- .../topics/identity-broker/tokens.adoc | 6 +- server_admin/topics/initialization.adoc | 12 +- .../login-settings/forgot-password.adoc | 10 +- .../topics/login-settings/remember-me.adoc | 4 +- server_admin/topics/overview.adoc | 6 +- server_admin/topics/overview/concepts.adoc | 28 +-- server_admin/topics/overview/features.adoc | 8 +- server_admin/topics/overview/how.adoc | 6 +- server_admin/topics/realms.adoc | 2 +- server_admin/topics/realms/cache.adoc | 8 +- server_admin/topics/realms/create.adoc | 6 +- server_admin/topics/realms/email.adoc | 6 +- server_admin/topics/realms/keys.adoc | 14 +- server_admin/topics/realms/master.adoc | 4 +- server_admin/topics/realms/ssl.adoc | 14 +- server_admin/topics/realms/themes.adoc | 14 +- server_admin/topics/roles.adoc | 0 server_admin/topics/roles/client-scope.adoc | 8 +- server_admin/topics/roles/composite.adoc | 2 +- server_admin/topics/roles/realm-roles.adoc | 6 +- .../topics/roles/user-role-mappings.adoc | 6 +- .../user-role-mappings/default-roles.adoc | 4 +- server_admin/topics/sessions.adoc | 2 +- .../topics/sessions/administering.adoc | 12 +- server_admin/topics/sessions/offline.adoc | 10 +- server_admin/topics/sessions/revocation.adoc | 4 +- server_admin/topics/sessions/timeouts.adoc | 6 +- server_admin/topics/sso-protocols.adoc | 2 +- server_admin/topics/sso-protocols/docker.adoc | 22 +-- server_admin/topics/sso-protocols/oidc.adoc | 28 +-- .../topics/sso-protocols/saml-vs-oidc.adoc | 2 +- server_admin/topics/sso-protocols/saml.adoc | 18 +- server_admin/topics/threat.adoc | 2 +- server_admin/topics/threat/brute-force.adoc | 12 +- server_admin/topics/threat/clickjacking.adoc | 6 +- .../topics/threat/compromised-codes.adoc | 6 +- .../topics/threat/compromised-tokens.adoc | 8 +- server_admin/topics/threat/csrf.adoc | 8 +- server_admin/topics/threat/open-redirect.adoc | 4 +- .../threat/password-db-compromised.adoc | 2 +- server_admin/topics/threat/redirect.adoc | 2 +- server_admin/topics/threat/scope.adoc | 2 +- server_admin/topics/threat/sql.adoc | 2 +- server_admin/topics/threat/ssl.adoc | 8 +- server_admin/topics/user-federation.adoc | 16 +- .../topics/user-federation/custom.adoc | 4 +- server_admin/topics/user-federation/ldap.adoc | 84 ++++---- server_admin/topics/user-federation/sssd.adoc | 38 ++-- server_admin/topics/users/attributes.adoc | 2 +- server_admin/topics/users/create-user.adoc | 4 +- server_admin/topics/users/credentials.adoc | 4 +- server_admin/topics/users/impersonation.adoc | 6 +- server_admin/topics/users/recaptcha.adoc | 14 +- .../topics/users/required-actions.adoc | 10 +- .../topics/users/user-registration.adoc | 10 +- server_admin/topics/users/viewing.adoc | 10 +- server_development/README.adoc | 9 - server_development/SUMMARY.adoc | 30 --- server_development/book-product.json | 48 ----- server_development/book.json | 35 ---- server_development/buildGuide.sh | 80 -------- server_development/gitlab-conversion.py | 113 ----------- server_development/index.adoc | 6 + server_development/master-docinfo.xml | 12 +- server_development/master.adoc | 6 + server_development/pom.xml | 29 +++ server_development/topics.adoc | 28 +++ .../topics/action-token-spi.adoc | 4 +- server_development/topics/admin-rest-api.adoc | 16 +- server_development/topics/auth-spi.adoc | 14 +- .../topics/custom-attributes.adoc | 2 +- server_development/topics/events.adoc | 0 server_development/topics/extensions.adoc | 24 +-- .../topics/identity-brokering.adoc | 4 +- .../identity-brokering/account-linking.adoc | 4 +- .../topics/identity-brokering/tokens.adoc | 6 +- server_development/topics/providers.adoc | 4 +- server_development/topics/themes.adoc | 32 ++-- .../topics/user-federation-mapper.adoc | 0 .../topics/user-federation.adoc | 0 server_development/topics/user-storage.adoc | 4 +- .../topics/user-storage/augmenting.adoc | 8 +- .../topics/user-storage/configuration.adoc | 6 +- .../topics/user-storage/import.adoc | 16 +- .../topics/user-storage/javaee.adoc | 2 +- .../topics/user-storage/migration.adoc | 24 +-- .../topics/user-storage/model-interfaces.adoc | 6 +- .../topics/user-storage/packaging.adoc | 6 +- .../topics/user-storage/simple-example.adoc | 26 +-- server_installation/README.adoc | 9 - server_installation/SUMMARY.adoc | 52 ----- server_installation/book-product.json | 71 ------- server_installation/buildGuide.sh | 80 -------- server_installation/gitlab-conversion.py | 113 ----------- server_installation/index.adoc | 6 + server_installation/master-docinfo.xml | 12 +- server_installation/master.adoc | 6 + server_installation/pom.xml | 29 +++ server_installation/topics.adoc | 50 +++++ server_installation/topics/cache.adoc | 6 +- server_installation/topics/cache/clear.adoc | 2 +- server_installation/topics/cache/disable.adoc | 2 +- .../topics/cache/eviction.adoc | 4 +- .../topics/cache/replication.adoc | 2 +- server_installation/topics/clustering.adoc | 8 +- .../topics/clustering/booting.adoc | 2 +- .../topics/clustering/example.adoc | 4 +- .../topics/clustering/load-balancer.adoc | 42 ++-- .../topics/clustering/multicast.adoc | 8 +- .../topics/clustering/recommended.adoc | 4 +- .../clustering/securing-cluster-comm.adoc | 2 +- .../topics/clustering/serialized.adoc | 6 +- .../topics/clustering/sticky-sessions.adoc | 36 ++-- .../topics/clustering/troubleshooting.adoc | 4 +- .../topics/config-subsystem.adoc | 4 +- .../configure-spi-providers.adoc | 2 +- .../topics/config-subsystem/start-cli.adoc | 8 +- server_installation/topics/database.adoc | 16 +- .../topics/database/checklist.adoc | 2 +- .../topics/database/datasource.adoc | 6 +- .../topics/database/hibernate.adoc | 4 +- server_installation/topics/database/jdbc.adoc | 8 +- .../database/unicode-considerations.adoc | 2 +- server_installation/topics/installation.adoc | 12 +- .../installation/directory-structure.adoc | 14 +- .../distribution-files-community.adoc | 12 +- .../distribution-files-product.adoc | 4 +- .../installation/system-requirements.adoc | 12 +- server_installation/topics/manage.adoc | 8 +- server_installation/topics/network.adoc | 6 +- .../topics/network/bind-address.adoc | 16 +- server_installation/topics/network/https.adoc | 38 ++-- .../topics/network/outgoing.adoc | 10 +- server_installation/topics/network/ports.adoc | 12 +- server_installation/topics/openshift.adoc | 26 +-- .../topics/operating-mode.adoc | 8 +- .../topics/operating-mode/domain.adoc | 42 ++-- .../topics/operating-mode/standalone-ha.adoc | 20 +- .../topics/operating-mode/standalone.adoc | 18 +- server_installation/topics/overview.adoc | 10 +- .../topics/overview/recommended-reading.adoc | 6 +- server_installation/topics/profiles.adoc | 20 +- server_installation/topics/proxy.adoc | 16 +- 378 files changed, 2900 insertions(+), 3963 deletions(-) delete mode 100644 .force_build delete mode 100644 OVERVIEW.adoc delete mode 100644 SUMMARY.adoc create mode 100644 aggregation/pom.xml create mode 100644 aggregation/src/frames-index.html create mode 100644 aggregation/src/frames-links.html create mode 100644 aggregation/src/frames.html create mode 100644 aggregation/src/index.html rename {images => aggregation/src}/keycloak_logo.png (100%) mode change 100755 => 100644 create mode 100644 assembly.xml delete mode 100755 authorization_services/README.adoc delete mode 100755 authorization_services/SUMMARY.adoc delete mode 100755 authorization_services/book-product.json delete mode 100755 authorization_services/buildGuide.sh delete mode 100755 authorization_services/gitlab-conversion.py create mode 100644 authorization_services/index.adoc mode change 100755 => 100644 authorization_services/master-docinfo.xml create mode 100644 authorization_services/master.adoc create mode 100644 authorization_services/pom.xml create mode 100644 authorization_services/topics.adoc mode change 100755 => 100644 authorization_services/topics/enforcer/authorization-context.adoc mode change 100755 => 100644 authorization_services/topics/enforcer/js-adapter.adoc mode change 100755 => 100644 authorization_services/topics/enforcer/keycloak-enforcement-bearer.adoc mode change 100755 => 100644 authorization_services/topics/enforcer/overview.adoc mode change 100755 => 100644 authorization_services/topics/example/overview.adoc mode change 100755 => 100644 authorization_services/topics/overview/architecture.adoc mode change 100755 => 100644 authorization_services/topics/overview/overview.adoc mode change 100755 => 100644 authorization_services/topics/overview/terminology.adoc mode change 100755 => 100644 authorization_services/topics/permission/create-resource.adoc mode change 100755 => 100644 authorization_services/topics/permission/create-scope.adoc mode change 100755 => 100644 authorization_services/topics/permission/decision-strategy.adoc mode change 100755 => 100644 authorization_services/topics/permission/overview.adoc mode change 100755 => 100644 authorization_services/topics/permission/typed-resource-permission.adoc mode change 100755 => 100644 authorization_services/topics/policy-evaluation-tool/overview.adoc mode change 100755 => 100644 authorization_services/topics/policy/aggregated-policy.adoc mode change 100755 => 100644 authorization_services/topics/policy/evaluation-api.adoc mode change 100755 => 100644 authorization_services/topics/policy/overview.adoc mode change 100755 => 100644 authorization_services/topics/resource-server/create-client.adoc mode change 100755 => 100644 authorization_services/topics/resource-server/default-config.adoc mode change 100755 => 100644 authorization_services/topics/resource-server/enable-authorization.adoc mode change 100755 => 100644 authorization_services/topics/resource-server/import-config.adoc mode change 100755 => 100644 authorization_services/topics/resource-server/overview.adoc mode change 100755 => 100644 authorization_services/topics/resource/create.adoc mode change 100755 => 100644 authorization_services/topics/resource/overview.adoc mode change 100755 => 100644 authorization_services/topics/resource/view.adoc mode change 100755 => 100644 authorization_services/topics/service/authorization/authorization-api-aapi.adoc mode change 100755 => 100644 authorization_services/topics/service/authorization/authorization-api.adoc mode change 100755 => 100644 authorization_services/topics/service/authorization/whatis-obtain-aat.adoc mode change 100755 => 100644 authorization_services/topics/service/client-api.adoc mode change 100755 => 100644 authorization_services/topics/service/entitlement/entitlement-api-aapi.adoc mode change 100755 => 100644 authorization_services/topics/service/entitlement/entitlement-api.adoc mode change 100755 => 100644 authorization_services/topics/service/entitlement/entitlement-request-metadata.adoc mode change 100755 => 100644 authorization_services/topics/service/entitlement/whatis-obtain-eat.adoc mode change 100755 => 100644 authorization_services/topics/service/overview.adoc mode change 100755 => 100644 authorization_services/topics/service/protection/permission-api-papi.adoc mode change 100755 => 100644 authorization_services/topics/service/protection/protection-api.adoc mode change 100755 => 100644 authorization_services/topics/service/protection/resources-api-papi.adoc mode change 100755 => 100644 authorization_services/topics/service/protection/whatis-obtain-pat.adoc mode change 100755 => 100644 authorization_services/topics/service/rpt/token-introspection.adoc rename build-product.sh => convert.sh (68%) create mode 100644 document-attributes-community.adoc create mode 100644 document-attributes-product.adoc delete mode 100755 getting_started/README.adoc delete mode 100755 getting_started/SUMMARY.adoc delete mode 100755 getting_started/book-product.json delete mode 100755 getting_started/buildGuide.sh delete mode 100755 getting_started/gitlab-conversion.py create mode 100644 getting_started/index.adoc create mode 100644 getting_started/master.adoc create mode 100644 getting_started/pom.xml create mode 100644 getting_started/topics.adoc mode change 100755 => 100644 getting_started/topics/first-boot.adoc mode change 100755 => 100644 getting_started/topics/first-boot/admin-console.adoc mode change 100755 => 100644 getting_started/topics/first-boot/boot.adoc mode change 100755 => 100644 getting_started/topics/first-boot/distribution-files-community.adoc mode change 100755 => 100644 getting_started/topics/first-boot/distribution-files-product.adoc mode change 100755 => 100644 getting_started/topics/first-boot/initial-user.adoc mode change 100755 => 100644 getting_started/topics/first-realm.adoc mode change 100755 => 100644 getting_started/topics/first-realm/account.adoc mode change 100755 => 100644 getting_started/topics/first-realm/before.adoc mode change 100755 => 100644 getting_started/topics/first-realm/realm.adoc mode change 100755 => 100644 getting_started/topics/first-realm/user.adoc mode change 100755 => 100644 getting_started/topics/overview.adoc mode change 100755 => 100644 getting_started/topics/secure-jboss-app/before.adoc delete mode 100755 gitlab-conversion.py create mode 100644 pom.xml delete mode 100755 scripts/buildGuides.sh delete mode 100755 securing_apps/README.adoc delete mode 100644 securing_apps/SUMMARY.adoc delete mode 100755 securing_apps/book-product.json delete mode 100755 securing_apps/buildGuide.sh delete mode 100755 securing_apps/gitlab-conversion.py create mode 100644 securing_apps/index.adoc mode change 100755 => 100644 securing_apps/master-docinfo.xml create mode 100644 securing_apps/master.adoc create mode 100644 securing_apps/pom.xml create mode 100644 securing_apps/topics.adoc mode change 100755 => 100644 securing_apps/topics/oidc/java/fuse-adapter.adoc mode change 100755 => 100644 securing_apps/topics/oidc/java/jetty8-adapter.adoc mode change 100755 => 100644 securing_apps/topics/oidc/java/jetty9-adapter.adoc mode change 100755 => 100644 securing_apps/topics/oidc/java/logout.adoc mode change 100755 => 100644 securing_apps/topics/oidc/java/multi-tenancy.adoc mode change 100755 => 100644 securing_apps/topics/oidc/java/spring-boot-adapter.adoc mode change 100755 => 100644 securing_apps/topics/oidc/java/spring-security-adapter.adoc mode change 100755 => 100644 securing_apps/topics/oidc/java/tomcat-adapter.adoc delete mode 100755 server_admin/README.adoc delete mode 100644 server_admin/SUMMARY.adoc delete mode 100644 server_admin/book-product.json delete mode 100755 server_admin/buildGuide.sh delete mode 100755 server_admin/gitlab-conversion.py create mode 100644 server_admin/index.adoc mode change 100755 => 100644 server_admin/master-docinfo.xml create mode 100644 server_admin/master.adoc create mode 100644 server_admin/pom.xml create mode 100644 server_admin/topics.adoc mode change 100755 => 100644 server_admin/topics/License.adoc mode change 100755 => 100644 server_admin/topics/admin-console-permissions.adoc mode change 100755 => 100644 server_admin/topics/clients/client-link.adoc mode change 100755 => 100644 server_admin/topics/export-import.adoc mode change 100755 => 100644 server_admin/topics/groups.adoc mode change 100755 => 100644 server_admin/topics/identity-broker.adoc mode change 100755 => 100644 server_admin/topics/overview/concepts.adoc mode change 100755 => 100644 server_admin/topics/overview/how.adoc mode change 100755 => 100644 server_admin/topics/roles.adoc mode change 100755 => 100644 server_admin/topics/threat.adoc mode change 100755 => 100644 server_admin/topics/users/create-user.adoc mode change 100755 => 100644 server_admin/topics/users/recaptcha.adoc delete mode 100755 server_development/README.adoc delete mode 100755 server_development/SUMMARY.adoc delete mode 100755 server_development/book-product.json delete mode 100755 server_development/book.json delete mode 100755 server_development/buildGuide.sh delete mode 100755 server_development/gitlab-conversion.py create mode 100644 server_development/index.adoc mode change 100755 => 100644 server_development/master-docinfo.xml create mode 100644 server_development/master.adoc create mode 100644 server_development/pom.xml create mode 100644 server_development/topics.adoc mode change 100755 => 100644 server_development/topics/auth-spi.adoc mode change 100755 => 100644 server_development/topics/custom-attributes.adoc mode change 100755 => 100644 server_development/topics/events.adoc mode change 100755 => 100644 server_development/topics/user-federation-mapper.adoc mode change 100755 => 100644 server_development/topics/user-federation.adoc delete mode 100755 server_installation/README.adoc delete mode 100755 server_installation/SUMMARY.adoc delete mode 100755 server_installation/book-product.json delete mode 100755 server_installation/buildGuide.sh delete mode 100755 server_installation/gitlab-conversion.py create mode 100644 server_installation/index.adoc mode change 100755 => 100644 server_installation/master-docinfo.xml create mode 100644 server_installation/master.adoc create mode 100644 server_installation/pom.xml create mode 100644 server_installation/topics.adoc mode change 100755 => 100644 server_installation/topics/cache.adoc mode change 100755 => 100644 server_installation/topics/cache/clear.adoc mode change 100755 => 100644 server_installation/topics/cache/disable.adoc mode change 100755 => 100644 server_installation/topics/cache/eviction.adoc mode change 100755 => 100644 server_installation/topics/cache/replication.adoc mode change 100755 => 100644 server_installation/topics/clustering.adoc mode change 100755 => 100644 server_installation/topics/clustering/booting.adoc mode change 100755 => 100644 server_installation/topics/clustering/example.adoc mode change 100755 => 100644 server_installation/topics/clustering/multicast.adoc mode change 100755 => 100644 server_installation/topics/clustering/recommended.adoc mode change 100755 => 100644 server_installation/topics/clustering/serialized.adoc mode change 100755 => 100644 server_installation/topics/clustering/troubleshooting.adoc mode change 100755 => 100644 server_installation/topics/database.adoc mode change 100755 => 100644 server_installation/topics/database/checklist.adoc mode change 100755 => 100644 server_installation/topics/database/datasource.adoc mode change 100755 => 100644 server_installation/topics/database/jdbc.adoc mode change 100755 => 100644 server_installation/topics/installation.adoc mode change 100755 => 100644 server_installation/topics/installation/directory-structure.adoc mode change 100755 => 100644 server_installation/topics/installation/distribution-files-community.adoc mode change 100755 => 100644 server_installation/topics/installation/distribution-files-product.adoc mode change 100755 => 100644 server_installation/topics/installation/system-requirements.adoc mode change 100755 => 100644 server_installation/topics/manage.adoc mode change 100755 => 100644 server_installation/topics/network.adoc mode change 100755 => 100644 server_installation/topics/network/bind-address.adoc mode change 100755 => 100644 server_installation/topics/network/https.adoc mode change 100755 => 100644 server_installation/topics/network/outgoing.adoc mode change 100755 => 100644 server_installation/topics/network/ports.adoc mode change 100755 => 100644 server_installation/topics/openshift.adoc mode change 100755 => 100644 server_installation/topics/operating-mode.adoc mode change 100755 => 100644 server_installation/topics/operating-mode/domain.adoc mode change 100755 => 100644 server_installation/topics/operating-mode/standalone-ha.adoc mode change 100755 => 100644 server_installation/topics/operating-mode/standalone.adoc mode change 100755 => 100644 server_installation/topics/overview.adoc mode change 100755 => 100644 server_installation/topics/overview/recommended-reading.adoc mode change 100755 => 100644 server_installation/topics/profiles.adoc mode change 100755 => 100644 server_installation/topics/proxy.adoc diff --git a/.force_build b/.force_build deleted file mode 100644 index 18fed18acd0..00000000000 --- a/.force_build +++ /dev/null @@ -1 +0,0 @@ -Thu 16 Mar 08:18:49 CET 2017 diff --git a/OVERVIEW.adoc b/OVERVIEW.adoc deleted file mode 100644 index ae64d783f92..00000000000 --- a/OVERVIEW.adoc +++ /dev/null @@ -1,9 +0,0 @@ - -= Keycloak Documentation - -image:images/keycloak_logo.png[alt="Keycloak"] - -{{book.project.name}} {{book.project.version}} - -http://www.keycloak.org - diff --git a/README.md b/README.md index a0e418f80e5..c35cf9e742e 100755 --- a/README.md +++ b/README.md @@ -9,7 +9,7 @@ For more information about Keycloak visit [Keycloak homepage](http://keycloak.or Building Keycloak Documentation ------------------------------- -Ensure you have [GitBook installed](https://github.com/GitbookIO/gitbook/blob/master/docs/setup.md) +Ensure you have [Maven installed](https://maven.apache.org/) First clone the Keycloak Documentation repository: @@ -18,16 +18,9 @@ First clone the Keycloak Documentation repository: To build Keycloak Documentation run: - gitbook build + mvn clean install build -You can then view the documentation by opening _book/index.html. - -Alternatively you can also have the Gitbook tools continiously re-build when you do changes. To do this run: - - gitbook serve - -You can then view the documentation on http://localhost:4000. - +You can then view the documentation by opening target/frames.html or target/index.html. Building RH-SSO Documentation @@ -35,28 +28,11 @@ Building RH-SSO Documentation Keycloak is the basis of [Red Hat Single Sign-On](https://access.redhat.com/products/red-hat-single-sign-on). The same documentation sources are used, but they are built slighty differently. -To build the documentation for RH-SSO go into the directory of the specific guide you want to build. For example to build Server Admin guide run: +To build the documentation for RH-SSO run: - cd server_admin - python ../gitlab-conversion.py - cd target - asciidoctor master.adoc + mvn clean install build -Dproduct -On Linux you can also run build-product.sh DIR. For example: - - ./build-product.sh server_admin - -Or build all guides with: - - ./build-product.sh - -If you have ccutil available you can build the guides with: - - ./build-product.sh -u - -You can then view the documentation by opening server_admin/target/master.html - -This will not create documentation that looks exactly as the official Red Hat Single Sign-On documentation, but the content will be the same. +You can then view the documentation by opening target/frames.html or target/index.html. License diff --git a/SUMMARY.adoc b/SUMMARY.adoc deleted file mode 100644 index bfffeffeb22..00000000000 --- a/SUMMARY.adoc +++ /dev/null @@ -1,19 +0,0 @@ -= Keycloak Documentation - -. link:getting_started/README.adoc[Getting Started] -{% include "./getting_started/SUMMARY.adoc" %} - -. link:server_installation/README.adoc[Server Installation and Configuration] -{% include "./server_installation/SUMMARY.adoc" %} - -. link:server_admin/README.adoc[Server Administration] -{% include "./server_admin/SUMMARY.adoc" %} - -. link:securing_apps/README.adoc[Securing Applications and Services] -{% include "./securing_apps/SUMMARY.adoc" %} - -. link:server_development/README.adoc[Server Development] -{% include "./server_development/SUMMARY.adoc" %} - -. link:authorization_services/README.adoc[Authorization Services] -{% include "./authorization_services/SUMMARY.adoc" %} \ No newline at end of file diff --git a/aggregation/pom.xml b/aggregation/pom.xml new file mode 100644 index 00000000000..34202129005 --- /dev/null +++ b/aggregation/pom.xml @@ -0,0 +1,179 @@ + + + 4.0.0 + + + org.keycloak.documentation + documentation-parent + 1.0.0-SNAPSHOT + ../ + + + Aggregation + aggregation + pom + + + + org.keycloak.documentation + authorization-services + ${project.version} + pom + + + org.keycloak.documentation + getting-started + ${project.version} + pom + + + org.keycloak.documentation + securing-apps + ${project.version} + pom + + + org.keycloak.documentation + server-admin + ${project.version} + pom + + + org.keycloak.documentation + server-development + ${project.version} + pom + + + org.keycloak.documentation + server-installation + ${project.version} + pom + + + + + ../target + + + org.apache.maven.plugins + maven-resources-plugin + + + copy-authorization_services + process-resources + + copy-resources + + + ${project.build.outputDirectory}/authorization_services/ + + + ../authorization_services/target/generated-docs + **/** + + + + + + copy-getting_started + process-resources + + copy-resources + + + ${project.build.outputDirectory}/getting_started/ + + + ../getting_started/target/generated-docs + **/** + + + + + + copy-securing_apps + process-resources + + copy-resources + + + ${project.build.outputDirectory}/securing_apps/ + + + ../securing_apps/target/generated-docs + **/** + + + + + + copy-server_admin + process-resources + + copy-resources + + + ${project.build.outputDirectory}/server_admin/ + + + ../server_admin/target/generated-docs + **/** + + + + + + copy-server_development + process-resources + + copy-resources + + + ${project.build.outputDirectory}/server_development/ + + + ../server_development/target/generated-docs + **/** + + + + + + copy-server_installation + process-resources + + copy-resources + + + ${project.build.outputDirectory}/server_installation/ + + + ../server_installation/target/generated-docs + **/** + + + + + + copy-index + process-resources + + copy-resources + + + ${project.build.outputDirectory}/ + + + src + *.* + true + + + + + + + + + diff --git a/aggregation/src/frames-index.html b/aggregation/src/frames-index.html new file mode 100644 index 00000000000..15323268215 --- /dev/null +++ b/aggregation/src/frames-index.html @@ -0,0 +1,17 @@ + + + + +Documentation Index + + + + + + diff --git a/aggregation/src/frames-links.html b/aggregation/src/frames-links.html new file mode 100644 index 00000000000..0652c514b40 --- /dev/null +++ b/aggregation/src/frames-links.html @@ -0,0 +1,46 @@ + + + + +Documentation Index + + + + + + diff --git a/aggregation/src/frames.html b/aggregation/src/frames.html new file mode 100644 index 00000000000..066232354db --- /dev/null +++ b/aggregation/src/frames.html @@ -0,0 +1,11 @@ + + + + +Keycloak Documentation + + + + + + diff --git a/aggregation/src/index.html b/aggregation/src/index.html new file mode 100644 index 00000000000..47006e78fee --- /dev/null +++ b/aggregation/src/index.html @@ -0,0 +1,45 @@ + + + + +Documentation Index + + + + + + + diff --git a/images/keycloak_logo.png b/aggregation/src/keycloak_logo.png old mode 100755 new mode 100644 similarity index 100% rename from images/keycloak_logo.png rename to aggregation/src/keycloak_logo.png diff --git a/assembly.xml b/assembly.xml new file mode 100644 index 00000000000..0e69534cc1a --- /dev/null +++ b/assembly.xml @@ -0,0 +1,14 @@ + + + asciidoc-html-zip + + zip + + + + + ${project.build.directory}/generated-docs + + + + diff --git a/authorization_services/README.adoc b/authorization_services/README.adoc deleted file mode 100755 index f05e1be806a..00000000000 --- a/authorization_services/README.adoc +++ /dev/null @@ -1,8 +0,0 @@ - -= Authorization Services - -image:images/keycloak_logo.png[alt="Keycloak"] - -{{book.project.name}} {{book.project.version}} - -http://www.keycloak.org diff --git a/authorization_services/SUMMARY.adoc b/authorization_services/SUMMARY.adoc deleted file mode 100755 index 5bccd18e8d0..00000000000 --- a/authorization_services/SUMMARY.adoc +++ /dev/null @@ -1,109 +0,0 @@ -= Authorization Services Guide - - .. link:authorization_services/topics/overview/overview.adoc[Overview] - - ... link:authorization_services/topics/overview/architecture.adoc[Architecture] - - ... link:authorization_services/topics/overview/terminology.adoc[Terminology] - - .. link:authorization_services/topics/getting-started/overview.adoc[Getting Started] - - ... link:authorization_services/topics/getting-started/hello-world/overview.adoc[Securing a Servlet Application] - - .... link:authorization_services/topics/getting-started/hello-world/create-realm.adoc[Creating a Realm and a User] - - .... link:authorization_services/topics/getting-started/hello-world/create-resource-server.adoc[Enabling Authorization Services] - - .... link:authorization_services/topics/getting-started/hello-world/deploy.adoc[Build, Deploy, and Test Your Application] -{% if book.community %} - ... link:authorization_services/topics/example/overview.adoc[Examples] -{% endif %} - - .. link:authorization_services/topics/resource-server/overview.adoc[Managing Resource Servers] - - ... link:authorization_services/topics/resource-server/create-client.adoc[Creating a Client Application] - - ... link:authorization_services/topics/resource-server/enable-authorization.adoc[Enabling Authorization Services] - - ... link:authorization_services/topics/resource-server/default-config.adoc[Default Configuration] - - ... link:authorization_services/topics/resource-server/import-config.adoc[Export and Import Authorization Configuration] - - .. link:authorization_services/topics/resource/overview.adoc[Managing Resources and Scopes] - - ... link:authorization_services/topics/resource/view.adoc[Viewing Resources] - - ... link:authorization_services/topics/resource/create.adoc[Creating Resources] - - .. link:authorization_services/topics/policy/overview.adoc[Managing Policies] - - ... link:authorization_services/topics/policy/user-policy.adoc[User-Based Policy] - - ... link:authorization_services/topics/policy/role-policy.adoc[Role-Based Policy] - - .... link:authorization_services/topics/policy/role-policy-required-role.adoc[Defining a Role as Required] - - ... link:authorization_services/topics/policy/js-policy.adoc[JavaScript-Based Policy] - - ... link:authorization_services/topics/policy/drools-policy.adoc[Rule-Based Policy] - - ... link:authorization_services/topics/policy/time-policy.adoc[Time-Based Policy] - - ... link:authorization_services/topics/policy/aggregated-policy.adoc[Aggregated Policy] - - ... link:authorization_services/topics/policy/client-policy.adoc[Client Policy] - - ... link:authorization_services/topics/policy/logic.adoc[Positive and Negative Logic] - - ... link:authorization_services/topics/policy/evaluation-api.adoc[Policy Evaluation API] - - .. link:authorization_services/topics/permission/overview.adoc[Managing Permissions] - - ... link:authorization_services/topics/permission/create-resource.adoc[Creating Resource-Based Permissions] - - .... link:authorization_services/topics/permission/typed-resource-permission.adoc[Typed Resource Permissions] - - ... link:authorization_services/topics/permission/create-scope.adoc[Creating Scope-Based Permissions] - - ... link:authorization_services/topics/permission/decision-strategy.adoc[Policy Decision Strategies] - - .. link:authorization_services/topics/policy-evaluation-tool/overview.adoc[Evaluating and Testing Policies] - - .. link:authorization_services/topics/service/overview.adoc[Authorization Services] - - ... link:authorization_services/topics/service/protection/protection-api.adoc[Protection API] - - .... link:authorization_services/topics/service/protection/whatis-obtain-pat.adoc[What is a PAT and How to Obtain It] - - .... link:authorization_services/topics/service/protection/resources-api-papi.adoc[Managing Resources] - - .... link:authorization_services/topics/service/protection/permission-api-papi.adoc[Managing Permission Requests] - - ... link:authorization_services/topics/service/authorization/authorization-api.adoc[Authorization API] - - .... link:authorization_services/topics/service/authorization/whatis-obtain-aat.adoc[What is an AAT and How to Obtain It] - - .... link:authorization_services/topics/service/authorization/authorization-api-aapi.adoc[Requesting Authorization Data and Token] - - ... link:authorization_services/topics/service/entitlement/entitlement-api.adoc[Entitlement API] - - .... link:authorization_services/topics/service/entitlement/entitlement-api-aapi.adoc[Requesting Entitlements] - .... link:authorization_services/topics/service/entitlement/entitlement-request-metadata.adoc[Entitlement Request Metadata] - - ... link:authorization_services/topics/service/rpt/overview.adoc[Requesting Party Token (RPT)] - .... link:authorization_services/topics/service/rpt/token-introspection.adoc[Introspecting a Requesting Party Token] - - ... link:authorization_services/topics/service/client-api.adoc[Authorization Client Java API] - - .. link:authorization_services/topics/enforcer/overview.adoc[Policy Enforcers] - - ... link:authorization_services/topics/enforcer/keycloak-enforcement-filter.adoc[{{book.project.name}} Adapter Policy Enforcer] - - .... link:authorization_services/topics/enforcer/keycloak-enforcement-bearer.adoc[Protecting a Stateless Service Using a Bearer Token] - - .... link:authorization_services/topics/enforcer/authorization-context.adoc[Obtaining the Authorization Context] - - .... link:authorization_services/topics/enforcer/js-adapter.adoc[JavaScript Integration] - - .... link:authorization_services/topics/enforcer/https.adoc[Setting up TLS/HTTPS] - diff --git a/authorization_services/book-product.json b/authorization_services/book-product.json deleted file mode 100755 index e6df08daabe..00000000000 --- a/authorization_services/book-product.json +++ /dev/null @@ -1,54 +0,0 @@ -{ - "gitbook": "2.x.x", - "structure": { - "readme": "README.adoc" - }, - "plugins": [ - "toggle-chapters", - "ungrey", - "splitter" - ], - "variables": { - "title": "Authorization Services Guide", - "community": false, - "product": true, - "images": "rhsso-images", - "appServer": "JBoss EAP 7", - "quickstartRepo": { - "name": "Quickstarts for the Red Hat Single Sign-On (SSO) Server", - "dir": "redhat-sso-quickstarts", - "link": "https://github.com/redhat-developer/redhat-sso-quickstarts" - }, - "project": { - "name": "Red Hat Single Sign-On", - "version": "7.1.0", - "module": "Authorization Services", - "doc_base_url": "https://access.redhat.com/documentation/en-us/red_hat_single_sign-on/", - "doc_info_version_url": "7.1" - }, - "adapterguide": { - "name": "Securing Applications and Services Guide", - "link": "https://access.redhat.com/documentation/en-us/red_hat_single_sign-on/7.1/html-single/securing_applications_and_services_guide/" - }, - "keycloakjsadapter": { - "name": "JavaScript OpenID Connect Adapter", - "link": "https://access.redhat.com/documentation/en-us/red_hat_single_sign-on/7.1/html-single/securing_applications_and_services_guide#javascript_adapter" - }, - "gettingstarted": { - "name": "Getting Started", - "link": "https://access.redhat.com/documentation/en-us/red_hat_single_sign-on/7.1/html-single/getting_started_guide/" - }, - "keycloakinstallingandboot": { - "name": "Installing and Boot", - "link": "https://access.redhat.com/documentation/en-us/red_hat_single_sign-on/7.1/html-single/getting_started_guide/#install-boot" - }, - "keycloakinstallclientadapter": { - "name": "Installing the Client Adapter", - "link": "https://access.redhat.com/documentation/en-us/red_hat_single_sign-on/7.1/html-single/getting_started_guide/#installing_the_client_adapter" - }, - - "subsystem": { - "undertow": "urn:jboss:domain:undertow:3.1" - } - } -} diff --git a/authorization_services/buildGuide.sh b/authorization_services/buildGuide.sh deleted file mode 100755 index b37f0c97dd0..00000000000 --- a/authorization_services/buildGuide.sh +++ /dev/null @@ -1,80 +0,0 @@ -# Build the guide - -# Find the directory name and full path -CURRENT_GUIDE=${PWD##*/} -CURRENT_DIRECTORY=$(pwd) - -usage(){ - cat <&2 - usage - exit 1;; - esac -done - -echo "" -echo "********************************************" -echo " Building $CURRENT_GUIDE " -echo "********************************************" -if [ ! -d target ]; then - echo "You must run 'python gitlab-conversion.py' to convert the content before you run this script." - exit -fi - -# Remove the guide directory path from the master.adoc file as it is not needed -echo "" -echo "***************************************************************************************" -echo "Removing the guide directory path from the master.adoc file as it is not needed." -echo "NOTE: The guide directory path should probably be removed from the SUMMARY.adoc file," -echo "but since we do not know if it will break the upstream build, we are doing this here. " -echo "If it can not be removed from the SUMMARY.adoc file, this should really be done in the " -echo "Python script because otherwise you must run this script before porting content!" -echo "***************************************************************************************" -echo "" -find . -name 'master.adoc' -print | xargs sed -i "s/include::$CURRENT_GUIDE\//include::/g" - -# Remove the html and build directories and then recreate the html/images/ directory -if [ -d target/html ]; then - rm -r target/html/ -fi -if [ -d target/html ]; then - rm -r target/html/ -fi - -mkdir -p html -cp -r target/images/ target/html/ - -echo "Building an asciidoctor version of the guide" -asciidoctor -t -dbook -a toc -o target/html/$CURRENT_GUIDE.html target/master.adoc - -echo "" -echo "Building a ccutil version of the guide" -ccutil compile --lang en_US --format html-single --main-file target/master.adoc - -cd .. - -echo "View the asciidoctor build here: " file://$CURRENT_DIRECTORY/target/html/$CURRENT_GUIDE.html - -if [ -d $CURRENT_DIRECTORY/build/tmp/en-US/html-single/ ]; then - echo "View the ccutil build here: " file://$CURRENT_DIRECTORY/build/tmp/en-US/html-single/index.html - exit 0 -else - echo -e "${RED}Build using ccutil failed!" - echo -e "${BLACK}See the log above for details." - exit 1 -fi diff --git a/authorization_services/gitlab-conversion.py b/authorization_services/gitlab-conversion.py deleted file mode 100755 index f2e87906cc9..00000000000 --- a/authorization_services/gitlab-conversion.py +++ /dev/null @@ -1,113 +0,0 @@ -import sys, os, re, json, shutil, errno - -def transform(root, f, targetdir): - full = os.path.join(root, f) - input = open(full, 'r').read() - dir = os.path.join(targetdir, root) - if not os.path.exists(dir): - os.makedirs(dir) - output = open(os.path.join(dir, f), 'w') - input = applyTransformation(input) - output.write(input) - - -def applyTransformation(input): - for variable in re.findall(r"\{\{(.*?)\}\}", input): - tmp = variable.replace('.', '_') - input = input.replace(variable, tmp) - input = input.replace('{{', '{').replace('}}', '}') - input = re.sub(r"<}==true]\g<2>endif::[]", input) - input = re.sub(r"image:(\.\./)*", "image:", input) - input = re.sub(r"image::(\.\./)*", "image::", input) - return input - - -indir = 'topics' -targetdir = 'target' -if len(sys.argv) > 1: - targetdir = sys.argv[1] - -if os.path.exists(targetdir): - shutil.rmtree(targetdir) - -if os.path.isdir('images'): - shutil.copytree('images',os.path.join(targetdir, 'images')) -if os.path.isdir('keycloak-images'): - shutil.copytree('keycloak-images',os.path.join(targetdir, 'keycloak-images')) -if os.path.isdir('rhsso-images'): - shutil.copytree('rhsso-images',os.path.join(targetdir, 'rhsso-images')) - -shutil.copyfile('metadata.ini', os.path.join(targetdir, 'metadata.ini')); -shutil.copyfile('master-docinfo.xml', os.path.join(targetdir, 'master-docinfo.xml')); - -tmp = os.path.join(targetdir, 'topics') -if not os.path.exists(tmp): - os.makedirs(tmp) - -# transform files -for root, dirs, filenames in os.walk(indir): - for f in filenames: - transform(root,f,targetdir) - -# Create master.doc includes -input = open('SUMMARY.adoc', 'r').read() -output = open(os.path.join(targetdir, 'master.adoc'), 'w') - -output.write(""" -:toc: -:toclevels: 3 -:numbered: - -include::document-attributes.adoc[] -""") - -input = re.sub(r"[ ]*\.+\s*link:[^/]+/(.*)\[(.*)\]", "include::\g<1>[]", input) -input = applyTransformation(input) -output.write(input) - -# parse book-product.json file and create document attributes -with open('book-product.json') as data_file: - data = json.load(data_file) - -variables = data['variables'] - -def makeAttributes(variables, variable, list): - for i in variables.keys(): - if variable is None: - tmp = i - else: - tmp = variable + '_' + i - if isinstance(variables[i],dict): - makeAttributes(variables[i], tmp, list) - elif isinstance(variables[i],bool): - boolval = 'false' - if variables[i]: - boolval = 'true' - list.append({tmp: boolval}) - else: - list.append({tmp: str(variables[i])}) - - -attributeList = [] -makeAttributes(variables, None, attributeList) - -output = open(os.path.join(targetdir, 'document-attributes.adoc'), 'w') -for attribute in attributeList: - for k in attribute.keys(): - output.write(':book_' + k + ": " + attribute[k] + "\n") - -print "Transformation complete!" - - - - - - - - - diff --git a/authorization_services/index.adoc b/authorization_services/index.adoc new file mode 100644 index 00000000000..7e6c6cf73db --- /dev/null +++ b/authorization_services/index.adoc @@ -0,0 +1,6 @@ +:toc: +:toclevels: 3 +:numbered: + +include::../document-attributes-community.adoc[] +include::topics.adoc[] \ No newline at end of file diff --git a/authorization_services/master-docinfo.xml b/authorization_services/master-docinfo.xml old mode 100755 new mode 100644 index 08582b09c96..e51eb9ea4b5 --- a/authorization_services/master-docinfo.xml +++ b/authorization_services/master-docinfo.xml @@ -1,10 +1,10 @@ -{book_project_name} -{book_project_doc_info_version_url} -For Use with {book_project_name} {book_project_doc_info_version_url} -{book_title} +{project_name} +{project_doc_info_version_url} +For Use with {project_name} {project_doc_info_version_url} +{title} {doc_info_version_url} - This guide consists of information for authorization services for {book_project_name} {book_project_doc_info_version_url} + This guide consists of information for authorization services for {project_name} {project_doc_info_version_url} Red Hat Customer Content Services diff --git a/authorization_services/master.adoc b/authorization_services/master.adoc new file mode 100644 index 00000000000..cc0fdffa8d3 --- /dev/null +++ b/authorization_services/master.adoc @@ -0,0 +1,6 @@ +:toc: +:toclevels: 3 +:numbered: + +include::../document-attributes-product.adoc[] +include::topics.adoc[] \ No newline at end of file diff --git a/authorization_services/pom.xml b/authorization_services/pom.xml new file mode 100644 index 00000000000..8ea0bc963ee --- /dev/null +++ b/authorization_services/pom.xml @@ -0,0 +1,29 @@ + + + 4.0.0 + + + org.keycloak.documentation + documentation-parent + 1.0.0-SNAPSHOT + ../ + + + Authorization Services + authorization-services + pom + + + + + org.asciidoctor + asciidoctor-maven-plugin + + + asciidoc-to-html + + + + + + diff --git a/authorization_services/topics.adoc b/authorization_services/topics.adoc new file mode 100644 index 00000000000..0573845efb7 --- /dev/null +++ b/authorization_services/topics.adoc @@ -0,0 +1,106 @@ +include::topics/overview/overview.adoc[] + +include::topics/overview/architecture.adoc[] + +include::topics/overview/terminology.adoc[] + +include::topics/getting-started/overview.adoc[] + +include::topics/getting-started/hello-world/overview.adoc[] + +include::topics/getting-started/hello-world/create-realm.adoc[] + +include::topics/getting-started/hello-world/create-resource-server.adoc[] + +include::topics/getting-started/hello-world/deploy.adoc[] +ifeval::[{project_community}==true] +include::topics/example/overview.adoc[] +endif::[] + +include::topics/resource-server/overview.adoc[] + +include::topics/resource-server/create-client.adoc[] + +include::topics/resource-server/enable-authorization.adoc[] + +include::topics/resource-server/default-config.adoc[] + +include::topics/resource-server/import-config.adoc[] + +include::topics/resource/overview.adoc[] + +include::topics/resource/view.adoc[] + +include::topics/resource/create.adoc[] + +include::topics/policy/overview.adoc[] + +include::topics/policy/user-policy.adoc[] + +include::topics/policy/role-policy.adoc[] + +include::topics/policy/role-policy-required-role.adoc[] + +include::topics/policy/js-policy.adoc[] + +include::topics/policy/drools-policy.adoc[] + +include::topics/policy/time-policy.adoc[] + +include::topics/policy/aggregated-policy.adoc[] + +include::topics/policy/client-policy.adoc[] + +include::topics/policy/logic.adoc[] + +include::topics/policy/evaluation-api.adoc[] + +include::topics/permission/overview.adoc[] + +include::topics/permission/create-resource.adoc[] + +include::topics/permission/typed-resource-permission.adoc[] + +include::topics/permission/create-scope.adoc[] + +include::topics/permission/decision-strategy.adoc[] + +include::topics/policy-evaluation-tool/overview.adoc[] + +include::topics/service/overview.adoc[] + +include::topics/service/protection/protection-api.adoc[] + +include::topics/service/protection/whatis-obtain-pat.adoc[] + +include::topics/service/protection/resources-api-papi.adoc[] + +include::topics/service/protection/permission-api-papi.adoc[] + +include::topics/service/authorization/authorization-api.adoc[] + +include::topics/service/authorization/whatis-obtain-aat.adoc[] + +include::topics/service/authorization/authorization-api-aapi.adoc[] + +include::topics/service/entitlement/entitlement-api.adoc[] + +include::topics/service/entitlement/entitlement-api-aapi.adoc[] +include::topics/service/entitlement/entitlement-request-metadata.adoc[] + +include::topics/service/rpt/overview.adoc[] +include::topics/service/rpt/token-introspection.adoc[] + +include::topics/service/client-api.adoc[] + +include::topics/enforcer/overview.adoc[] + +include::topics/enforcer/keycloak-enforcement-filter.adoc[] + +include::topics/enforcer/keycloak-enforcement-bearer.adoc[] + +include::topics/enforcer/authorization-context.adoc[] + +include::topics/enforcer/js-adapter.adoc[] + +include::topics/enforcer/https.adoc[] \ No newline at end of file diff --git a/authorization_services/topics/enforcer/authorization-context.adoc b/authorization_services/topics/enforcer/authorization-context.adoc old mode 100755 new mode 100644 index 0b505edbcdf..298dbeaf2e2 --- a/authorization_services/topics/enforcer/authorization-context.adoc +++ b/authorization_services/topics/enforcer/authorization-context.adoc @@ -16,7 +16,7 @@ Obtaining the Authorization Context in a Servlet Container [NOTE] For more details about how you can obtain a `KeycloakSecurityContext` consult the adapter configuration. The example above should be sufficient -to obtain the context when running an application using any of the servlet containers supported by {{book.project.name}}. +to obtain the context when running an application using any of the servlet containers supported by {project_name}. The authorization context helps give you more control over the decisions made and returned by the server. For example, you can use it to build a dynamic menu where items are hidden or shown depending on the permissions associated with a resource or scope. @@ -35,7 +35,7 @@ if (authzContext.hasScopePermission("urn:project.com:project:create")) { } ``` -The `AuthorizationContext` represents one of the main capabilities of {{book.project.name}} {{book.project.module}}. From the examples above, you can see that the protected resource is not directly associated with the policies that govern them. +The `AuthorizationContext` represents one of the main capabilities of {project_name} Authorization Services. From the examples above, you can see that the protected resource is not directly associated with the policies that govern them. Consider some similar code using role-based access control (RBAC): @@ -53,15 +53,15 @@ if (User.hasRole('project-manager')) { } ``` -Although both examples address the same requirements, they do so in different ways. In RBAC, roles only _implicitly_ define access for their resources. With {{book.project.name}} you gain the capability to create more manageable code that focuses directly on your resources whether you are using RBAC, attribute-based access control (ABAC), or any other BAC variant. Either you have the permission for a given resource or scope, or you don't. +Although both examples address the same requirements, they do so in different ways. In RBAC, roles only _implicitly_ define access for their resources. With {project_name} you gain the capability to create more manageable code that focuses directly on your resources whether you are using RBAC, attribute-based access control (ABAC), or any other BAC variant. Either you have the permission for a given resource or scope, or you don't. Now, suppose your security requirements have changed and in addition to project managers, PMOs can also create new projects. -Security requirements change, but with {{book.project.name}} there is no need to change your application code to address the new requirements. Once your application is based on the resource and scope identifier, you need only change the configuration of the permissions or policies associated with a particular resource in the authorization server. In this case, the permissions and policies associated with the `Project Resource` and/or the scope `urn:project.com:project:create` would be changed. +Security requirements change, but with {project_name} there is no need to change your application code to address the new requirements. Once your application is based on the resource and scope identifier, you need only change the configuration of the permissions or policies associated with a particular resource in the authorization server. In this case, the permissions and policies associated with the `Project Resource` and/or the scope `urn:project.com:project:create` would be changed. ==== Using the AuthorizationContext to obtain an Authorization Client Instance -The ```AuthorizationContext``` can also be used to obtain a reference to the <> configured to your application: +The ```AuthorizationContext``` can also be used to obtain a reference to the <<_service_client_api, Authorization Client API>> configured to your application: ```java ClientAuthorizationContext clientContext = ClientAuthorizationContext.class.cast(authzContext); diff --git a/authorization_services/topics/enforcer/https.adoc b/authorization_services/topics/enforcer/https.adoc index 1a727bba208..a0e435cd8f5 100644 --- a/authorization_services/topics/enforcer/https.adoc +++ b/authorization_services/topics/enforcer/https.adoc @@ -12,8 +12,8 @@ When the server is using HTTPS, ensure your adapter is configured as follows: ``` The configuration above enables TLS/HTTPS to the Authorization Client, making possible to access a -{{book.project.name}} Server remotely using the HTTPS scheme. +{project_name} Server remotely using the HTTPS scheme. [NOTE] -It is strongly recommended that you enable TLS/HTTPS when accessing the {{book.project.name}} Server endpoints. +It is strongly recommended that you enable TLS/HTTPS when accessing the {project_name} Server endpoints. diff --git a/authorization_services/topics/enforcer/js-adapter.adoc b/authorization_services/topics/enforcer/js-adapter.adoc old mode 100755 new mode 100644 index ab95d939608..627a46d7dac --- a/authorization_services/topics/enforcer/js-adapter.adoc +++ b/authorization_services/topics/enforcer/js-adapter.adoc @@ -1,10 +1,10 @@ [[_enforcer_js_adapter]] ==== JavaScript Integration -The {{book.project.name}} Server comes with a JavaScript library you can use to interact with a resource server protected by a policy enforcer. -This library is based on the {{book.project.name}} JavaScript adapter, which can be integrated to allow your client to obtain permissions from a {{book.project.name}} Server. +The {project_name} Server comes with a JavaScript library you can use to interact with a resource server protected by a policy enforcer. +This library is based on the {project_name} JavaScript adapter, which can be integrated to allow your client to obtain permissions from a {project_name} Server. -You can obtain this library from a running a {{book.project.name}} Server instance by including the following `script` tag in your web page: +You can obtain this library from a running a {project_name} Server instance by including the following `script` tag in your web page: ```html @@ -17,18 +17,18 @@ var authorization = new KeycloakAuthorization(keycloak); ``` The *keycloak-authz.js* library provides two main features: -* Handle responses from a resource server protected by a <> and obtain a requesting party token (RPT) with the necessary permissions to gain access to the protected resources on the resource server. +* Handle responses from a resource server protected by a <<_enforcer_overview, {project_name} Policy Enforcer>> and obtain a requesting party token (RPT) with the necessary permissions to gain access to the protected resources on the resource server. -** In this case, the library can handle whatever authorization protocol the resource server is using: <> or <>. +** In this case, the library can handle whatever authorization protocol the resource server is using: <<_service_entitlement_api, Entitlements>>. -* Obtain permissions from a {{book.project.name}} Server using the <>. +* Obtain permissions from a {project_name} Server using the <<_service_entitlement_api, Entitlement API>>. -In both cases, the library allows you to easily interact with both resource server and {{book.project.name}} {{book.project.module}} to obtain tokens with +In both cases, the library allows you to easily interact with both resource server and {project_name} Authorization Services to obtain tokens with permissions your client can use as bearer tokens to access the protected resources on a resource server. ===== Handling Authorization Responses from a Resource Server -If a resource server is protected by a policy enforcer, it responds to client requests based on the permissions carried along with a <>. +If a resource server is protected by a policy enforcer, it responds to client requests based on the permissions carried along with a <<_enforcer_bearer, bearer token>>. Typically, when you try to access a resource server with a bearer token that is lacking permissions to access a protected resource, the resource server responds with a *401* status code and a `WWW-Authenticate` header. diff --git a/authorization_services/topics/enforcer/keycloak-enforcement-bearer.adoc b/authorization_services/topics/enforcer/keycloak-enforcement-bearer.adoc old mode 100755 new mode 100644 index e5a5f345eff..519c8b8edee --- a/authorization_services/topics/enforcer/keycloak-enforcement-bearer.adoc +++ b/authorization_services/topics/enforcer/keycloak-enforcement-bearer.adoc @@ -41,6 +41,6 @@ HTTP/1.1 401 Unauthorized WWW-Authenticate: KC_ETT realm="photoz-restful-api",as_uri="http://localhost:8080/auth/realms/photoz/authz/entitlement" ``` -Once a client receives a response from the server, it examines the status code and `WWW-Authenticate` header to obtain an RPT from the {{book.project.name}} Server. +Once a client receives a response from the server, it examines the status code and `WWW-Authenticate` header to obtain an RPT from the {project_name} Server. diff --git a/authorization_services/topics/enforcer/keycloak-enforcement-filter.adoc b/authorization_services/topics/enforcer/keycloak-enforcement-filter.adoc index 84845d0274b..81090e05c51 100644 --- a/authorization_services/topics/enforcer/keycloak-enforcement-filter.adoc +++ b/authorization_services/topics/enforcer/keycloak-enforcement-filter.adoc @@ -1,12 +1,12 @@ [[_enforcer_filter]] -=== {{book.project.name}} Adapter Policy Enforcer +=== {project_name} Adapter Policy Enforcer -You can enforce authorization decisions for your applications if you are using {{book.project.name}} OIDC adapters. +You can enforce authorization decisions for your applications if you are using {project_name} OIDC adapters. -When you enable policy enforcement for your {{book.project.name}} application, the corresponding adapter intercepts all requests to your application and enforces the authorization decisions obtained from the server. +When you enable policy enforcement for your {project_name} application, the corresponding adapter intercepts all requests to your application and enforces the authorization decisions obtained from the server. -Policy enforcement is strongly linked to your application's paths and the <> you created for a resource server using the {{book.project.name}} Administration Console. By default, -when you create a resource server, {{book.project.name}} creates a <> for your resource server so you can enable policy enforcement quickly. +Policy enforcement is strongly linked to your application's paths and the <<_resource_overview, resources>> you created for a resource server using the {project_name} Administration Console. By default, +when you create a resource server, {project_name} creates a <<_resource_server_default_config, default configuration>> for your resource server so you can enable policy enforcement quickly. The default configuration allows access for all resources in your application provided the authenticated user belongs to the same realm as the resource server being protected. @@ -68,7 +68,7 @@ Here is a description of each configuration option: * *policy-enforcer* + Specifies the configuration options that define how policies are actually enforced and optionally the paths you want to protect. If not specified, the policy enforcer queries the server -for all resources associated with the resource server being protected. In this case, you need to ensure the resources are properly configured with a <> property that matches the paths you want to protect. +for all resources associated with the resource server being protected. In this case, you need to ensure the resources are properly configured with a <<_resource_create_uri, URI>> property that matches the paths you want to protect. + ** *user-managed-access* + diff --git a/authorization_services/topics/enforcer/overview.adoc b/authorization_services/topics/enforcer/overview.adoc old mode 100755 new mode 100644 index 855b46ac39a..2f3581247f8 --- a/authorization_services/topics/enforcer/overview.adoc +++ b/authorization_services/topics/enforcer/overview.adoc @@ -1,8 +1,8 @@ [[_enforcer_overview]] == Policy Enforcers -Policy Enforcement Point (PEP) is a design pattern and as such you can implement it in different ways. {{book.project.name}} provides all the necessary means -to implement PEPs for different platforms, environments, and programming languages. {{book.project.name}} {{book.project.module}} presents a RESTful API, +Policy Enforcement Point (PEP) is a design pattern and as such you can implement it in different ways. {project_name} provides all the necessary means +to implement PEPs for different platforms, environments, and programming languages. {project_name} Authorization Services presents a RESTful API, and leverages OAuth2 authorization capabilities for fine-grained authorization using a centralized authorization server. -image:../../images/pep-pattern-diagram.png[alt="PEP Overview"] \ No newline at end of file +image:images/pep-pattern-diagram.png[alt="PEP Overview"] \ No newline at end of file diff --git a/authorization_services/topics/example/overview.adoc b/authorization_services/topics/example/overview.adoc old mode 100755 new mode 100644 index fd12772ee81..7b4327f9101 --- a/authorization_services/topics/example/overview.adoc +++ b/authorization_services/topics/example/overview.adoc @@ -1,12 +1,12 @@ [[_example_overview]] == Examples -The {{book.project.name}} Authorization can also help you to quickly get started with the authorization services and understand how to apply the same concepts to your +The {project_name} Authorization can also help you to quickly get started with the authorization services and understand how to apply the same concepts to your own applications. -If you are using the {{book.project.name}} Demo Distribution and you have it properly extracted in your file system: +If you are using the {project_name} Demo Distribution and you have it properly extracted in your file system: -* **keycloak-demo-{{book.project.version}}.[zip|tar.gz]** +* **keycloak-demo-{project_version}.[zip|tar.gz]** you can check out the available examples from the following directory: @@ -14,7 +14,7 @@ you can check out the available examples from the following directory: cd ${KEYCLOAK_DEMO_SERVER_DIR}/examples/authz ``` -Or you can get them from https://github.com/keycloak/keycloak/tree/{{book.project.version}}/examples/authz[GitHub]. +Or you can get them from https://github.com/keycloak/keycloak/tree/{project_version}/examples/authz[GitHub]. Each example has a `README` file with instructions about how to build, deploy, and test the example. @@ -24,12 +24,12 @@ Here is a brief description of each example: |=== |Name |Description -| https://github.com/keycloak/keycloak/tree/{{book.project.version}}/examples/authz/hello-world-authz-service[hello-world-authz-service] +| https://github.com/keycloak/keycloak/tree/{project_version}/examples/authz/hello-world-authz-service[hello-world-authz-service] | A single-page application that is protected by a policy enforcer that decides whether a user can access that page based on the permissions obtained from a Keycloak Server. -| https://github.com/keycloak/keycloak/tree/{{book.project.version}}/examples/authz/photoz[photoz] +| https://github.com/keycloak/keycloak/tree/{project_version}/examples/authz/photoz[photoz] | A simple application based on HTML5+AngularJS+JAX-RS that demonstrates how to enable fine-grained permissions to RESTFul based services and HTML5 clients. -| https://github.com/keycloak/keycloak/tree/{{book.project.version}}/examples/authz/servlet-authz[servlet-authz] +| https://github.com/keycloak/keycloak/tree/{project_version}/examples/authz/servlet-authz[servlet-authz] | A simple Servlet-based application that demonstrates how to enable fine-grained authorization to a JBoss/Wildfly Servlet Application. |=== diff --git a/authorization_services/topics/getting-started/hello-world/before-start.adoc b/authorization_services/topics/getting-started/hello-world/before-start.adoc index 43525f50da3..57ce8cec83f 100644 --- a/authorization_services/topics/getting-started/hello-world/before-start.adoc +++ b/authorization_services/topics/getting-started/hello-world/before-start.adoc @@ -1,15 +1,15 @@ === Before You Start -This guide is based on the *{{book.project.name}} Demo Distribution*. Download the demo distribution before proceeding. +This guide is based on the *{project_name} Demo Distribution*. Download the demo distribution before proceeding. [NOTE] -This guide assumes that you are already familiar with {{book.project.name}} and that you are able to install and boot a {{book.project.name}} Server. For more information, see https://keycloak.gitbooks.io/getting-started-tutorials/content/[the Getting Started tutorials]. +This guide assumes that you are already familiar with {project_name} and that you are able to install and boot a {project_name} Server. For more information, see https://keycloak.gitbooks.io/getting-started-tutorials/content/[the Getting Started tutorials]. -Ensure you have a {{book.project.name}} instance running; the default configuration is http://localhost:8080/auth[http://localhost:8080/auth]. After logging in to the +Ensure you have a {project_name} instance running; the default configuration is http://localhost:8080/auth[http://localhost:8080/auth]. After logging in to the Administration Console, a page similar to this one is displayed: -.{{book.project.name}} Administration Console -image:../../{{book.images}}/getting-started/kc-start-page.png[alt="{{book.project.name}} Administration Console"] +.{project_name} Administration Console +image:{project_images}/getting-started/kc-start-page.png[alt="{project_name} Administration Console"] The source code for the getting started tutorials can be obtained from the demo distributions. The authorization-related examples are located at *${KEYCLOAK_DEMO_SERVER_DIR}/examples/authz*. \ No newline at end of file diff --git a/authorization_services/topics/getting-started/hello-world/create-realm.adoc b/authorization_services/topics/getting-started/hello-world/create-realm.adoc index 791812e8d4e..28f413a93fd 100644 --- a/authorization_services/topics/getting-started/hello-world/create-realm.adoc +++ b/authorization_services/topics/getting-started/hello-world/create-realm.adoc @@ -5,14 +5,14 @@ The first step is to create a realm and a user in that realm. The realm consists * A single user -* A single client application, which then becomes a <> for which you need to enable authorization services. +* A single client application, which then becomes a <<_overview_terminology, resource server>> for which you need to enable authorization services. To create a realm and a user complete the following steps: . Create a realm with a name *hello-world-authz*. Once created, a page similar to the following is displayed: + .Realm hello-world-authz -image:../../../{{book.images}}/getting-started/hello-world/create-realm.png[alt="Realm hello-world-authz"] +image:{project_images}/getting-started/hello-world/create-realm.png[alt="Realm hello-world-authz"] . Create a user for your newly created realm. Click *Users*. The user list page opens. @@ -22,12 +22,12 @@ image:../../../{{book.images}}/getting-started/hello-world/create-realm.png[alt= Click the *User Enabled* switch to *On*, and then click *Save*. + .Add User -image:../../../{{book.images}}/getting-started/hello-world/create-user.png[alt="Add User"] +image:{project_images}/getting-started/hello-world/create-user.png[alt="Add User"] . Set a password for the user by clicking the *Credentials* tab. + .Set User Password -image:../../../{{book.images}}/getting-started/hello-world/reset-user-pwd.png[alt="Set User Password"] +image:{project_images}/getting-started/hello-world/reset-user-pwd.png[alt="Set User Password"] . Complete the *New Password* and *Password Confirmation* fields with a password and click the *Temporary* switch to *OFF*. diff --git a/authorization_services/topics/getting-started/hello-world/create-resource-server.adoc b/authorization_services/topics/getting-started/hello-world/create-resource-server.adoc index 42381e49b00..872584ff85d 100644 --- a/authorization_services/topics/getting-started/hello-world/create-resource-server.adoc +++ b/authorization_services/topics/getting-started/hello-world/create-resource-server.adoc @@ -8,12 +8,12 @@ To create a new client, complete the following steps: . Click *Clients* to start creating a new client application and fill in the *Client ID*, *Client Protocol*, and *Root URL* fields. + .Create Client Application -image:../../../{{book.images}}/getting-started/hello-world/create-client.png[alt="Create Client Application"] +image:{project_images}/getting-started/hello-world/create-client.png[alt="Create Client Application"] . Click *Save*. The Client Details page is displayed. + .Client Details -image:../../../{{book.images}}/getting-started/hello-world/enable-authz.png[alt="Client Details"] +image:{project_images}/getting-started/hello-world/enable-authz.png[alt="Client Details"] . On the Client Details page, click the *Authorization Enabled* switch to *ON*, and then click *Save*. A new *Authorization* tab is displayed for the client. @@ -21,8 +21,8 @@ A new *Authorization* tab is displayed for the client. . Click the *Authorization* tab and an Authorization Settings page similar to the following is displayed: + .Authorization Settings -image:../../../{{book.images}}/getting-started/hello-world/authz-settings.png[alt="Authorization Settings"] +image:{project_images}/getting-started/hello-world/authz-settings.png[alt="Authorization Settings"] -When you enable authorization services for a client application, {{book.project.name}} automatically creates several <> for your client authorization configuration. +When you enable authorization services for a client application, {project_name} automatically creates several <<_resource_server_default_config, default settings>> for your client authorization configuration. -For more information about authorization configuration, see <>. +For more information about authorization configuration, see <<_resource_server_enable_authorization, Enabling Authorization Services>>. diff --git a/authorization_services/topics/getting-started/hello-world/deploy.adoc b/authorization_services/topics/getting-started/hello-world/deploy.adoc index 5049dc31f52..f9a33b48d18 100644 --- a/authorization_services/topics/getting-started/hello-world/deploy.adoc +++ b/authorization_services/topics/getting-started/hello-world/deploy.adoc @@ -3,43 +3,43 @@ Now that the *app-authz-vanilla* resource server (or client) is properly configured and authorization services are enabled, it can be deployed to the server. -The project and code for the application you are going to deploy is available in link:{{book.quickstartRepo.link}}[{{book.quickstartRepo.name}}]. You will need the following +The project and code for the application you are going to deploy is available in link:{quickstartRepo_link}[{quickstartRepo_name}]. You will need the following installed on your machine and available in your PATH before you can continue: * Java JDK 8 * Apache Maven 3.1.1 or higher * Git -You can obtain the code by cloning the repository at {{book.quickstartRepo.link}}. The default branch corresponds to the latest release of {{book.project.name}}. Follow these steps to download the code. +You can obtain the code by cloning the repository at {quickstartRepo_link}. The default branch corresponds to the latest release of {project_name}. Follow these steps to download the code. .Clone Project [source, subs="attributes"] ---- -$ git clone {{book.quickstartRepo.link}} +$ git clone {quickstartRepo_link} ---- The application we are about to build and deploy is located at [source, subs="attributes"] ---- -$ cd {{book.quickstartRepo.dir}}/app-authz-jee-vanilla +$ cd {quickstartRepo_dir}/app-authz-jee-vanilla ---- ==== Obtaining the Adapter Configuration You must first obtain the adapter configuration before building and deploying the application. -To obtain the adapter configuration from the {{book.project.name}} Administration Console, complete the following steps. +To obtain the adapter configuration from the {project_name} Administration Console, complete the following steps. . Click *Clients*. In the client listing, click the *app-authz-vanilla* client application. The Client Details page opens. + .Client Details -image:../../../{{book.images}}/getting-started/hello-world/enable-authz.png[alt="Client Details"] +image:{project_images}/getting-started/hello-world/enable-authz.png[alt="Client Details"] . Click the *Installation* tab. From the Format Option dropdown list, select *Keycloak OIDC JSON*. The adapter configuration is displayed in JSON format. Click *Download*. + .Adapter Configuration -image:../../../{{book.images}}/getting-started/hello-world/adapter-config.png[alt="Adapter Configuration"] +image:{project_images}/getting-started/hello-world/adapter-config.png[alt="Adapter Configuration"] . Move the file `keycloak.json` to the `app-authz-jee-vanilla/config` directory. @@ -64,21 +64,21 @@ $ mvn clean package wildfly:deploy ==== Testing the Application -If your application was successfully deployed you can access it at http://localhost:8080/app-authz-vanilla[http://localhost:8080/app-authz-vanilla]. The {{book.project.name}} Login page opens. +If your application was successfully deployed you can access it at http://localhost:8080/app-authz-vanilla[http://localhost:8080/app-authz-vanilla]. The {project_name} Login page opens. .Login Page -image:../../../{{book.images}}/getting-started/hello-world/login-page.png[alt="Login Page"] +image:{project_images}/getting-started/hello-world/login-page.png[alt="Login Page"] Log in as *alice* using the password you specified for that user. After authenticating, the following page is displayed: .Hello World Authz Main Page -image:../../../{{book.images}}/getting-started/hello-world/main-page.png[alt="Hello World Authz Main Page"] +image:{project_images}/getting-started/hello-world/main-page.png[alt="Hello World Authz Main Page"] -The <> defined by {{book.project.name}} when you enable authorization services for a client application provide a simple +The <<_resource_server_default_config, default settings>> defined by {project_name} when you enable authorization services for a client application provide a simple policy that always grants access to the resources protected by this policy. You can start by changing the default permissions and policies and test how your application responds, or even create new policies using the different -<> provided by {{book.project.name}}. +<<_policy_overview, policy types>> provided by {project_name}. There are a plenty of things you can do now to test this application. For example, you can change the default policy by clicking the Authorization tab for the client, then `Policies` tab, then click on `Default Policy` in the list to allow you to change it as follows: @@ -91,7 +91,7 @@ $evaluation.deny(); Now, log out of the demo application and log in again. You can no longer access the application. -image:../../../{{book.images}}/getting-started/hello-world/access-denied-page.png[alt="Access Denied Page"] +image:{project_images}/getting-started/hello-world/access-denied-page.png[alt="Access Denied Page"] Let's fix that now, but instead of changing the `Default Policy` code we are going to change the `Logic` to `Negative` using the dropdown list below the policy code text area. That re-enables access to the application as we are negating the result of that policy, which is by default denying all requests for access. Again, before testing this change, be sure to log out and log in again. @@ -101,6 +101,6 @@ That re-enables access to the application as we are negating the result of that There are additional things you can do, such as: * Create a scope, define a policy and permission for it, and test it on the application side. Can the user perform an action (or anything else represented by the scope you created)? -* Create different types of policies such as <>, <>, <>, <>, or <>, and associate these policies with the `Default Permission`. +* Create different types of policies such as <<_policy_drools, rule-based>>, and associate these policies with the `Default Permission`. * Apply multiple policies to the `Default Permission` and test the behavior. For example, combine multiple policies and change the `Decision Strategy` accordingly. -* For more information about how to view and test permissions inside your application see <>. \ No newline at end of file +* For more information about how to view and test permissions inside your application see <<_enforcer_authorization_context, Obtaining the Authorization Context>>. \ No newline at end of file diff --git a/authorization_services/topics/getting-started/hello-world/overview.adoc b/authorization_services/topics/getting-started/hello-world/overview.adoc index 935f679fa5b..177dc2b88c1 100644 --- a/authorization_services/topics/getting-started/hello-world/overview.adoc +++ b/authorization_services/topics/getting-started/hello-world/overview.adoc @@ -1,11 +1,11 @@ [[_getting_started_hello_world_overview]] === Securing a Servlet Application -The purpose of this getting started guide is to get you up and running as quickly as possible so that you can experiment with and test various authorization features provided by {{book.project.name}}. +The purpose of this getting started guide is to get you up and running as quickly as possible so that you can experiment with and test various authorization features provided by {project_name}. This quick tour relies heavily on the default database and server configurations and does not cover complex deployment options. For more information on features or configuration options, see the appropriate sections in this documentation. -This guide explains key concepts about {{book.project.name}} {{book.project.module}}: +This guide explains key concepts about {project_name} Authorization Services: * Enabling fine-grained authorization for a client application * Configuring a client application to be a resource server, with protected resources diff --git a/authorization_services/topics/getting-started/overview.adoc b/authorization_services/topics/getting-started/overview.adoc index 9b72e135157..2a7904fd702 100644 --- a/authorization_services/topics/getting-started/overview.adoc +++ b/authorization_services/topics/getting-started/overview.adoc @@ -1,10 +1,10 @@ [[_getting_started_overview]] == Getting Started -Before you can use this tutorial, you need to complete the installation of {{book.project.name}} and create the initial admin user as shown in the link:{{book.gettingstarted.link}}[{{book.gettingstarted.name}}] tutorial. -There is one caveat to this. You have to run a separate {{book.appServer}} instance on the same machine as {{book.project.name}} Server. This separate instance will run your Java Servlet application. Because of this you will have to run the {{book.project.name}} under a different port so that there are no port conflicts when running on the same machine. Use the `jboss.socket.binding.port-offset` system property on the command line. The value of this property is a number that will be added to the base value of every port opened by {{book.project.name}} Server. +Before you can use this tutorial, you need to complete the installation of {project_name} and create the initial admin user as shown in the link:{gettingstarted_link}[{gettingstarted_name}] tutorial. +There is one caveat to this. You have to run a separate {appServer} instance on the same machine as {project_name} Server. This separate instance will run your Java Servlet application. Because of this you will have to run the {project_name} under a different port so that there are no port conflicts when running on the same machine. Use the `jboss.socket.binding.port-offset` system property on the command line. The value of this property is a number that will be added to the base value of every port opened by {project_name} Server. -To boot {{book.project.name}} Server: +To boot {project_name} Server: .Linux/Unix [source] @@ -18,7 +18,7 @@ $ .../bin/standalone.sh -Djboss.socket.binding.port-offset=100 > ...\bin\standalone.bat -Djboss.socket.binding.port-offset=100 ---- -For more details about how to install and configure a {{book.appServer}}, please follow the steps on the link:{{book.adapterguide.link}}[{{book.adapterguide.name}}] tutorial. +For more details about how to install and configure a {appServer}, please follow the steps on the link:{adapterguide_link}[{adapterguide_name}] tutorial. -After installing and booting both servers you should be able to access {{book.project.name}} Admin Console at http://localhost:8180/auth/admin/ and also the {{book.appServer}} instance at +After installing and booting both servers you should be able to access {project_name} Admin Console at http://localhost:8180/auth/admin/ and also the {appServer} instance at http://localhost:8080. diff --git a/authorization_services/topics/overview/architecture.adoc b/authorization_services/topics/overview/architecture.adoc old mode 100755 new mode 100644 index 6b5cd52348c..8f7f0db1829 --- a/authorization_services/topics/overview/architecture.adoc +++ b/authorization_services/topics/overview/architecture.adoc @@ -1,35 +1,35 @@ [[_overview_architecture]] === Architecture -image:../../images/authz-arch-overview.png[alt="{{book.project.name}} AuthZ Architecture Overview"] +image:images/authz-arch-overview.png[alt="{project_name} AuthZ Architecture Overview"] -From a design perspective, {{book.project.module}} is based on a well-defined set of authorization patterns providing these capabilities: +From a design perspective, Authorization Services is based on a well-defined set of authorization patterns providing these capabilities: * **Policy Administration Point (PAP)** + -Provides a set of UIs based on the {{book.project.name}} Administration Console to manage resource servers, resources, scopes, permissions, and policies. -Part of this is also accomplished remotely through the use of the <>. +Provides a set of UIs based on the {project_name} Administration Console to manage resource servers, resources, scopes, permissions, and policies. +Part of this is also accomplished remotely through the use of the <<_service_protection_api, Protection API>>. + * **Policy Decision Point (PDP)** + Provides a distributable policy decision point to where authorization requests are sent and policies are evaluated accordingly with the permissions being requested. Part of this is also accomplished remotely through the use of the -<> and <> APIs. +<<_service_entitlement_api, Entitlement>> APIs. + * **Policy Enforcement Point (PEP)** + Provides implementations for different environments to actually enforce authorization decisions at the resource server side. -{{book.project.name}} provides some built-in <>. +{project_name} provides some built-in <<_enforcer_overview, Policy Enforcers>>. + * **Policy Information Point (PIP)** + -Being based on {{book.project.name}} Authentication Server, you can obtain attributes from identities and runtime environment during the evaluation of authorization policies. +Being based on {project_name} Authentication Server, you can obtain attributes from identities and runtime environment during the evaluation of authorization policies. ==== The Authorization Process -Three main processes define the necessary steps to understand how to use {{book.project.name}} to enable fine-grained authorization to your applications: +Three main processes define the necessary steps to understand how to use {project_name} to enable fine-grained authorization to your applications: * *Resource Management* * *Permission and Policy Management* @@ -39,19 +39,19 @@ Three main processes define the necessary steps to understand how to use {{book. *Resource Management* involves all the necessary steps to define what is being protected. -image:../../images/resource-mgmt-process.png[alt="Resource Management Overview"] +image:images/resource-mgmt-process.png[alt="Resource Management Overview"] -First, you need to specify {{book.project.name}} what are you looking to protect, which usually represents a web application or a set of one or more services. For more information on resource servers see <>. +First, you need to specify {project_name} what are you looking to protect, which usually represents a web application or a set of one or more services. For more information on resource servers see <<_overview_terminology, Terminology>>. -Resource servers are managed using the {{book.project.name}} Administration Console. There you can enable any registered client application as a resource server and start managing the resources and scopes you want to protect. +Resource servers are managed using the {project_name} Administration Console. There you can enable any registered client application as a resource server and start managing the resources and scopes you want to protect. -image:../../images/rs-r-scopes.png[alt="Resource Server Overview"] +image:images/rs-r-scopes.png[alt="Resource Server Overview"] A resource can be a web page, a RESTFul resource, a file in your file system, an EJB, and so on. They can represent a group of resources (just like a Class in Java) or they can represent a single and specific resource. For instance, you might have a _Bank Account_ resource that represents all banking accounts and use it to define the authorization policies that are common to all banking accounts. However, you might want to define specific policies for _Alice Account_ (a resource instance that belongs to a customer), where only the owner is allowed to access some information or perform an operation. -Resources can be managed using the {{book.project.name}} Administration Console or the <>. In the latter case, resource servers are able to manage their resources remotely. +Resources can be managed using the {project_name} Administration Console or the <<_service_protection_api, Protection API>>. In the latter case, resource servers are able to manage their resources remotely. Scopes usually represent the actions that can be performed on a resource, but they are not limited to that. You can also use scopes to represent one or more attributes within a resource. @@ -61,13 +61,13 @@ Once you have defined your resource server and all the resources you want to pro This process involves all the necessary steps to actually define the security and access requirements that govern your resources. -image:../../images/policy-mgmt-process.png[alt="Permission and Policy Management Overview"] +image:images/policy-mgmt-process.png[alt="Permission and Policy Management Overview"] Policies define the conditions that must be satisfied to access or perform operations on something (resource or scope), but they are not tied to what they are protecting. They are generic and can be reused to build permissions or even more complex policies. For instance,to allow access to a group of resources only for users granted with a role "User Premium,"" you can use RBAC (Role-based Access Control). -{{book.project.name}} provides a few built-in policy types (and their respective policy providers) covering the most common access control mechanisms. You can even create policies based on rules written using JavaScript or JBoss Drools. +{project_name} provides a few built-in policy types (and their respective policy providers) covering the most common access control mechanisms. You can even create policies based on rules written using JavaScript or JBoss Drools. Once you have your policies defined, you can start defining your permissions. Permissions are coupled with the resource they are protecting. Here you specify what you want to protect (resource or scope) and the policies that must be satisfied to grant or deny permission. @@ -76,9 +76,9 @@ what you want to protect (resource or scope) and the policies that must be satis *Policy Enforcement* involves the necessary steps to actually enforce authorization decisions to a resource server. This is achieved by enabling a *Policy Enforcement Point* or PEP at the resource server that is capable of communicating with the authorization server, ask for authorization data and control access to protected resources based on the decisions and permissions returned by the server. -image:../../images/pep-pattern-diagram.png[alt="PEP Overview"] +image:images/pep-pattern-diagram.png[alt="PEP Overview"] -{{book.project.name}} provides some built-in <> implementations that you can use to protect your applications depending on the platform they are running on. +{project_name} provides some built-in <<_enforcer_overview, Policy Enforcers>> implementations that you can use to protect your applications depending on the platform they are running on. ==== Authorization Services @@ -109,24 +109,24 @@ The operations provided by the Protection API can be organized in two main group ** Issue Permission Tickets [NOTE] -By default, Remote Resource Management is enabled. You can change that using the {{book.project.name}} Administration Console and only allow resource management through the console. +By default, Remote Resource Management is enabled. You can change that using the {project_name} Administration Console and only allow resource management through the console. When using the UMA protocol, the issuance of Permission Tickets by the Protection API is an important part of the whole authorization process. As described in a subsequent section, they represent the permissions being requested by the client and that are sent to the server to obtain a final token with all permissions granted during the evaluation of the permissions and policies associated with the resources and scopes being requested. -For more information, see <>. +For more information, see <<_service_protection_api, Protection API>>. ===== Authorization API -The Authorization API is also a https://docs.kantarainitiative.org/uma/rec-uma-core.html[UMA-compliant] endpoint providing a single operation that exchanges an Access Token and <> with a Requesting Party Token (RPT). +The Authorization API is also a https://docs.kantarainitiative.org/uma/rec-uma-core.html[UMA-compliant] endpoint providing a single operation that exchanges an Access Token and <<_overview_terminology_permission_ticket, Permission Ticket>> with a Requesting Party Token (RPT). The RPT contains all permissions granted to a client and can be used to call a resource server to get access to its protected resources. When requesting an RPT you can also provide a previously issued RPT. In this case, the resulting RPT will consist of the union of the permissions from the previous RPT and the new ones within a permission ticket. -image:../../images/authz-calls.png[alt="Authorization API Overview"] +image:images/authz-calls.png[alt="Authorization API Overview"] -For more information, see <>. +For more information, see <<_service_authorization_api, Authorization API>>. ==== Entitlement API @@ -135,9 +135,9 @@ The Entitlement API provides a 1-legged protocol to issue RPTs. Unlike the Autho From this API you can obtain all the entitlements or permissions for a user (based on the resources managed by a given resource server) or just the entitlements for a set of one or more resources. -image:../../images/entitlement-calls.png[alt="Entitlement API Overview"] +image:images/entitlement-calls.png[alt="Entitlement API Overview"] -For more information see <>. +For more information see <<_service_entitlement_api, Entitlement API>>. diff --git a/authorization_services/topics/overview/overview.adoc b/authorization_services/topics/overview/overview.adoc old mode 100755 new mode 100644 index 58625c9fa71..596653ec880 --- a/authorization_services/topics/overview/overview.adoc +++ b/authorization_services/topics/overview/overview.adoc @@ -1,14 +1,14 @@ [[_overview]] == Overview -{% if book.product %} -NOTE: {{book.project.module}} is a Technology Preview feature and is not fully supported. This feature is disabled by default. +ifeval::[{project_product}==true] +NOTE: Authorization Services is a Technology Preview feature and is not fully supported. This feature is disabled by default. -To enable {{book.project.module}} add the `standalone/configuration/profile.properties` file with the contents `profile=preview` +To enable Authorization Services add the `standalone/configuration/profile.properties` file with the contents `profile=preview` or start the server with `-Dkeycloak.profile=preview` to enable all technology preview features. -{% endif %} +endif::[] -{{book.project.name}} supports fine-grained authorization policies and is able to combine different access control +{project_name} supports fine-grained authorization policies and is able to combine different access control mechanisms such as: * **Attribute-based access control (ABAC)** @@ -21,7 +21,7 @@ mechanisms such as: * **Time-based access control** * **Support for custom access control mechanisms (ACMs) through a Policy Provider Service Provider Interface (SPI)** -{{book.project.name}} is based on a set of administrative UIs and a RESTful API, and provides the necessary means to create permissions +{project_name} is based on a set of administrative UIs and a RESTful API, and provides the necessary means to create permissions for your protected resources and scopes, associate those permissions with authorization policies, and enforce authorization decisions in your applications and services. Resource servers (applications or services serving protected resources) usually rely on some kind of information to decide if access should be granted to a protected resource. For RESTful-based resource servers, that information is usually obtained from a security token, usually sent as a bearer token on every request to the server. For web applications that rely on a session to authenticate users, that information is usually stored in a user's session and retrieved from there for each request. @@ -34,7 +34,7 @@ Frequently, resource servers only perform authorization decisions based on role- * It is not the most flexible access control mechanism. Roles do not represent who you are and lack contextual information. If you have been granted a role, you have at least some access. Considering that today we need to consider heterogeneous environments where users are distributed across different regions, with different local policies, -using different devices, and with a high demand for information sharing, {{book.project.name}} Authorization Services can help you improve the authorization capabilities of your applications and services by providing: +using different devices, and with a high demand for information sharing, {project_name} Authorization Services can help you improve the authorization capabilities of your applications and services by providing: * Resource protection using fine-grained authorization policies and different access control mechanisms * Centralized Resource, Permission, and Policy Management diff --git a/authorization_services/topics/overview/terminology.adoc b/authorization_services/topics/overview/terminology.adoc old mode 100755 new mode 100644 index 749dee456e7..1e7a37c1b23 --- a/authorization_services/topics/overview/terminology.adoc +++ b/authorization_services/topics/overview/terminology.adoc @@ -1,7 +1,7 @@ [[_overview_terminology]] === Terminology -Before going further, it is important to understand these terms and concepts introduced by {{book.project.name}} {{book.project.module}}. +Before going further, it is important to understand these terms and concepts introduced by {project_name} Authorization Services. [[_overview_terminology_resource_server]] ==== Resource Server @@ -12,7 +12,7 @@ Resource servers usually rely on some kind of information to decide whether acce that information is usually carried in a security token, typically sent as a bearer token along with every request to the server. Web applications that rely on a session to authenticate users usually store that information in the user's session and retrieve it from there for each request. -In {{book.project.name}}, any *confidential* client application can act as a resource server. This client's resources and their respective scopes are protected and governed by a set of authorization policies. +In {project_name}, any *confidential* client application can act as a resource server. This client's resources and their respective scopes are protected and governed by a set of authorization policies. ==== Resource @@ -39,7 +39,7 @@ A permission associates the object being protected with the policies that must b *** *Y* represents an action to be performed, for example, write, view, and so on. *** *Z* represents a protected resource, for example, "/accounts". -{{book.project.name}} provides a rich platform for building a range of permission strategies ranging from simple to very complex, rule-based dynamic permissions. It provides flexibility and helps to: +{project_name} provides a rich platform for building a range of permission strategies ranging from simple to very complex, rule-based dynamic permissions. It provides flexibility and helps to: * Reduce code refactoring and permission management costs * Support a more flexible security model, helping you to easily adapt to changes in your security requirements @@ -52,16 +52,16 @@ but rather the conditions that must be satisfied for access to a given object (f Policies are strongly related to the different access control mechanisms (ACMs) that you can use to protect your resources. With policies, you can implement strategies for attribute-based access control (ABAC), role-based access control (RBAC), context-based access control, or any combination of these. -{{book.project.name}} leverages the concept of policies and how you define them by providing the concept of aggregated policies, where you can build a "policy of policies" and still control the behavior of the evaluation. -Instead of writing one large policy with all the conditions that must be satisfied for access to a given resource, the policies implementation in {{book.project.name}} {{book.project.module}} follows the divide-and-conquer technique. +{project_name} leverages the concept of policies and how you define them by providing the concept of aggregated policies, where you can build a "policy of policies" and still control the behavior of the evaluation. +Instead of writing one large policy with all the conditions that must be satisfied for access to a given resource, the policies implementation in {project_name} Authorization Services follows the divide-and-conquer technique. That is, you can create individual policies, then reuse them with different permissions and build more complex policies by combining individual policies. ==== Policy Provider -Policy providers are implementations of specific policy types. {{book.project.name}} provides built-in policies, backed by their corresponding +Policy providers are implementations of specific policy types. {project_name} provides built-in policies, backed by their corresponding policy providers, and you can create your own policy types to support your specific requirements. -{{book.project.name}} provides a SPI (Service Provider Interface) that you can use to plug in your own policy provider implementations. +{project_name} provides a SPI (Service Provider Interface) that you can use to plug in your own policy provider implementations. [[_overview_terminology_permission_ticket]] ==== Permission Ticket @@ -73,4 +73,4 @@ In UMA, permission tickets are crucial to support person-to-person sharing and a In the UMA workflow, permission tickets are issued by the authorization server to a resource server, which returns the permission ticket to the client trying to access a protected resource. Once the client receives the ticket, it can make a request for an RPT (a final token holding authorization data) by sending the ticket back to the authorization server. -For more information on permission tickets, see <> and the https://docs.kantarainitiative.org/uma/rec-uma-core.html[UMA] specification. \ No newline at end of file +For more information on permission tickets, see <<_service_authorization_api, Authorization API>> and the https://docs.kantarainitiative.org/uma/rec-uma-core.html[UMA] specification. \ No newline at end of file diff --git a/authorization_services/topics/permission/create-resource.adoc b/authorization_services/topics/permission/create-resource.adoc old mode 100755 new mode 100644 index 1ee69550a82..991fc59fd78 --- a/authorization_services/topics/permission/create-resource.adoc +++ b/authorization_services/topics/permission/create-resource.adoc @@ -6,7 +6,7 @@ A resource-based permission defines a set of one or more resources to protect us To create a new resource-based permission, select *Resource-based* in the dropdown list in the upper right corner of the permission listing. .Add Resource-Based Permission -image:../../{{book.images}}/permission/create-resource.png[alt="Add Resource-Based Permission"] +image:{project_images}/permission/create-resource.png[alt="Add Resource-Based Permission"] ==== Configuration @@ -38,4 +38,4 @@ Defines a set of one or more policies to associate with a permission. * *Decision Strategy* + -The <> for this permission. \ No newline at end of file +The <<_permission_decision_strategies, Decision Strategy>> for this permission. \ No newline at end of file diff --git a/authorization_services/topics/permission/create-scope.adoc b/authorization_services/topics/permission/create-scope.adoc old mode 100755 new mode 100644 index b1e8729c0dd..1180455862e --- a/authorization_services/topics/permission/create-scope.adoc +++ b/authorization_services/topics/permission/create-scope.adoc @@ -6,7 +6,7 @@ A scope-based permission defines a set of one or more scopes to protect using a To create a new scope-based permission, select *Scope-based* in the dropdown list in the upper right corner of the permission listing. .Add Scope-Based Permission -image:../../{{book.images}}/permission/create-scope.png[alt="Add Scope-Based Permission"] +image:{project_images}/permission/create-scope.png[alt="Add Scope-Based Permission"] ==== Configuration @@ -33,4 +33,4 @@ Defines a set of one or more policies to associate with a permission. * *Decision Strategy* + -The <> for this permission. \ No newline at end of file +The <<_permission_decision_strategies, Decision Strategy>> for this permission. \ No newline at end of file diff --git a/authorization_services/topics/permission/decision-strategy.adoc b/authorization_services/topics/permission/decision-strategy.adoc old mode 100755 new mode 100644 diff --git a/authorization_services/topics/permission/overview.adoc b/authorization_services/topics/permission/overview.adoc old mode 100755 new mode 100644 index b9f7d227ca8..adfd596b99b --- a/authorization_services/topics/permission/overview.adoc +++ b/authorization_services/topics/permission/overview.adoc @@ -7,7 +7,7 @@ After creating the resources you want to protect and the policies you want to us you can start managing permissions. To manage permissions, click the *Permissions* tab when editing a resource server. .Permissions -image:../../{{book.images}}/permission/view.png[alt="Permissions"] +image:{project_images}/permission/view.png[alt="Permissions"] Permissions can be created to protect two main types of objects: diff --git a/authorization_services/topics/permission/typed-resource-permission.adoc b/authorization_services/topics/permission/typed-resource-permission.adoc old mode 100755 new mode 100644 index e73be604b25..090a38c7ecf --- a/authorization_services/topics/permission/typed-resource-permission.adoc +++ b/authorization_services/topics/permission/typed-resource-permission.adoc @@ -1,7 +1,7 @@ [[_permission_typed_resource]] ==== Typed Resource Permission -Resource permissions can also be used to define policies that are to be applied to all resources with a given <>. This form of resource-based permission can be useful when you have resources sharing common access requirements and constraints. +Resource permissions can also be used to define policies that are to be applied to all resources with a given <<_resource_create_type, type>>. This form of resource-based permission can be useful when you have resources sharing common access requirements and constraints. Frequently, resources within an application can be categorized (or typed) based on the data they encapsulate or the functionality they provide. For example, a financial application can manage different banking accounts where each one belongs to a specific customer. Although they are different banking accounts, they share common security requirements and constraints that are globally defined by the banking organization. With typed resource permissions, you can define common policies to apply to all banking accounts, such as: @@ -9,8 +9,8 @@ Frequently, resources within an application can be categorized (or typed) based * Only allow access from the owner's country and/or region * Enforce a specific authentication method -To create a typed resource permission, click <> when creating a new resource-based permission. With `Apply to Resource Type` set to `On`, +To create a typed resource permission, click <<_permission_create_resource_apply_resource_type, Apply to Resource Type>> when creating a new resource-based permission. With `Apply to Resource Type` set to `On`, you can specify the type that you want to protect as well as the policies that are to be applied to govern access to all resources with type you have specified. .Example of a Typed Resource Permission -image:../../{{book.images}}/permission/typed-resource-perm-example.png[alt="Example of a Typed Resource Permission"] \ No newline at end of file +image:{project_images}/permission/typed-resource-perm-example.png[alt="Example of a Typed Resource Permission"] \ No newline at end of file diff --git a/authorization_services/topics/policy-evaluation-tool/overview.adoc b/authorization_services/topics/policy-evaluation-tool/overview.adoc old mode 100755 new mode 100644 index 7b66f706f9a..76819b68a9b --- a/authorization_services/topics/policy-evaluation-tool/overview.adoc +++ b/authorization_services/topics/policy-evaluation-tool/overview.adoc @@ -5,7 +5,7 @@ When designing your policies, you can simulate authorization requests to test ho You can access the Policy Evaluation Tool by clicking the `Evaluate` tab when editing a resource server. There you can specify different inputs to simulate real authorization requests and test the effect of your policies. -image:../../{{book.images}}/policy-evaluation-tool/policy-evaluation-tool.png[alt="Policy Evaluation Tool"] +image:{project_images}/policy-evaluation-tool/policy-evaluation-tool.png[alt="Policy Evaluation Tool"] === Providing Identity Information diff --git a/authorization_services/topics/policy/aggregated-policy.adoc b/authorization_services/topics/policy/aggregated-policy.adoc old mode 100755 new mode 100644 index 88af8e7516a..9a1f5338e36 --- a/authorization_services/topics/policy/aggregated-policy.adoc +++ b/authorization_services/topics/policy/aggregated-policy.adoc @@ -1,12 +1,12 @@ [[_policy_aggregated]] === Aggregated Policy -As mentioned previously, {{book.project.name}} allows you to build a policy of policies, a concept referred to as policy aggregation. You can use policy aggregation to reuse existing policies to build more complex ones and keep your permissions even more decoupled from the policies that are evaluated during the processing of authorization requests. +As mentioned previously, {project_name} allows you to build a policy of policies, a concept referred to as policy aggregation. You can use policy aggregation to reuse existing policies to build more complex ones and keep your permissions even more decoupled from the policies that are evaluated during the processing of authorization requests. To create a new aggregated policy, select *Aggregated* in the dropdown list located in the right upper corner of the policy listing. .Add an Aggregated Policy -image:../../{{book.images}}/policy/create-aggregated.png[alt="Add Aggregated Policy"] +image:{project_images}/policy/create-aggregated.png[alt="Add Aggregated Policy"] Let's suppose you have a resource called _Confidential Resource_ that can be accessed only by users from the _keycloak.org_ domain and from a certain range of IP addresses. You can create a single policy with both conditions. However, you want to reuse the domain part of this policy to apply to permissions that operates regardless of the originating network. @@ -37,7 +37,7 @@ The decision strategy for this permission. + * *Logic* + -The <> of this policy to apply after the other conditions have been evaluated. +The <<_policy_logic, Logic>> of this policy to apply after the other conditions have been evaluated. ==== Decision Strategy for Aggregated Policies diff --git a/authorization_services/topics/policy/client-policy.adoc b/authorization_services/topics/policy/client-policy.adoc index fa278769ccb..ab333e4ff8d 100644 --- a/authorization_services/topics/policy/client-policy.adoc +++ b/authorization_services/topics/policy/client-policy.adoc @@ -6,7 +6,7 @@ You can use this type of policy to define conditions for your permissions where To create a new client-based policy, select *Client* in the dropdown list in the upper right corner of the policy listing. .Add a Client-Based Policy -image:../../{{book.images}}/policy/create-client.png[alt="Add Client-Based Policy"] +image:{project_images}/policy/create-client.png[alt="Add Client-Based Policy"] ==== Configuration @@ -25,4 +25,4 @@ Specifies which clients are given access by this policy. + * *Logic* + -The <> of this policy to apply after the other conditions have been evaluated. \ No newline at end of file +The <<_policy_logic, Logic>> of this policy to apply after the other conditions have been evaluated. \ No newline at end of file diff --git a/authorization_services/topics/policy/drools-policy.adoc b/authorization_services/topics/policy/drools-policy.adoc index 316abe003a3..f8e49d0b27c 100644 --- a/authorization_services/topics/policy/drools-policy.adoc +++ b/authorization_services/topics/policy/drools-policy.adoc @@ -2,13 +2,13 @@ === Rule-Based Policy With this type of policy you can define conditions for your permissions using http://www.drools.org[Drools], which is a rule evaluation environment. It is one of the _Rule-Based_ policy types -supported by {{book.project.name}}, and provides flexibility to write any policy based on the <>. +supported by {project_name}, and provides flexibility to write any policy based on the <<_policy_evaluation_api, Evaluation API>>. To create a new Rule-based policy, in the dropdown list in the right upper corner of the policy listing, select *Rule*. .Add Rule Policy -image:../../{{book.images}}/policy/create-drools.png[alt="Add Rule Policy"] +image:{project_images}/policy/create-drools.png[alt="Add Rule Policy"] ==== Configuration @@ -51,7 +51,7 @@ Specifies an interval for scanning for artifact updates. + * *Logic* + -The <> of this policy to apply after the other conditions have been evaluated. +The <<_policy_logic, Logic>> of this policy to apply after the other conditions have been evaluated. ==== Examples @@ -89,4 +89,4 @@ rule "Authorize Using Identity Information" end ``` -For more information about what you can access from the `org.keycloak.authorization.policy.evaluation.Evaluation` interface, see <>. +For more information about what you can access from the `org.keycloak.authorization.policy.evaluation.Evaluation` interface, see <<_policy_evaluation_api, Evaluation API>>. diff --git a/authorization_services/topics/policy/evaluation-api.adoc b/authorization_services/topics/policy/evaluation-api.adoc old mode 100755 new mode 100644 index 91e8522a31e..e30c57c588c --- a/authorization_services/topics/policy/evaluation-api.adoc +++ b/authorization_services/topics/policy/evaluation-api.adoc @@ -1,7 +1,7 @@ [[_policy_evaluation_api]] === Policy Evaluation API -When writing rule-based policies using JavaScript or JBoss Drools, {{book.project.name}} provides an Evaluation API that provides useful information to help determine whether a permission should be granted. +When writing rule-based policies using JavaScript or JBoss Drools, {project_name} provides an Evaluation API that provides useful information to help determine whether a permission should be granted. This API consists of a few interfaces that provides you access to information such as: @@ -40,21 +40,21 @@ public interface Evaluation { } ``` -When processing an authorization request, {{book.project.name}} creates an `Evaluation` instance before evaluating any policy. This instance is then passed to each policy to determine whether access is *GRANT* or *DENY*. +When processing an authorization request, {project_name} creates an `Evaluation` instance before evaluating any policy. This instance is then passed to each policy to determine whether access is *GRANT* or *DENY*. Policies determine this by invoking the `grant()` or `deny()` methods on an `Evaluation` instance. By default, the state of the `Evaluation` instance is denied, which means that your policies must explicitly invoke the `grant()` method to indicate to the policy evaluation engine that permission should be granted. -{% if book.community %} +ifeval::[{project_community}==true] For more information about the Evaluation API see the http://www.keycloak.org/docs/javadocs/index.html[JavaDocs]. -{% endif %} +endif::[] -{% if book.product %} +ifeval::[{project_product}==true] For more information about the Evaluation API see the https://access.redhat.com/webassets/avalon/d/red-hat-single-sign-on/version-7.1/javadocs/[JavaDocs]. -{% endif %} +endif::[] ==== The Evaluation Context diff --git a/authorization_services/topics/policy/js-policy.adoc b/authorization_services/topics/policy/js-policy.adoc index 0814819821d..8dca2ae67b6 100644 --- a/authorization_services/topics/policy/js-policy.adoc +++ b/authorization_services/topics/policy/js-policy.adoc @@ -2,12 +2,12 @@ === JavaScript-Based Policy You can use this type of policy to define conditions for your permissions using JavaScript. It is one of the rule-based policy types -supported by {{book.project.name}}, and provides flexibility to write any policy based on the <>. +supported by {project_name}, and provides flexibility to write any policy based on the <<_policy_evaluation_api, Evaluation API>>. To create a new JavaScript-based policy, select *JavaScript* in the dropdown list in the upper right corner of the policy listing. .Add JavaScript Policy -image:../../{{book.images}}/policy/create-js.png[alt="Add JavaScript Policy"] +image:{project_images}/policy/create-js.png[alt="Add JavaScript Policy"] ==== Configuration @@ -26,7 +26,7 @@ The JavaScript code providing the conditions for this policy. + * *Logic* + -The <> of this policy to apply after the other conditions have been evaluated. +The <<_policy_logic, Logic>> of this policy to apply after the other conditions have been evaluated. ==== Examples @@ -66,4 +66,4 @@ if (identity.hasRole('admin') || email.endsWith('@keycloak.org')) { } ``` -When writing your own rules, keep in mind that the *$evaluation* object is an object implementing *org.keycloak.authorization.policy.evaluation.Evaluation*. For more information about what you can access from this interface, see the <>. +When writing your own rules, keep in mind that the *$evaluation* object is an object implementing *org.keycloak.authorization.policy.evaluation.Evaluation*. For more information about what you can access from this interface, see the <<_policy_evaluation_api, Evaluation API>>. diff --git a/authorization_services/topics/policy/overview.adoc b/authorization_services/topics/policy/overview.adoc old mode 100755 new mode 100644 index 1196530b264..8ca03666a1e --- a/authorization_services/topics/policy/overview.adoc +++ b/authorization_services/topics/policy/overview.adoc @@ -6,7 +6,7 @@ As mentioned previously, policies define the conditions that must be satisfied b You can view all policies associated with a resource server by clicking the *Policy* tab when editing a resource server. .Policies -image:../../{{book.images}}/policy/view.png[alt="Policies"] +image:{project_images}/policy/view.png[alt="Policies"] On this tab, you can view the list of previously created policies as well as create and edit a policy. diff --git a/authorization_services/topics/policy/role-policy-required-role.adoc b/authorization_services/topics/policy/role-policy-required-role.adoc index 23bb0513d6c..3ca576a2bfa 100644 --- a/authorization_services/topics/policy/role-policy-required-role.adoc +++ b/authorization_services/topics/policy/role-policy-required-role.adoc @@ -5,7 +5,7 @@ When creating a role-based policy, you can specify a specific role as `Required` only if the user requesting access has been granted *all* the *required* roles. Both realm and client roles can be configured as such. .Example of Required Role -image:../../{{book.images}}/policy/create-role.png[alt="Example of Required Role"] +image:{project_images}/policy/create-role.png[alt="Example of Required Role"] To specify a role as required, select the `Required` checkbox for the role you want to configure as required. diff --git a/authorization_services/topics/policy/role-policy.adoc b/authorization_services/topics/policy/role-policy.adoc index 12cfcb7e5bd..1d7c2ae622d 100644 --- a/authorization_services/topics/policy/role-policy.adoc +++ b/authorization_services/topics/policy/role-policy.adoc @@ -3,14 +3,14 @@ You can use this type of policy to define conditions for your permissions where a set of one or more roles is permitted to access an object. -By default, roles added to this policy are not specified as required and the policy will grant access if the user requesting access has been granted any of these roles. However, you can specify a specific role as <> if you want to enforce a specific role. You can also combine required and non-required roles, regardless of whether they are realm or client roles. +By default, roles added to this policy are not specified as required and the policy will grant access if the user requesting access has been granted any of these roles. However, you can specify a specific role as <<_policy_rbac_required, required>> if you want to enforce a specific role. You can also combine required and non-required roles, regardless of whether they are realm or client roles. -Role policies can be useful when you need more restricted role-based access control (RBAC), where specific roles must be enforced to grant access to an object. For instance, you can enforce that a user must consent to allowing a client application (which is acting on the user's behalf) to access the user's resources. You can use {{book.project.name}} Client Scope Mapping to enable consent pages or even enforce clients to explicitly provide a scope when obtaining access tokens from a {{book.project.name}} server. +Role policies can be useful when you need more restricted role-based access control (RBAC), where specific roles must be enforced to grant access to an object. For instance, you can enforce that a user must consent to allowing a client application (which is acting on the user's behalf) to access the user's resources. You can use {project_name} Client Scope Mapping to enable consent pages or even enforce clients to explicitly provide a scope when obtaining access tokens from a {project_name} server. To create a new role-based policy, select *Role* in the dropdown list in the upper right corner of the policy listing. .Add Role-Based Policy -image:../../{{book.images}}/policy/create-role.png[alt="Add Role-Based Policy"] +image:{project_images}/policy/create-role.png[alt="Add Role-Based Policy"] ==== Configuration @@ -33,4 +33,4 @@ Specifies which *client* roles are permitted by this policy. To enable this fiel + * *Logic* + -The <> of this policy to apply after the other conditions have been evaluated. \ No newline at end of file +The <<_policy_logic, Logic>> of this policy to apply after the other conditions have been evaluated. \ No newline at end of file diff --git a/authorization_services/topics/policy/time-policy.adoc b/authorization_services/topics/policy/time-policy.adoc index 20c9fa6f3e2..32fe39e625f 100644 --- a/authorization_services/topics/policy/time-policy.adoc +++ b/authorization_services/topics/policy/time-policy.adoc @@ -6,7 +6,7 @@ You can use this type of policy to define time conditions for your permissions. To create a new time-based policy, select *Time* in the dropdown list in the upper right corner of the policy listing. .Add Time Policy -image:../../{{book.images}}/policy/create-time.png[alt="Add Time Policy"] +image:{project_images}/policy/create-time.png[alt="Add Time Policy"] ==== Configuration @@ -50,6 +50,6 @@ Defines the minute that access must be granted. You can also specify a range of + * *Logic* + -The <> of this policy to apply after the other conditions have been evaluated. +The <<_policy_logic, Logic>> of this policy to apply after the other conditions have been evaluated. -Access is only granted if all conditions are satisfied. {{book.project.name}} will perform an _AND_ based on the outcome of each condition. \ No newline at end of file +Access is only granted if all conditions are satisfied. {project_name} will perform an _AND_ based on the outcome of each condition. \ No newline at end of file diff --git a/authorization_services/topics/policy/user-policy.adoc b/authorization_services/topics/policy/user-policy.adoc index e2c881c46dc..f0fee5504c3 100644 --- a/authorization_services/topics/policy/user-policy.adoc +++ b/authorization_services/topics/policy/user-policy.adoc @@ -6,7 +6,7 @@ You can use this type of policy to define conditions for your permissions where To create a new user-based policy, select *User* in the dropdown list in the upper right corner of the policy listing. .Add a User-Based Policy -image:../../{{book.images}}/policy/create-user.png[alt="Add User-Based Policy"] +image:{project_images}/policy/create-user.png[alt="Add User-Based Policy"] ==== Configuration @@ -25,4 +25,4 @@ Specifies which users are given access by this policy. + * *Logic* + -The <> of this policy to apply after the other conditions have been evaluated. \ No newline at end of file +The <<_policy_logic, Logic>> of this policy to apply after the other conditions have been evaluated. \ No newline at end of file diff --git a/authorization_services/topics/resource-server/create-client.adoc b/authorization_services/topics/resource-server/create-client.adoc old mode 100755 new mode 100644 index a98ec1e05cb..c7e9fb206f5 --- a/authorization_services/topics/resource-server/create-client.adoc +++ b/authorization_services/topics/resource-server/create-client.adoc @@ -1,19 +1,19 @@ [[_resource_server_create_client]] === Creating a Client Application -The first step to enable {{book.project.name}} {{book.project.module}} is to create the client application that you want to turn into a resource server. +The first step to enable {project_name} Authorization Services is to create the client application that you want to turn into a resource server. To create a client application, complete the following steps: . Click *Clients*. + .Clients -image:../../{{book.images}}/resource-server/client-list.png[alt="Clients"] +image:{project_images}/resource-server/client-list.png[alt="Clients"] . On this page, click *Create*. + .Create Client -image:../../{{book.images}}/resource-server/client-create.png[alt="Create Client"] +image:{project_images}/resource-server/client-create.png[alt="Create Client"] . Type the `Client ID` of the client. For example, _my-resource-server_. . Type the `Root URL` for your application. For example: @@ -25,4 +25,4 @@ http://${host}:${port}/my-resource-server . Click *Save*. The client is created and the client Settings page opens. A page similar to the following is displayed: + .Client Settings -image:../../{{book.images}}/resource-server/client-enable-authz.png[alt="Client Settings"] \ No newline at end of file +image:{project_images}/resource-server/client-enable-authz.png[alt="Client Settings"] \ No newline at end of file diff --git a/authorization_services/topics/resource-server/default-config.adoc b/authorization_services/topics/resource-server/default-config.adoc old mode 100755 new mode 100644 index 2e46622320f..30ebf919806 --- a/authorization_services/topics/resource-server/default-config.adoc +++ b/authorization_services/topics/resource-server/default-config.adoc @@ -1,7 +1,7 @@ [[_resource_server_default_config]] === Default Configuration -When you create a resource server, {{book.project.name}} creates a default configuration for your newly created resource server. +When you create a resource server, {project_name} creates a default configuration for your newly created resource server. The default configuration consists of: @@ -12,22 +12,22 @@ The default configuration consists of: The default protected resource is referred to as the *default resource* and you can view it if you navigate to the *Resources* tab. .Default Resource -image:../../{{book.images}}/resource-server/default-resource.png[alt="Default Resource"] +image:{project_images}/resource-server/default-resource.png[alt="Default Resource"] This resource defines a `Type`, namely `urn:my-resource-server:resources:default` and a `URI` `/*`. Here, the `URI` field defines a -wildcard pattern that indicates to {{book.project.name}} that this resource represents all the paths in your application. In other words, -when enabling <> for your application, all the permissions associated with the resource +wildcard pattern that indicates to {project_name} that this resource represents all the paths in your application. In other words, +when enabling <<_enforcer_overview, policy enforcement>> for your application, all the permissions associated with the resource will be examined before granting access. -The `Type` mentioned previously defines a value that can be used to create <> that must be applied +The `Type` mentioned previously defines a value that can be used to create <<_permission_typed_resource, typed resource permissions>> that must be applied to the default resource or any other resource you create using the same type. The default policy is referred to as the *only from realm policy* and you can view it if you navigate to the *Policies* tab. .Default Policy -image:../../{{book.images}}/resource-server/default-policy.png[alt="Default Policy"] +image:{project_images}/resource-server/default-policy.png[alt="Default Policy"] -This policy is a <> defining a condition that always grants access to the resources protected by this policy. If you click this policy you can see that it defines a rule as follows: +This policy is a <<_policy_js, JavaScript-based policy>> defining a condition that always grants access to the resources protected by this policy. If you click this policy you can see that it defines a rule as follows: ```js // by default, grants any permission associated with this policy @@ -37,13 +37,13 @@ $evaluation.grant(); Lastly, the default permission is referred to as the *default permission* and you can view it if you navigate to the *Permissions* tab. .Default Permission -image:../../{{book.images}}/resource-server/default-permission.png[alt="Default Permission"] +image:{project_images}/resource-server/default-permission.png[alt="Default Permission"] -This permission is a <>, defining a set of one or more policies that are applied to all resources with a given type. +This permission is a <<_permission_create_resource, resource-based permission>>, defining a set of one or more policies that are applied to all resources with a given type. ==== Changing the Default Configuration You can change the default configuration by removing the default resource, policy, or permission definitions and creating your own. [NOTE] -The default configuration defines a resource that maps to all paths in your application. If you are about to write permissions to your own resources, be sure to remove the *Default Resource* or change its ```URI``` field to a more specific path in your application. Otherwise, the policy associated with the default resource (which by default always grants access) will allow {{book.project.name}} to grant access to any protected resource. +The default configuration defines a resource that maps to all paths in your application. If you are about to write permissions to your own resources, be sure to remove the *Default Resource* or change its ```URI``` field to a more specific path in your application. Otherwise, the policy associated with the default resource (which by default always grants access) will allow {project_name} to grant access to any protected resource. diff --git a/authorization_services/topics/resource-server/enable-authorization.adoc b/authorization_services/topics/resource-server/enable-authorization.adoc old mode 100755 new mode 100644 index 9be8f029dd6..128e260fa63 --- a/authorization_services/topics/resource-server/enable-authorization.adoc +++ b/authorization_services/topics/resource-server/enable-authorization.adoc @@ -4,12 +4,12 @@ To turn your OIDC Client Application into a resource server and enable fine-grained authorization, click the *Authorization Enabled* switch to *ON* and click *Save*. .Enabling Authorization Services -image:../../{{book.images}}/resource-server/client-enable-authz.png[alt="Enabling Authorization Services"] +image:{project_images}/resource-server/client-enable-authz.png[alt="Enabling Authorization Services"] A new Authorization tab is displayed for this client. Click the *Authorization* tab and a page similar to the following is displayed: .Resource Server Settings -image:../../{{book.images}}/resource-server/authz-settings.png[alt="Resource Server Settings"] +image:{project_images}/resource-server/authz-settings.png[alt="Resource Server Settings"] The Authorization tab contains additional sub-tabs covering the different steps that you must follow to actually protect your application's resources. Each tab is covered separately by a specific topic in this documentation. But here is a quick description about each one: @@ -19,23 +19,23 @@ General settings for your resource server. For more details about this page see * *Resource* + -From this page, you can manage your application's <>. +From this page, you can manage your application's <<_resource_overview, resources>>. * *Scope* + -From this page, you can manage <>. +From this page, you can manage <<_resource_overview, scopes>>. * *Policies* + -From this page, you can manage <> and define the conditions that must be met to grant a permission. +From this page, you can manage <<_policy_overview, authorization policies>> and define the conditions that must be met to grant a permission. * *Permissions* + -From this page, you can manage the <> for your protected resources and scopes by linking them with the policies you created. +From this page, you can manage the <<_permission_overview, permissions>> for your protected resources and scopes by linking them with the policies you created. * *Evaluate* + -From this page, you can <> and view the result of the evaluation of the permissions and authorization policies you have defined. +From this page, you can <<_policy_evaluation_overview, simulate authorization requests>> and view the result of the evaluation of the permissions and authorization policies you have defined. [[resource_server_settings]] ==== Resource Server Settings diff --git a/authorization_services/topics/resource-server/import-config.adoc b/authorization_services/topics/resource-server/import-config.adoc old mode 100755 new mode 100644 index 78fbed1adad..c3d0d311a7e --- a/authorization_services/topics/resource-server/import-config.adoc +++ b/authorization_services/topics/resource-server/import-config.adoc @@ -14,12 +14,12 @@ To export a configuration file, complete the following steps: . Navigate to the *Resource Server Settings* page. + .Resource Server Settings -image:../../{{book.images}}/resource-server/authz-settings.png[alt="Resource Server Settings"] +image:{project_images}/resource-server/authz-settings.png[alt="Resource Server Settings"] . On this page, in the Export Settings section, click *Export*. + .Export Settings -image:../../{{book.images}}/resource-server/authz-export.png[alt="Export Settings"] +image:{project_images}/resource-server/authz-export.png[alt="Export Settings"] The configuration file is exported in JSON format and displayed in a text area, from which you can copy and paste. You can also click *Download* to download the configuration file and save it. diff --git a/authorization_services/topics/resource-server/overview.adoc b/authorization_services/topics/resource-server/overview.adoc old mode 100755 new mode 100644 index 7c905624173..6ade00d77bb --- a/authorization_services/topics/resource-server/overview.adoc +++ b/authorization_services/topics/resource-server/overview.adoc @@ -3,6 +3,6 @@ According to the OAuth2 specification, a resource server is a server hosting the protected resources and capable of accepting and responding to protected resource requests. -In {{book.project.name}}, resource servers are provided with a rich platform for enabling fine-grained authorization for their protected resources, where authorization decisions can be made based on different access control mechanisms. +In {project_name}, resource servers are provided with a rich platform for enabling fine-grained authorization for their protected resources, where authorization decisions can be made based on different access control mechanisms. Any client application can be configured to support fine-grained permissions. In doing so, you are conceptually turning the client application into a resource server. \ No newline at end of file diff --git a/authorization_services/topics/resource/create.adoc b/authorization_services/topics/resource/create.adoc old mode 100755 new mode 100644 index c7178571fad..705610161f3 --- a/authorization_services/topics/resource/create.adoc +++ b/authorization_services/topics/resource/create.adoc @@ -7,9 +7,9 @@ be created to represent a set of one or more resources and the way you define th To create a new resource, click *Create* in the right upper corner of the resource listing. .Add Resource -image:../../{{book.images}}/resource/create.png[alt="Add Resource"] +image:{project_images}/resource/create.png[alt="Add Resource"] -In {{book.project.name}}, a resource defines a small set of information that is common to different types of resources, such as: +In {project_name}, a resource defines a small set of information that is common to different types of resources, such as: * *Name* + @@ -42,11 +42,11 @@ However, resources can also be associated with users, so you can create permissi ==== Managing Resources Remotely -Resource management is also exposed through the <> to allow resource servers to remotely manage their resources. +Resource management is also exposed through the <<_service_protection_api, Protection API>> to allow resource servers to remotely manage their resources. When using the Protection API, resource servers can be implemented to manage resources owned by their users. In this case, you can specify the user identifier to configure a resource as belonging to a specific user. [NOTE] -{{book.project.name}} provides resource servers complete control over their resources. In the future, we should be able to +{project_name} provides resource servers complete control over their resources. In the future, we should be able to allow users to control their own resources as well as approve authorization requests and manage permissions, especially when using the UMA protocol. \ No newline at end of file diff --git a/authorization_services/topics/resource/overview.adoc b/authorization_services/topics/resource/overview.adoc old mode 100755 new mode 100644 diff --git a/authorization_services/topics/resource/view.adoc b/authorization_services/topics/resource/view.adoc old mode 100755 new mode 100644 index 5306518a214..5b9f8148626 --- a/authorization_services/topics/resource/view.adoc +++ b/authorization_services/topics/resource/view.adoc @@ -4,7 +4,7 @@ On the *Resource* page, you see a list of the resources associated with a resource server. .Resources -image:../../{{book.images}}/resource/view.png[alt="Resources"] +image:{project_images}/resource/view.png[alt="Resources"] The resource list provides information about the protected resources, such as: diff --git a/authorization_services/topics/service/authorization/authorization-api-aapi.adoc b/authorization_services/topics/service/authorization/authorization-api-aapi.adoc old mode 100755 new mode 100644 index 0a75cb5fb14..85cc2cb2fd4 --- a/authorization_services/topics/service/authorization/authorization-api-aapi.adoc +++ b/authorization_services/topics/service/authorization/authorization-api-aapi.adoc @@ -1,7 +1,7 @@ [[_service_authorization_api_aapi]] ==== Requesting Authorization Data and Token -Client applications using the UMA protocol can use a specific endpoint to obtain a special security token called a <>. +Client applications using the UMA protocol can use a specific endpoint to obtain a special security token called a <<_service_rpt_overview, Requesting Party Token (RPT)>>. This token consists of all the permissions granted to a user as a result of the evaluation of the permissions and authorization policies associated with the resources being requested. With an RPT, client applications can gain access to protected resources at the resource server. @@ -12,8 +12,8 @@ http://${host}:${port}/auth/realms/${realm_name}/authz/authorize When requesting an RPT, you need to provide two things: -* A <> representing the resources you want to access -* The <> (as a bearer token) representing a user's identity and his consent to access authorization data on his behalf. +* A <<_service_protection_permission_api_papi, permission ticket>> representing the resources you want to access +* The <<_service_authorization_aat, Authorization API token (AAT)>> (as a bearer token) representing a user's identity and his consent to access authorization data on his behalf. The permission ticket is added to a HTTP request as a parameter whether the AAT is included in a ```Authorization``` header in order to authenticate de request using the AAT as a bearer token. diff --git a/authorization_services/topics/service/authorization/authorization-api.adoc b/authorization_services/topics/service/authorization/authorization-api.adoc old mode 100755 new mode 100644 diff --git a/authorization_services/topics/service/authorization/whatis-obtain-aat.adoc b/authorization_services/topics/service/authorization/whatis-obtain-aat.adoc old mode 100755 new mode 100644 index 2ac2fa018ac..6911fb53d1b --- a/authorization_services/topics/service/authorization/whatis-obtain-aat.adoc +++ b/authorization_services/topics/service/authorization/whatis-obtain-aat.adoc @@ -1,16 +1,16 @@ [[_service_authorization_aat]] ==== What is an AAT and How to Obtain It -An authorization API token (AAT) is a special OAuth2 access token with the scope *uma_authorization*. When you create a user, {{book.project.name}} automatically +An authorization API token (AAT) is a special OAuth2 access token with the scope *uma_authorization*. When you create a user, {project_name} automatically assigns the role _uma_authorization_ to the user. The _uma_authorization_ role is a default realm role. .Default Role uma_authorization -image:../../../{{book.images}}/service/rs-uma-authorization-role.png[alt="Default Role uma_authorization "] +image:{project_images}/service/rs-uma-authorization-role.png[alt="Default Role uma_authorization "] An AAT enables a client application to query the server for user permissions. -Client applications can obtain an AAT from {{book.project.name}} like any other OAuth2 access token. Usually, client applications obtain AATs after the user is successfully -authenticated in {{book.project.name}}. By default, the _authorization_code_ grant type is used to authenticate users, and the server will issue an OAuth2 access token to the client application acting on their behalf. +Client applications can obtain an AAT from {project_name} like any other OAuth2 access token. Usually, client applications obtain AATs after the user is successfully +authenticated in {project_name}. By default, the _authorization_code_ grant type is used to authenticate users, and the server will issue an OAuth2 access token to the client application acting on their behalf. The example below uses the Resource Owner Password Credentials Grant Type to request an AAT: diff --git a/authorization_services/topics/service/client-api.adoc b/authorization_services/topics/service/client-api.adoc old mode 100755 new mode 100644 index 50a4ad248c4..6fbdfdc29bd --- a/authorization_services/topics/service/client-api.adoc +++ b/authorization_services/topics/service/client-api.adoc @@ -2,7 +2,7 @@ === Authorization Client Java API Depending on your requirements, a resource server should be able to manage resources remotely or even check for permissions programmatically. -If you are using Java, you can access the {{book.project.name}} Authorization Services using the Authorization Client API. +If you are using Java, you can access the {project_name} Authorization Services using the Authorization Client API. It is targeted for resource servers that want to access the different APIs provided by the server such as the Protection, Authorization and Entitlement APIs. @@ -39,7 +39,7 @@ The name of the realm. * *auth-server-url* (required) + -The base URL of the {{book.project.name}} server. All other {{book.project.name}} pages and REST service endpoints are derived from this. It is usually in the form https://host:port/auth. +The base URL of the {project_name} server. All other {project_name} pages and REST service endpoints are derived from this. It is usually in the form https://host:port/auth. * *resource* (required) + diff --git a/authorization_services/topics/service/entitlement/entitlement-api-aapi.adoc b/authorization_services/topics/service/entitlement/entitlement-api-aapi.adoc old mode 100755 new mode 100644 index 34ce11fa4b2..c391c26ce87 --- a/authorization_services/topics/service/entitlement/entitlement-api-aapi.adoc +++ b/authorization_services/topics/service/entitlement/entitlement-api-aapi.adoc @@ -1,7 +1,7 @@ [[_service_entitlement_api_aapi]] ==== Requesting Entitlements -Client applications can use a specific endpoint to obtain a special security token called a <>. +Client applications can use a specific endpoint to obtain a special security token called a <<_service_rpt_overview, Requesting Party Token (RPT)>>. This token consists of all the entitlements (or permissions) for a user as a result of the evaluation of the permissions and authorization policies associated with the resources being requested. With an RPT, client applications can gain access to protected resources at the resource server. @@ -10,8 +10,8 @@ With an RPT, client applications can gain access to protected resources at the r http://${host}:${port}/auth/realms/${realm_name}/authz/entitlement/{client_id} ``` -The **client_id** parameter above must be provided in order to identify the client application acting as a <> -in {{book.project.name}}. You must provide the client identifier in order to restrict the scope of the evaluation to the resources, scopes and permissions +The **client_id** parameter above must be provided in order to identify the client application acting as a <<_overview_terminology_resource_server, resource server>> +in {project_name}. You must provide the client identifier in order to restrict the scope of the evaluation to the resources, scopes and permissions managed by a specific resource server. The Entitlement API comes in two flavors: @@ -22,14 +22,14 @@ owned and managed by the resource server itself. * Using HTTP **POST** in order to obtain entitlements based on a a set of one or more resources and scopes sent along with an entitlement request. [NOTE] -Using one or another depends on your use case and how much resources you have registered in {{book.project.name}}. Although the **GET** variant +Using one or another depends on your use case and how much resources you have registered in {project_name}. Although the **GET** variant provides an easy way to obtain entitlements from the server, it might not be appropriate in case you have too much resources associated with an user. In this case, the **POST** method is recommended. Regardless of the HTTP method you decide to use, the Entitlement API endpoint expects an access token in the request representing a user's identity and his consent to access authorization data on his behalf. The access token must be sent as a bearer token using a HTTP ```Authorization``` header. -After successfully invoking the Entitlement API endpoint, you will get a <> with all permissions +After successfully invoking the Entitlement API endpoint, you will get a <<_service_rpt_overview, RPT>> with all permissions granted by the server. ===== Obtaining Entitlements @@ -51,7 +51,7 @@ As a result, the server response is: ``` Using this method to obtain entitlements, the server responds to the requesting client with *all* entitlements for a user, based on the evaluation of the permissions and -authorization policies associated with the resources owned by the user or the resource server itself. For instance, suppose you have permissions defined in {{book.project.name}} for the following resources: +authorization policies associated with the resources owned by the user or the resource server itself. For instance, suppose you have permissions defined in {project_name} for the following resources: * Main Page * Alice Bank Account diff --git a/authorization_services/topics/service/entitlement/entitlement-api.adoc b/authorization_services/topics/service/entitlement/entitlement-api.adoc old mode 100755 new mode 100644 diff --git a/authorization_services/topics/service/entitlement/entitlement-request-metadata.adoc b/authorization_services/topics/service/entitlement/entitlement-request-metadata.adoc old mode 100755 new mode 100644 diff --git a/authorization_services/topics/service/entitlement/whatis-obtain-eat.adoc b/authorization_services/topics/service/entitlement/whatis-obtain-eat.adoc old mode 100755 new mode 100644 index 66a698a832c..ca3c55ad5ec --- a/authorization_services/topics/service/entitlement/whatis-obtain-eat.adoc +++ b/authorization_services/topics/service/entitlement/whatis-obtain-eat.adoc @@ -3,8 +3,8 @@ An entitlement API token (EAT) is a special OAuth2 access token with the scope *kc_entitlement*. -Client applications can obtain an EAT from {{book.project.name}} like any other OAuth2 access token. Usually, client applications obtain EATs after the user is successfully -authenticated in {{book.project.name}}. By default the _authorizaton_code_ grant type is used to authenticate a user and issue an OAuth2 access token to the client application acting on the user's behalf. +Client applications can obtain an EAT from {project_name} like any other OAuth2 access token. Usually, client applications obtain EATs after the user is successfully +authenticated in {project_name}. By default the _authorizaton_code_ grant type is used to authenticate a user and issue an OAuth2 access token to the client application acting on the user's behalf. For demonstration purposes, the example below uses Resource Owner Password Credentials Grant Type to request an EAT: diff --git a/authorization_services/topics/service/overview.adoc b/authorization_services/topics/service/overview.adoc old mode 100755 new mode 100644 index 7de9d288ab0..90284852103 --- a/authorization_services/topics/service/overview.adoc +++ b/authorization_services/topics/service/overview.adoc @@ -1,7 +1,7 @@ [[_service_overview]] == Authorization Services -{{book.project.name}} {{book.project.module}} are based on OAuth2's User-Managed Access (UMA) Profile. +{project_name} Authorization Services are based on OAuth2's User-Managed Access (UMA) Profile. This section describes the different RESTful endpoints that you can interact with to enable fine-grained authorization for your applications and services. \ No newline at end of file diff --git a/authorization_services/topics/service/protection/permission-api-papi.adoc b/authorization_services/topics/service/protection/permission-api-papi.adoc old mode 100755 new mode 100644 index 8d25bb70d5d..ed170c9739b --- a/authorization_services/topics/service/protection/permission-api-papi.adoc +++ b/authorization_services/topics/service/protection/permission-api-papi.adoc @@ -7,23 +7,23 @@ Resource servers using the UMA protocol can use a specific endpoint to manage pe http://${host}:${port}/auth/realms/${realm_name}/authz/protection/permission ``` -A <> is a special security token type representing a permission request. Per the UMA specification, a permission ticket is: +A <<_overview_terminology_permission_ticket, permission ticket>> is a special security token type representing a permission request. Per the UMA specification, a permission ticket is: `A correlation handle that is conveyed from an authorization server to a resource server, from a resource server to a client, and ultimately from a client back to an authorization server, to enable the authorization server to assess the correct policies to apply to a request for authorization data.` [NOTE] _Permission ticket support is limited_. -In the full UMA protocol, resource servers can register permission requests in the server to support authorization flows where a resource owner (the user that owns a resource being requested) can approve access to his resources by third parties, among other ways. This represents one of the main features of the UMA specification: resource owners can control their own resources and the policies that govern them. Currently {{book.project.name}} UMA implementation support is very limited in this regard. For example, the system does not store permission tickets on the server and we are essentially using UMA to provide API security and base our authorization offerings. In the future, full support of UMA and other use cases is planned. +In the full UMA protocol, resource servers can register permission requests in the server to support authorization flows where a resource owner (the user that owns a resource being requested) can approve access to his resources by third parties, among other ways. This represents one of the main features of the UMA specification: resource owners can control their own resources and the policies that govern them. Currently {project_name} UMA implementation support is very limited in this regard. For example, the system does not store permission tickets on the server and we are essentially using UMA to provide API security and base our authorization offerings. In the future, full support of UMA and other use cases is planned. -In most cases, you won't need to deal with this endpoint directly. {{book.project.name}} provides a <> that enables UMA for your +In most cases, you won't need to deal with this endpoint directly. {project_name} provides a <<_enforcer_overview, policy enforcer>> that enables UMA for your resource server so it can obtain a permission ticket from the authorization server, return this ticket to client application, and enforce authorization decisions based on a final requesting party token (RPT). -The process of obtaining permission tickets from {{book.project.name}} is performed by resource servers and not regular client applications, +The process of obtaining permission tickets from {project_name} is performed by resource servers and not regular client applications, where permission tickets are obtained when a client tries to access a protected resource without the necessary grants to access the resource. The issuance of permission tickets is an important aspects when using UMA as it allows resource servers to: * Abstract from clients the data associated with the resources protected by the resource server -* Register in the {{book.project.name}} authorization requests which in turn can be used later in workflows to grant access based on the resource's owner consent +* Register in the {project_name} authorization requests which in turn can be used later in workflows to grant access based on the resource's owner consent * Decouple resource servers from authorization servers and allow them to protect and manage their resources using different authorization servers Client wise, a permission ticket has also important aspects that its worthy to highlight: diff --git a/authorization_services/topics/service/protection/protection-api.adoc b/authorization_services/topics/service/protection/protection-api.adoc old mode 100755 new mode 100644 index 974ab8f5155..16cef4a301b --- a/authorization_services/topics/service/protection/protection-api.adoc +++ b/authorization_services/topics/service/protection/protection-api.adoc @@ -5,7 +5,7 @@ The Protection API provides a UMA-compliant set of endpoints providing: * *Resource Registration* + -With this endpoint, resource servers can manage their resources remotely and enable <> to query the server for the resources that need protection. +With this endpoint, resource servers can manage their resources remotely and enable <<_enforcer_overview, policy enforcers>> to query the server for the resources that need protection. * *Permission Registration* + diff --git a/authorization_services/topics/service/protection/resources-api-papi.adoc b/authorization_services/topics/service/protection/resources-api-papi.adoc old mode 100755 new mode 100644 diff --git a/authorization_services/topics/service/protection/whatis-obtain-pat.adoc b/authorization_services/topics/service/protection/whatis-obtain-pat.adoc old mode 100755 new mode 100644 index 8d1cd67ab16..c2e707b132b --- a/authorization_services/topics/service/protection/whatis-obtain-pat.adoc +++ b/authorization_services/topics/service/protection/whatis-obtain-pat.adoc @@ -1,13 +1,13 @@ [[_service_protection_whatis_obtain_pat]] ==== What is a PAT and How to Obtain It -A *protection API token* (PAT) is a special OAuth2 access token with a scope defined as *uma_protection*. When you create a resource server, {{book.project.name}} automatically +A *protection API token* (PAT) is a special OAuth2 access token with a scope defined as *uma_protection*. When you create a resource server, {project_name} automatically creates a role, _uma_protection_, for the corresponding client application and associates it with the client's service account. .Service Account granted with *uma_protection* role -image:../../../{{book.images}}/service/rs-uma-protection-role.png[alt="Service Account granted with uma_protection role"] +image:{project_images}/service/rs-uma-protection-role.png[alt="Service Account granted with uma_protection role"] -Resource servers can obtain a PAT from {{book.project.name}} like any other OAuth2 access token. For example, using curl: +Resource servers can obtain a PAT from {project_name} like any other OAuth2 access token. For example, using curl: ```bash curl -X POST \ @@ -33,5 +33,5 @@ The example above is using the *client_credentials* grant type to obtain a PAT f ``` [NOTE] -{{book.project.name}} can authenticate your client application in different ways. For simplicity, the *client_credentials* grant type is used here, +{project_name} can authenticate your client application in different ways. For simplicity, the *client_credentials* grant type is used here, which requires a _client_id_ and a _client_secret_. You can choose to use any supported authentication method. \ No newline at end of file diff --git a/authorization_services/topics/service/rpt/overview.adoc b/authorization_services/topics/service/rpt/overview.adoc index c69ad472b47..ddeaec76023 100644 --- a/authorization_services/topics/service/rpt/overview.adoc +++ b/authorization_services/topics/service/rpt/overview.adoc @@ -1,7 +1,7 @@ [[_service_rpt_overview]] ==== Requesting Party Token -A requesting party token (RPT) is a https://tools.ietf.org/html/rfc7519[JSON web token (JWT)] digitally signed using https://www.rfc-editor.org/rfc/rfc7515.txt[JSON web signature (JWS)]. The token is built based on the OAuth2 access token previously issued by {{book.project.name}} to a specific client acting on behalf of an user +A requesting party token (RPT) is a https://tools.ietf.org/html/rfc7519[JSON web token (JWT)] digitally signed using https://www.rfc-editor.org/rfc/rfc7515.txt[JSON web signature (JWS)]. The token is built based on the OAuth2 access token previously issued by {project_name} to a specific client acting on behalf of an user or on its own behalf. When you decode an RPT, you see a payload similar to the following: diff --git a/authorization_services/topics/service/rpt/token-introspection.adoc b/authorization_services/topics/service/rpt/token-introspection.adoc old mode 100755 new mode 100644 index 0d15fc6bbfd..0d83d774083 --- a/authorization_services/topics/service/rpt/token-introspection.adoc +++ b/authorization_services/topics/service/rpt/token-introspection.adoc @@ -6,7 +6,7 @@ Sometimes you might want to introspect a requesting party token (RPT) to check i There are two main use cases where token introspection can help you: * When client applications need to query the token validity to obtain a new one with the same or additional permissions -* When enforcing authorization decisions at the resource server side, especially when none of the built-in <> fits your application +* When enforcing authorization decisions at the resource server side, especially when none of the built-in <<_enforcer_overview, policy enforcers>> fits your application ==== Obtaining Information about an RPT @@ -27,7 +27,7 @@ curl -X POST \ ``` [NOTE] -The request above is using HTTP BASIC and passing the client's credentials (client ID and secret) to authenticate the client attempting to introspect the token, but you can use any other client authentication method supported by {{book.project.name}}. +The request above is using HTTP BASIC and passing the client's credentials (client ID and secret) to authenticate the client attempting to introspect the token, but you can use any other client authentication method supported by {project_name}. The introspection endpoint expects two parameters: @@ -67,13 +67,13 @@ If the RPT is not active, this response is returned instead: ==== Do I Need to Invoke the Server Every Time I Want to Introspect an RPT? -No. Both <> and <> APIs use the +No. Both <<_service_entitlement_api, Entitlement>> APIs use the https://tools.ietf.org/html/rfc7519[JSON web token (JWT)] specification as the default format for RPTs. If you want to validate these tokens without a call to the remote introspection endpoint, you can decode the RPT and query for its validity locally. Once you decode the token, you can also use the permissions within the token to enforce authorization decisions. -This is essentially what the <> do. Be sure to: +This is essentially what the <<_enforcer_overview, policy enforcers>> do. Be sure to: * Validate the signature of the RPT (based on the realm's public key) * Query for token validity based on its _exp_, _iat_, and _aud_ claims \ No newline at end of file diff --git a/build-product.sh b/convert.sh similarity index 68% rename from build-product.sh rename to convert.sh index de65905738a..2f91446f3ee 100755 --- a/build-product.sh +++ b/convert.sh @@ -38,25 +38,7 @@ function buildGuide echo "$TOOL: $GUIDE" echo "" - cd $GUIDE - rm -rf build - rm -rf target - - python ../gitlab-conversion.py - - if [ "$TOOL" = "asciidoctor" ]; then - asciidoctor -dbook -a toc -o target/master.html target/master.adoc - echo "" - echo "Built file://$CURRENT_DIRECTORY/$GUIDE/target/master.html" - fi - - if [ "$TOOL" = "ccutil" ]; then - ccutil compile --lang en_US --format html-single --main-file target/master.adoc - echo "" - echo "Built file://$CURRENT_DIRECTORY/$GUIDE/build/tmp/en-US/html-single/index.html" - fi - - cd .. + cp /home/st/tmp/keycloak-documentation/$GUIDE/pom.xml $GUIDE/ } if [ "$GUIDE" = "" ]; then diff --git a/document-attributes-community.adoc b/document-attributes-community.adoc new file mode 100644 index 00000000000..5196add3162 --- /dev/null +++ b/document-attributes-community.adoc @@ -0,0 +1,52 @@ +:project_name: Keycloak +:project_community: true +:project_product: false +:project_version: 3.3.0.CR1 +:project_versionMvn: 3.3.0.CR1 +:project_versionNpm: 3.3.0-cr.1 +:project_images: keycloak-images +:project_doc_base_url: http://www.keycloak.org/documentation.html +:project_doc_info_version_url: 3.3 + +:quickstartRepo_link: https://github.com/keycloak/keycloak-quickstarts +:quickstartRepo_name: Keycloak Quickstarts Repository +:quickstartRepo_dir: keycloak-quickstarts + +:adapterguide_link: {project_doc_base_url}/{project_doc_info_version_url}/html-single/securing-applications-and-services-guide/ +:adapterguide_name: Securing Applications and Services Guide +:adminguide_link: https://keycloak.gitbooks.io/documentation/content/server_admin/index.html +:adminguide_name: Server Administration +:apidocs_link: {project_doc_base_url}/{project_doc_info_version_url}/html-single/api-documentation/ +:apidocs_name: API Documentation +:developerguide_link: {project_doc_base_url}/{project_doc_info_version_url}/html-single/server-developer-guide/ +:developerguide_name: Server Development +:gettingstarted_link: {project_doc_base_url}/{project_doc_info_version_url}/html/getting-started-guide/ +:gettingstarted_name: Getting Started Tutorial +:installguide_link: {project_doc_base_url}/{project_doc_info_version_url}/html-single/server-installation-and-configuration-guide/ +:installguide_name: Server Installation and Configuration +:installguide_profile_link: {project_doc_base_url}/{project_doc_info_version_url}/html-single/server-installation-and-configuration-guide/#profiles +:installguide_profile_name: Profiles + +:appserver_name: JBoss EAP +:appserver_doc_base_url: https://access.redhat.com/documentation/en/red-hat-jboss-enterprise-application-platform +:appserver_version: {appserver_version} +:appserver_socket_link: {appserver_doc_base_url}/{appserver_version}/html-single/configuration-guide/#network_and_port_configuration +:appserver_socket_name: JBoss EAP Configuration Guide +:appserver_jgroups_link: {appserver_doc_base_url}/{appserver_version}/html-single/configuration-guide/#cluster_communication_jgroups +:appserver_jgroups_name: JBoss EAP Configuration Guide +:appserver_jpa_link: {appserver_doc_base_url}/{appserver_version}/html-single/development-guide/#hibernate +:appserver_jpa_name: JBoss EAP Development Guide +:appserver_network_link: {appserver_doc_base_url}/{appserver_version}/html-single/configuration-guide/#network_and_port_configuration +:appserver_network_name: JBoss EAP Configuration Guide +:appserver_datasource_link: {appserver_doc_base_url}/{appserver_version}/html-single/configuration-guide/#datasource_management +:appserver_datasource_name: JBoss EAP Configuration Guide +:appserver_caching_link: {appserver_doc_base_url}/{appserver_version}/html-single/configuration-guide/#infinispan +:appserver_caching_name: JBoss EAP Configuration Guide +:appserver_admindoc_link: {appserver_doc_base_url}/{appserver_version}/html-single/configuration-guide/configuration-guide +:appserver_admindoc_name: JBoss EAP Configuration Guide +:appserver_loadbalancer_link: {appserver_doc_base_url}/{appserver_version}/html-single/configuration-guide/#configuring_high_availability +:appserver_loadbalancer_name: JBoss EAP Configuration Guide + +:fuseVersion: JBoss Fuse 6.3.0 Rollup 1 + +:subsystem_undertow_xml_urn: urn:jboss:domain:undertow:3.1 diff --git a/document-attributes-product.adoc b/document-attributes-product.adoc new file mode 100644 index 00000000000..4e10480a11a --- /dev/null +++ b/document-attributes-product.adoc @@ -0,0 +1,52 @@ +:project_name: Red Hat Single Sign-On +:project_community: false +:project_product: true +:project_version: 7.2.0.DR4 +:project_versionMvn: 3.3.0.Final-redhat1 +:project_versionNpm: 3.3.0.Final-redhat1 +:project_images: rhsso-images +:project_doc_base_url: https://access.redhat.com/documentation/en/red-hat-single-sign-on/ +:project_doc_info_version_url: 7.2 + +:quickstartRepo_link: https://github.com/keycloak/keycloak-quickstarts +:quickstartRepo_name: Keycloak Quickstarts Repository +:quickstartRepo_dir: keycloak-quickstarts + +:adapterguide_link: {project_doc_base_url}/{project_doc_info_version_url}/html-single/securing-applications-and-services-guide/ +:adapterguide_name: Securing Applications and Services Guide +:adminguide_link: https://keycloak.gitbooks.io/documentation/content/server_admin/index.html +:adminguide_name: Server Administration +:apidocs_link: {project_doc_base_url}/{project_doc_info_version_url}/html-single/api-documentation/ +:apidocs_name: API Documentation +:developerguide_link: {project_doc_base_url}/{project_doc_info_version_url}/html-single/server-developer-guide/ +:developerguide_name: Server Development +:gettingstarted_link: {project_doc_base_url}/{project_doc_info_version_url}/html/getting-started-guide/ +:gettingstarted_name: Getting Started Tutorial +:installguide_link: {project_doc_base_url}/{project_doc_info_version_url}/html-single/server-installation-and-configuration-guide/ +:installguide_name: Server Installation and Configuration +:installguide_profile_link: {project_doc_base_url}/{project_doc_info_version_url}/html-single/server-installation-and-configuration-guide/#profiles +:installguide_profile_name: Profiles + +:appserver_name: JBoss EAP +:appserver_doc_base_url: https://access.redhat.com/documentation/en/red-hat-jboss-enterprise-application-platform +:appserver_version: {appserver_version} +:appserver_socket_link: {appserver_doc_base_url}/{appserver_version}/html-single/configuration-guide/#network_and_port_configuration +:appserver_socket_name: JBoss EAP Configuration Guide +:appserver_jgroups_link: {appserver_doc_base_url}/{appserver_version}/html-single/configuration-guide/#cluster_communication_jgroups +:appserver_jgroups_name: JBoss EAP Configuration Guide +:appserver_jpa_link: {appserver_doc_base_url}/{appserver_version}/html-single/development-guide/#hibernate +:appserver_jpa_name: JBoss EAP Development Guide +:appserver_network_link: {appserver_doc_base_url}/{appserver_version}/html-single/configuration-guide/#network_and_port_configuration +:appserver_network_name: JBoss EAP Configuration Guide +:appserver_datasource_link: {appserver_doc_base_url}/{appserver_version}/html-single/configuration-guide/#datasource_management +:appserver_datasource_name: JBoss EAP Configuration Guide +:appserver_caching_link: {appserver_doc_base_url}/{appserver_version}/html-single/configuration-guide/#infinispan +:appserver_caching_name: JBoss EAP Configuration Guide +:appserver_admindoc_link: {appserver_doc_base_url}/{appserver_version}/html-single/configuration-guide/configuration-guide +:appserver_admindoc_name: JBoss EAP Configuration Guide +:appserver_loadbalancer_link: {appserver_doc_base_url}/{appserver_version}/html-single/configuration-guide/#configuring_high_availability +:appserver_loadbalancer_name: JBoss EAP Configuration Guide + +:fuseVersion: JBoss Fuse 6.3.0 Rollup 1 + +:subsystem_undertow_xml_urn: urn:jboss:domain:undertow:3.1 diff --git a/getting_started/README.adoc b/getting_started/README.adoc deleted file mode 100755 index 107f7a261cd..00000000000 --- a/getting_started/README.adoc +++ /dev/null @@ -1,9 +0,0 @@ - -= Getting Started - -image:images/keycloak_logo.png[alt="Keycloak"] - -{{book.project.name}} {{book.project.version}} - -http://www.keycloak.org - diff --git a/getting_started/SUMMARY.adoc b/getting_started/SUMMARY.adoc deleted file mode 100755 index 49bbb6e23ff..00000000000 --- a/getting_started/SUMMARY.adoc +++ /dev/null @@ -1,24 +0,0 @@ -= Getting Started Guide - - .. link:getting_started/topics/overview.adoc[Overview] - .. link:getting_started/topics/first-boot.adoc[Installing and Booting] -{% if book.community %} - ... link:getting_started/topics/first-boot/distribution-files-community.adoc[Installing the Server] -{% endif %} -{% if book.product %} - ... link:getting_started/topics/first-boot/distribution-files-product.adoc[Installing the Server] -{% endif %} - ... link:getting_started/topics/first-boot/boot.adoc[Booting the Server] - ... link:getting_started/topics/first-boot/initial-user.adoc[Creating the Admin Account] - ... link:getting_started/topics/first-boot/admin-console.adoc[Logging in to the Admin Console] - .. link:getting_started/topics/first-realm.adoc[Creating Your First Realm and User] - ... link:getting_started/topics/first-realm/before.adoc[Before You Start] - ... link:getting_started/topics/first-realm/realm.adoc[Creating a New Realm] - ... link:getting_started/topics/first-realm/user.adoc[Creating a New User] - ... link:getting_started/topics/first-realm/account.adoc[User Account Service] - .. link:getting_started/topics/secure-jboss-app.adoc[Securing a JBoss Servlet Application] - ... link:getting_started/topics/secure-jboss-app/before.adoc[Before You Start] - ... link:getting_started/topics/secure-jboss-app/install-client-adapter.adoc[Installing the Client Adapter] - ... link:getting_started/topics/secure-jboss-app/download-quickstarts.adoc[Downloading, Building, and Deploying Application Code] - ... link:getting_started/topics/secure-jboss-app/create-client.adoc[Creating and Registering the Client] - ... link:getting_started/topics/secure-jboss-app/subsystem.adoc[Configuring the Subsystem] diff --git a/getting_started/book-product.json b/getting_started/book-product.json deleted file mode 100755 index 4853fc75c0b..00000000000 --- a/getting_started/book-product.json +++ /dev/null @@ -1,47 +0,0 @@ -{ - "gitbook": "2.x.x", - "structure": { - "readme": "README.adoc" - }, - "plugins": [ - "toggle-chapters", - "ungrey", - "splitter" - ], - "variables": { - "title": "Getting Started Guide", - "project": { - "name": "Red Hat Single Sign-On", - "version": "7.1.0", - "doc_base_url": "https://access.redhat.com/documentation/en/red-hat-single-sign-on/", - "doc_info_version_url": "7.1" - }, - "community": false, - "product": true, - "images": "rhsso-images", - - "installguide": { - "name": "Server Installation and Configuration Guide", - "link": "https://access.redhat.com/documentation/en/red-hat-single-sign-on/7.1/html-single/server-installation-and-configuration-guide/" - - }, - "adminguide": { - "name": "Server Administration Guide", - "link": "https://access.redhat.com/documentation/en/red-hat-single-sign-on/7.1/html-single/server-administration-guide/" - }, - "clientadapter": "RH-SSO-{{book.project.version}}-eap7-adapter.zip", - "appServer": "JBoss EAP 7", - "appserver": { - "name": "JBoss EAP 7" - }, - "quickstartRepo": { - "name": "Quickstarts for the Red Hat Single Sign-On (SSO) Server", - "dir": "redhat-sso-quickstarts", - "link": "https://github.com/redhat-developer/redhat-sso-quickstarts" - }, - - "subsystem": { - "undertow": "urn:jboss:domain:undertow:3.1" - } - } -} diff --git a/getting_started/buildGuide.sh b/getting_started/buildGuide.sh deleted file mode 100755 index b37f0c97dd0..00000000000 --- a/getting_started/buildGuide.sh +++ /dev/null @@ -1,80 +0,0 @@ -# Build the guide - -# Find the directory name and full path -CURRENT_GUIDE=${PWD##*/} -CURRENT_DIRECTORY=$(pwd) - -usage(){ - cat <&2 - usage - exit 1;; - esac -done - -echo "" -echo "********************************************" -echo " Building $CURRENT_GUIDE " -echo "********************************************" -if [ ! -d target ]; then - echo "You must run 'python gitlab-conversion.py' to convert the content before you run this script." - exit -fi - -# Remove the guide directory path from the master.adoc file as it is not needed -echo "" -echo "***************************************************************************************" -echo "Removing the guide directory path from the master.adoc file as it is not needed." -echo "NOTE: The guide directory path should probably be removed from the SUMMARY.adoc file," -echo "but since we do not know if it will break the upstream build, we are doing this here. " -echo "If it can not be removed from the SUMMARY.adoc file, this should really be done in the " -echo "Python script because otherwise you must run this script before porting content!" -echo "***************************************************************************************" -echo "" -find . -name 'master.adoc' -print | xargs sed -i "s/include::$CURRENT_GUIDE\//include::/g" - -# Remove the html and build directories and then recreate the html/images/ directory -if [ -d target/html ]; then - rm -r target/html/ -fi -if [ -d target/html ]; then - rm -r target/html/ -fi - -mkdir -p html -cp -r target/images/ target/html/ - -echo "Building an asciidoctor version of the guide" -asciidoctor -t -dbook -a toc -o target/html/$CURRENT_GUIDE.html target/master.adoc - -echo "" -echo "Building a ccutil version of the guide" -ccutil compile --lang en_US --format html-single --main-file target/master.adoc - -cd .. - -echo "View the asciidoctor build here: " file://$CURRENT_DIRECTORY/target/html/$CURRENT_GUIDE.html - -if [ -d $CURRENT_DIRECTORY/build/tmp/en-US/html-single/ ]; then - echo "View the ccutil build here: " file://$CURRENT_DIRECTORY/build/tmp/en-US/html-single/index.html - exit 0 -else - echo -e "${RED}Build using ccutil failed!" - echo -e "${BLACK}See the log above for details." - exit 1 -fi diff --git a/getting_started/gitlab-conversion.py b/getting_started/gitlab-conversion.py deleted file mode 100755 index f2e87906cc9..00000000000 --- a/getting_started/gitlab-conversion.py +++ /dev/null @@ -1,113 +0,0 @@ -import sys, os, re, json, shutil, errno - -def transform(root, f, targetdir): - full = os.path.join(root, f) - input = open(full, 'r').read() - dir = os.path.join(targetdir, root) - if not os.path.exists(dir): - os.makedirs(dir) - output = open(os.path.join(dir, f), 'w') - input = applyTransformation(input) - output.write(input) - - -def applyTransformation(input): - for variable in re.findall(r"\{\{(.*?)\}\}", input): - tmp = variable.replace('.', '_') - input = input.replace(variable, tmp) - input = input.replace('{{', '{').replace('}}', '}') - input = re.sub(r"<}==true]\g<2>endif::[]", input) - input = re.sub(r"image:(\.\./)*", "image:", input) - input = re.sub(r"image::(\.\./)*", "image::", input) - return input - - -indir = 'topics' -targetdir = 'target' -if len(sys.argv) > 1: - targetdir = sys.argv[1] - -if os.path.exists(targetdir): - shutil.rmtree(targetdir) - -if os.path.isdir('images'): - shutil.copytree('images',os.path.join(targetdir, 'images')) -if os.path.isdir('keycloak-images'): - shutil.copytree('keycloak-images',os.path.join(targetdir, 'keycloak-images')) -if os.path.isdir('rhsso-images'): - shutil.copytree('rhsso-images',os.path.join(targetdir, 'rhsso-images')) - -shutil.copyfile('metadata.ini', os.path.join(targetdir, 'metadata.ini')); -shutil.copyfile('master-docinfo.xml', os.path.join(targetdir, 'master-docinfo.xml')); - -tmp = os.path.join(targetdir, 'topics') -if not os.path.exists(tmp): - os.makedirs(tmp) - -# transform files -for root, dirs, filenames in os.walk(indir): - for f in filenames: - transform(root,f,targetdir) - -# Create master.doc includes -input = open('SUMMARY.adoc', 'r').read() -output = open(os.path.join(targetdir, 'master.adoc'), 'w') - -output.write(""" -:toc: -:toclevels: 3 -:numbered: - -include::document-attributes.adoc[] -""") - -input = re.sub(r"[ ]*\.+\s*link:[^/]+/(.*)\[(.*)\]", "include::\g<1>[]", input) -input = applyTransformation(input) -output.write(input) - -# parse book-product.json file and create document attributes -with open('book-product.json') as data_file: - data = json.load(data_file) - -variables = data['variables'] - -def makeAttributes(variables, variable, list): - for i in variables.keys(): - if variable is None: - tmp = i - else: - tmp = variable + '_' + i - if isinstance(variables[i],dict): - makeAttributes(variables[i], tmp, list) - elif isinstance(variables[i],bool): - boolval = 'false' - if variables[i]: - boolval = 'true' - list.append({tmp: boolval}) - else: - list.append({tmp: str(variables[i])}) - - -attributeList = [] -makeAttributes(variables, None, attributeList) - -output = open(os.path.join(targetdir, 'document-attributes.adoc'), 'w') -for attribute in attributeList: - for k in attribute.keys(): - output.write(':book_' + k + ": " + attribute[k] + "\n") - -print "Transformation complete!" - - - - - - - - - diff --git a/getting_started/index.adoc b/getting_started/index.adoc new file mode 100644 index 00000000000..7e6c6cf73db --- /dev/null +++ b/getting_started/index.adoc @@ -0,0 +1,6 @@ +:toc: +:toclevels: 3 +:numbered: + +include::../document-attributes-community.adoc[] +include::topics.adoc[] \ No newline at end of file diff --git a/getting_started/master-docinfo.xml b/getting_started/master-docinfo.xml index 1fa06b2773c..2154808846d 100644 --- a/getting_started/master-docinfo.xml +++ b/getting_started/master-docinfo.xml @@ -1,10 +1,10 @@ -{book_project_name} -{book_project_doc_info_version_url} -For Use with {book_project_name} {book_project_doc_info_version_url} -{book_title} -{book_project_doc_info_version_url} +{project_name} +{project_doc_info_version_url} +For Use with {project_name} {project_doc_info_version_url} +{title} +{project_doc_info_version_url} - This guide consists of basic information and instructions to get started with {book_project_name} {book_project_doc_info_version_url} + This guide consists of basic information and instructions to get started with {project_name} {project_doc_info_version_url} Red Hat Customer Content Services diff --git a/getting_started/master.adoc b/getting_started/master.adoc new file mode 100644 index 00000000000..cc0fdffa8d3 --- /dev/null +++ b/getting_started/master.adoc @@ -0,0 +1,6 @@ +:toc: +:toclevels: 3 +:numbered: + +include::../document-attributes-product.adoc[] +include::topics.adoc[] \ No newline at end of file diff --git a/getting_started/pom.xml b/getting_started/pom.xml new file mode 100644 index 00000000000..be34d3b7111 --- /dev/null +++ b/getting_started/pom.xml @@ -0,0 +1,29 @@ + + + 4.0.0 + + + org.keycloak.documentation + documentation-parent + 1.0.0-SNAPSHOT + ../ + + + Getting Started + getting-started + pom + + + + + org.asciidoctor + asciidoctor-maven-plugin + + + asciidoc-to-html + + + + + + diff --git a/getting_started/topics.adoc b/getting_started/topics.adoc new file mode 100644 index 00000000000..a8ce68242c0 --- /dev/null +++ b/getting_started/topics.adoc @@ -0,0 +1,22 @@ +include::topics/overview.adoc[] +include::topics/first-boot.adoc[] +ifeval::[{project_community}==true] +include::topics/first-boot/distribution-files-community.adoc[] +endif::[] +ifeval::[{project_product}==true] +include::topics/first-boot/distribution-files-product.adoc[] +endif::[] +include::topics/first-boot/boot.adoc[] +include::topics/first-boot/initial-user.adoc[] +include::topics/first-boot/admin-console.adoc[] +include::topics/first-realm.adoc[] +include::topics/first-realm/before.adoc[] +include::topics/first-realm/realm.adoc[] +include::topics/first-realm/user.adoc[] +include::topics/first-realm/account.adoc[] +include::topics/secure-jboss-app.adoc[] +include::topics/secure-jboss-app/before.adoc[] +include::topics/secure-jboss-app/install-client-adapter.adoc[] +include::topics/secure-jboss-app/download-quickstarts.adoc[] +include::topics/secure-jboss-app/create-client.adoc[] +include::topics/secure-jboss-app/subsystem.adoc[] diff --git a/getting_started/topics/first-boot.adoc b/getting_started/topics/first-boot.adoc old mode 100755 new mode 100644 index bbc5500ea0d..92431e4a3b0 --- a/getting_started/topics/first-boot.adoc +++ b/getting_started/topics/first-boot.adoc @@ -3,5 +3,5 @@ == Installing and Booting This very short tutorial walks you through booting up the server in standalone mode, setting up the initial admin user, -and logging into the {{book.project.name}} admin console. +and logging into the {project_name} admin console. diff --git a/getting_started/topics/first-boot/admin-console.adoc b/getting_started/topics/first-boot/admin-console.adoc old mode 100755 new mode 100644 index 75101abc931..fd4fb0962a0 --- a/getting_started/topics/first-boot/admin-console.adoc +++ b/getting_started/topics/first-boot/admin-console.adoc @@ -7,12 +7,12 @@ After you create the initial admin account, you can log in to the Admin Console Alternatively you can go to the console URL directly at http://localhost:8080/auth/admin/ + .Login Page -image:../../{{book.images}}/login-page.png[] +image:{project_images}/login-page.png[] -. Type the username and password you created on the Welcome page. The {{book.project.name}} Admin Console page opens. +. Type the username and password you created on the Welcome page. The {project_name} Admin Console page opens. + .Admin Console -image:../../{{book.images}}/admin-console.png[] +image:{project_images}/admin-console.png[] NOTE: If you are curious about a certain feature, button, or field within the Admin Console, hover your mouse over the question mark `?` icon. This will pop up tooltip text to describe the area of the console you are interested in. diff --git a/getting_started/topics/first-boot/boot.adoc b/getting_started/topics/first-boot/boot.adoc old mode 100755 new mode 100644 index 120e2b8864b..9a450777f6e --- a/getting_started/topics/first-boot/boot.adoc +++ b/getting_started/topics/first-boot/boot.adoc @@ -1,10 +1,10 @@ === Booting the Server -To boot the {{book.project.name}} server, go to the _bin/_ directory of the server distribution. +To boot the {project_name} server, go to the _bin/_ directory of the server distribution. .Standalone Boot Scripts -image:../../{{book.images}}/standalone-boot-files.png[] +image:{project_images}/standalone-boot-files.png[] To boot the server: diff --git a/getting_started/topics/first-boot/distribution-files-community.adoc b/getting_started/topics/first-boot/distribution-files-community.adoc old mode 100755 new mode 100644 index c06f213f66e..18f00ba3edc --- a/getting_started/topics/first-boot/distribution-files-community.adoc +++ b/getting_started/topics/first-boot/distribution-files-community.adoc @@ -1,12 +1,12 @@ === Installing Distribution Files -The {{book.project.name}} Server is contained in one distribution file: +The {project_name} Server is contained in one distribution file: -* 'keycloak-{{book.project.version}}.[zip|tar.gz]' +* 'keycloak-{project_version}.[zip|tar.gz]' -The 'keycloak-{{book.project.version}}.[zip|tar.gz]' file is the server only distribution. It contains nothing other than the scripts and binaries -to run the {{book.project.name}} server. +The 'keycloak-{project_version}.[zip|tar.gz]' file is the server only distribution. It contains nothing other than the scripts and binaries +to run the {project_name} server. To unpack these files run the `unzip` or `gunzip` and `tar` utilities. diff --git a/getting_started/topics/first-boot/distribution-files-product.adoc b/getting_started/topics/first-boot/distribution-files-product.adoc old mode 100755 new mode 100644 index 5665ce34ccb..bcae8bb9999 --- a/getting_started/topics/first-boot/distribution-files-product.adoc +++ b/getting_started/topics/first-boot/distribution-files-product.adoc @@ -1,12 +1,12 @@ === Installing the Server -The {{book.project.name}} Server is contained in one distribution file: +The {project_name} Server is contained in one distribution file: -* 'RH-SSO-{{book.project.version}}.[zip|tar.gz]' +* 'RH-SSO-{project_version}.[zip|tar.gz]' -The 'RH-SSO-{{book.project.version}}.[zip|tar.gz]' file is the server-only distribution. It contains only the scripts and binaries -to run the {{book.project.name}} server. +The 'RH-SSO-{project_version}.[zip|tar.gz]' file is the server-only distribution. It contains only the scripts and binaries +to run the {project_name} server. To unpack these files run the `unzip` or `gunzip` and `tar` utilities. diff --git a/getting_started/topics/first-boot/initial-user.adoc b/getting_started/topics/first-boot/initial-user.adoc old mode 100755 new mode 100644 index 771675a29fe..42f7b1168fc --- a/getting_started/topics/first-boot/initial-user.adoc +++ b/getting_started/topics/first-boot/initial-user.adoc @@ -4,14 +4,14 @@ After the server boots, open your browser and go to the http://localhost:8080/auth URL. The page should look like this: .Welcome Page -image:../../{{book.images}}/initial-welcome-page.png[] +image:{project_images}/initial-welcome-page.png[] -{{book.project.name}} does not have a configured admin account by default. You must create one on the Welcome page. +{project_name} does not have a configured admin account by default. You must create one on the Welcome page. This account will allow you to create an admin that can log into the _master_ realm's administration console so that -you can start creating realms and users and registering applications to be secured by {{book.project.name}}. +you can start creating realms and users and registering applications to be secured by {project_name}. NOTE: You can only create an initial admin user on the Welcome Page if you connect using `localhost`. This is a security precaution. You can also create the initial admin user at the command line with the `add-user-keycloak.sh` script. For more details see - link:{{book.installguide.link}}[{{book.installguide.name}}] and link:{{book.adminguide.link}}[{{book.adminguide.name}}]. + link:{installguide_link}[{installguide_name}] and link:{adminguide_link}[{adminguide_name}]. diff --git a/getting_started/topics/first-realm.adoc b/getting_started/topics/first-realm.adoc old mode 100755 new mode 100644 index 3bca2724593..5d36df5de2c --- a/getting_started/topics/first-realm.adoc +++ b/getting_started/topics/first-realm.adoc @@ -1,6 +1,6 @@ == Creating a Realm and User -This short tutorial walks you through creating a new realm within the {{book.project.name}} Admin Console and adding +This short tutorial walks you through creating a new realm within the {project_name} Admin Console and adding a new user to that realm. With that new user you will log into your new realm and visit the built-in User Account service that all users have access to. \ No newline at end of file diff --git a/getting_started/topics/first-realm/account.adoc b/getting_started/topics/first-realm/account.adoc old mode 100755 new mode 100644 index ff127e0118a..8cb13b88a04 --- a/getting_started/topics/first-realm/account.adoc +++ b/getting_started/topics/first-realm/account.adoc @@ -11,10 +11,10 @@ User Account Link:: . Type the username and password you created previously. You must create a permanent password after you successfully log in if you didn't toggle the Temporary switch to *Off* previously. + .Update Password -image:../../{{book.images}}/update-password.png[] +image:{project_images}/update-password.png[] The User Account Service page opens. Every user in a realm has access to this Account Service by default. -You can update profile information and change or add additional credentials. For more information on this service see the link:{{book.adminguide.link}}[{{book.adminguide.name}}]. +You can update profile information and change or add additional credentials. For more information on this service see the link:{adminguide_link}[{adminguide_name}]. diff --git a/getting_started/topics/first-realm/before.adoc b/getting_started/topics/first-realm/before.adoc old mode 100755 new mode 100644 index dca93426a5b..4266ca1d23c --- a/getting_started/topics/first-realm/before.adoc +++ b/getting_started/topics/first-realm/before.adoc @@ -1,6 +1,6 @@ === Before You Start -Before you can participate in this tutorial, you need to complete the installation of {{book.project.name}} and create the -initial admin user as shown in the <> tutorial. +Before you can participate in this tutorial, you need to complete the installation of {project_name} and create the +initial admin user as shown in the <<_install-boot, Installing and Booting>> tutorial. diff --git a/getting_started/topics/first-realm/realm.adoc b/getting_started/topics/first-realm/realm.adoc old mode 100755 new mode 100644 index a7e7640ce4d..23404689408 --- a/getting_started/topics/first-realm/realm.adoc +++ b/getting_started/topics/first-realm/realm.adoc @@ -4,8 +4,8 @@ To create a new realm, complete the following steps: -. Log in to the {{book.project.name}} Admin Console using the account you created in the -<> tutorial. +. Log in to the {project_name} Admin Console using the account you created in the +<<_install-boot, Install and Boot>> tutorial. Admin Console Link:: http://localhost:8080/auth/admin/ @@ -13,13 +13,13 @@ Admin Console Link:: . In the top left corner dropdown menu that is titled `Master`, click *Add Realm*. If you are logged in to the master realm this dropdown menu lists all the realms created. The Add Realm page opens. + .Add Realm Menu -image:../../{{book.images}}/add-realm-menu.png[] +image:{project_images}/add-realm-menu.png[] . You will be creating a brand new realm from scratch so type `demo` for the realm name and click `Create`. + .Create Realm -image:../../{{book.images}}/create-realm.png[] +image:{project_images}/create-realm.png[] After creating the realm the main Admin Console page opens. The current realm is now set to `demo`. You can switch between managing the `master` realm and the realm you just created by clicking the top left corner dropdown menu. diff --git a/getting_started/topics/first-realm/user.adoc b/getting_started/topics/first-realm/user.adoc old mode 100755 new mode 100644 index 81196177297..de2a72bc486 --- a/getting_started/topics/first-realm/user.adoc +++ b/getting_started/topics/first-realm/user.adoc @@ -7,20 +7,20 @@ To create a new user in the `demo` realm as well as a temporary password for tha . In the left menu bar click *Users*. The user list page opens. + .Users -image:../../{{book.images}}/users.png[] +image:{project_images}/users.png[] . On the right side of the empty user list, click *Add User*. + .Add User -image:../../{{book.images}}/add-user.png[] +image:{project_images}/add-user.png[] . The only required field is `Username`. When you are finished, click *Save*. The management page for your new user opens. . The next step is to define a temporary password for your new user. Click the *Credentials* tab. + .Set Temporary Password -image:../../{{book.images}}/credentials.png[] +image:{project_images}/credentials.png[] . Type a new password and confirm it. A red *Reset Password* button is displayed. . Click *Reset Password* to reset the user password to the new one you specified. diff --git a/getting_started/topics/overview.adoc b/getting_started/topics/overview.adoc old mode 100755 new mode 100644 index 1b5038ce2a6..47c9f8316d3 --- a/getting_started/topics/overview.adoc +++ b/getting_started/topics/overview.adoc @@ -2,6 +2,6 @@ == Overview The purpose of this guide is to get you up and running as quickly as possible so that you can -play with and test-drive various features that {{book.project.name}} has. It relies heavily on the default database +play with and test-drive various features that {project_name} has. It relies heavily on the default database and server configuration and does not cover any complex deployment options. If you want a more in-depth discussion of any features or configuration options, consult the various reference guides available. \ No newline at end of file diff --git a/getting_started/topics/secure-jboss-app.adoc b/getting_started/topics/secure-jboss-app.adoc index ba07252c101..1b42ce98e20 100644 --- a/getting_started/topics/secure-jboss-app.adoc +++ b/getting_started/topics/secure-jboss-app.adoc @@ -1,7 +1,7 @@ == Securing a JBoss Servlet Application -In this section you will learn how to secure a Java Servlet application on the {{book.appserver.name}} application server. You will learn how to install the -{{book.project.name}} Client Adapter onto a {{book.appserver.name}} application server distribution. You will create and register a client application in the -{{book.project.name}} Admin Console. Finally, you will configure the application to be secured by {{book.project.name}}. +In this section you will learn how to secure a Java Servlet application on the {appserver_name} application server. You will learn how to install the +{project_name} Client Adapter onto a {appserver_name} application server distribution. You will create and register a client application in the +{project_name} Admin Console. Finally, you will configure the application to be secured by {project_name}. diff --git a/getting_started/topics/secure-jboss-app/before.adoc b/getting_started/topics/secure-jboss-app/before.adoc old mode 100755 new mode 100644 index 2d204182dd7..2c28ba31ca2 --- a/getting_started/topics/secure-jboss-app/before.adoc +++ b/getting_started/topics/secure-jboss-app/before.adoc @@ -1,15 +1,15 @@ === Before You Start -Before you can participate in this tutorial, you need to complete the installation of {{book.project.name}} and create the -initial admin user as shown in the <> tutorial. There is one -caveat to this. You have to run a separate {{book.appserver.name}} instance on the same machine as the -{{book.project.name}} server. This separate instance will run your Java Servlet application. Because of this you will -have to run the {{book.project.name}} under a different port so that there are no port conflicts when running on the +Before you can participate in this tutorial, you need to complete the installation of {project_name} and create the +initial admin user as shown in the <<_install-boot, Installing and Booting>> tutorial. There is one +caveat to this. You have to run a separate {appserver_name} instance on the same machine as the +{project_name} server. This separate instance will run your Java Servlet application. Because of this you will +have to run the {project_name} under a different port so that there are no port conflicts when running on the same machine. Use the `jboss.socket.binding.port-offset` system property on the command line. The value of this property -is a number that will be added to the base value of every port opened by the {{book.project.name}} server. +is a number that will be added to the base value of every port opened by the {project_name} server. -To boot the {{book.project.name}} server: +To boot the {project_name} server: .Linux/Unix [source] @@ -23,6 +23,6 @@ $ .../bin/standalone.sh -Djboss.socket.binding.port-offset=100 > ...\bin\standalone.bat -Djboss.socket.binding.port-offset=100 ---- -After booting up {{book.project.name}}, you can then access the admin console at http://localhost:8180/auth/admin/ +After booting up {project_name}, you can then access the admin console at http://localhost:8180/auth/admin/ diff --git a/getting_started/topics/secure-jboss-app/create-client.adoc b/getting_started/topics/secure-jboss-app/create-client.adoc index 0bbd96d42cc..0ca17a3a704 100644 --- a/getting_started/topics/secure-jboss-app/create-client.adoc +++ b/getting_started/topics/secure-jboss-app/create-client.adoc @@ -1,7 +1,7 @@ === Creating and Registering the Client -The next step you have to do is to define and register the client in the {{book.project.name}} Admin Console. +The next step you have to do is to define and register the client in the {project_name} Admin Console. . Log into the Admin Console with your admin account as you did in previous tutorials. @@ -10,26 +10,26 @@ the Admin Console with your admin account as you did in previous tutorials. the `demo` realm. Click `Clients` in the left side menu. The Clients page opens. + .Clients -image:../../{{book.images}}/clients.png[] +image:{project_images}/clients.png[] . On the right click *Create*. . Complete the fields as shown below: + .Add Client -image:../../{{book.images}}/add-client.png[] +image:{project_images}/add-client.png[] -. After clicking the `Save` button your client application entry will be created. You now have to go back to the {{book.appserver.name}} -instance that the application is deployed on and configure it so that this app is secured by {{book.project.name}}. You can obtain -a template for the configuration you need by going to the `Installation` tab in the client entry in the {{book.project.name}} Admin Console. +. After clicking the `Save` button your client application entry will be created. You now have to go back to the {appserver_name} +instance that the application is deployed on and configure it so that this app is secured by {project_name}. You can obtain +a template for the configuration you need by going to the `Installation` tab in the client entry in the {project_name} Admin Console. + .Installation Tab -image:../../{{book.images}}/client-installation.png[] +image:{project_images}/client-installation.png[] . Select *Keycloak OIDC JBoss Subsystem XML*. An XML template is generated that you'll need to cut and paste. + .Template XML -image:../../{{book.images}}/client-install-selected.png[] +image:{project_images}/client-install-selected.png[] diff --git a/getting_started/topics/secure-jboss-app/download-quickstarts.adoc b/getting_started/topics/secure-jboss-app/download-quickstarts.adoc index ee3967fc84b..6cedf0a9dae 100644 --- a/getting_started/topics/secure-jboss-app/download-quickstarts.adoc +++ b/getting_started/topics/secure-jboss-app/download-quickstarts.adoc @@ -1,21 +1,21 @@ === Downloading, Building, and Deploying Application Code -The project and code for the application you are going to secure is available in link:{{book.quickstartRepo.link}}[{{book.quickstartRepo.name}}]. You will need the following +The project and code for the application you are going to secure is available in link:{quickstartRepo_link}[{quickstartRepo_name}]. You will need the following installed on your machine and available in your PATH before you can continue: * Java JDK 8 * Apache Maven 3.1.1 or higher * Git -You can obtain the code by cloning the repository at {{book.quickstartRepo.link}}. Use the branch matching the version of Red Hat Single Sign-On in use. Follow these steps to download the code, build it, -and deploy it. Make sure your {{book.appserver.name}} application server is started before you run these steps. +You can obtain the code by cloning the repository at {quickstartRepo_link}. Use the branch matching the version of Red Hat Single Sign-On in use. Follow these steps to download the code, build it, +and deploy it. Make sure your {appserver_name} application server is started before you run these steps. .Clone Project [source, subs="attributes"] ---- -$ git clone {{book.quickstartRepo.link}} -$ cd {{book.quickstartRepo.dir}}/app-profile-jee-vanilla +$ git clone {quickstartRepo_link} +$ cd {quickstartRepo_dir}/app-profile-jee-vanilla $ mvn clean wildfly:deploy ---- @@ -24,7 +24,7 @@ You should see some text scroll down in the application server console window. http://localhost:8080/vanilla .Application Login Page -image:../../{{book.images}}/app-login-page.png[] +image:{project_images}/app-login-page.png[] If you open up the application's _web.xml_ file you would see that the application is secured via `BASIC` authentication. If you click on the login button on the login page, the browser @@ -32,7 +32,7 @@ will pop up a BASIC auth login dialog. .Application Login Dialog -image:../../{{book.images}}/client-auth-required.png[] +image:{project_images}/client-auth-required.png[] The application is not secured by any identity provider, so anything you enter in the dialog box will result in a `Forbidden` message being diff --git a/getting_started/topics/secure-jboss-app/install-client-adapter.adoc b/getting_started/topics/secure-jboss-app/install-client-adapter.adoc index ca0a4f7726f..9e4d5643f03 100644 --- a/getting_started/topics/secure-jboss-app/install-client-adapter.adoc +++ b/getting_started/topics/secure-jboss-app/install-client-adapter.adoc @@ -1,18 +1,18 @@ === Installing the Client Adapter -Download the {{book.appserver.name}} distribution and unzip +Download the {appserver_name} distribution and unzip it into a directory on your machine. -{% if book.community %} +ifeval::[{project_community}==true] Next download the WildFly OpenID Connect adapter distribution from link:http://www.keycloak.org/downloads.html[keycloak.org]. -{% endif %} +endif::[] -{% if book.product %} -Next download the RH-SSO-{{book.project.version}}-eap7-adapter.zip distribution. -{% endif %} +ifeval::[{project_product}==true] +Next download the RH-SSO-{project_version}-eap7-adapter.zip distribution. +endif::[] -Unzip this file into the root directory of your {{book.appserver.name}} distribution. +Unzip this file into the root directory of your {appserver_name} distribution. Next perform the following actions: @@ -30,7 +30,7 @@ $ ./jboss-cli.sh --file=adapter-install-offline.cli > jboss-cli.bat --file=adapter-install-offline.cli ---- -{% if book.community %} +ifeval::[{project_community}==true] .Wildfly 11 and Linux/Unix [source] ---- @@ -44,7 +44,7 @@ $ ./jboss-cli.sh --file=adapter-elytron-install-offline.cli > cd bin > jboss-cli.bat --file=adapter-elytron-install-offline.cli ---- -{% endif %} +endif::[] This script will make the appropriate edits to the _.../standalone/configuration/standalone.xml_ file of your app server distribution. Finally, boot the application server. diff --git a/getting_started/topics/secure-jboss-app/subsystem.adoc b/getting_started/topics/secure-jboss-app/subsystem.adoc index 367915e345e..cb7611cd4eb 100644 --- a/getting_started/topics/secure-jboss-app/subsystem.adoc +++ b/getting_started/topics/secure-jboss-app/subsystem.adoc @@ -46,6 +46,6 @@ that resides in the _standalone/configuration_ directory of the application serv . Reboot your application server. -. Go to http://localhost:8080/vanilla and click *login*. The {{book.project.name}} login page opens. You can log in using the user you created in the <> chapter. +. Go to http://localhost:8080/vanilla and click *login*. The {project_name} login page opens. You can log in using the user you created in the <<_create-new-user, Creating a New User>> chapter. diff --git a/gitlab-conversion.py b/gitlab-conversion.py deleted file mode 100755 index 180a47a3c80..00000000000 --- a/gitlab-conversion.py +++ /dev/null @@ -1,111 +0,0 @@ -import sys, os, re, json, shutil, errno - -def transform(root, f, targetdir): - full = os.path.join(root, f) - input = open(full, 'r').read() - dir = os.path.join(targetdir, root) - if not os.path.exists(dir): - os.makedirs(dir) - output = open(os.path.join(dir, f), 'w') - input = applyTransformation(input) - output.write(input) - - -def applyTransformation(input): - for variable in re.findall(r"\{\{(.*?)\}\}", input): - tmp = variable.replace('.', '_') - input = input.replace(variable, tmp) - input = input.replace('{{', '{').replace('}}', '}') - input = re.sub(r"<}==true]\g<2>endif::[]", input) - input = re.sub(r"image:(\.\./)*", "image:", input) - input = re.sub(r"image::(\.\./)*", "image::", input) - return input - - -indir = 'topics' -targetdir = 'target' -if len(sys.argv) > 1: - targetdir = sys.argv[1] - -if os.path.exists(targetdir): - shutil.rmtree(targetdir) - -if os.path.isdir('images'): - shutil.copytree('images',os.path.join(targetdir, 'images')) -if os.path.isdir('keycloak-images'): - shutil.copytree('keycloak-images',os.path.join(targetdir, 'keycloak-images')) -if os.path.isdir('rhsso-images'): - shutil.copytree('rhsso-images',os.path.join(targetdir, 'rhsso-images')) - -shutil.copyfile('metadata.ini', os.path.join(targetdir, 'metadata.ini')); -shutil.copyfile('master-docinfo.xml', os.path.join(targetdir, 'master-docinfo.xml')); - -tmp = os.path.join(targetdir, 'topics') -if not os.path.exists(tmp): - os.makedirs(tmp) - -# transform files -for root, dirs, filenames in os.walk(indir): - for f in filenames: - transform(root,f,targetdir) - -# Create master.doc includes -input = open('SUMMARY.adoc', 'r').read() -output = open(os.path.join(targetdir, 'master.adoc'), 'w') - -output.write(""" -:toc: -:toclevels: 3 -:numbered: - -include::document-attributes.adoc[] -""") - -input = re.sub(r"[ ]*\.+\s*link:[^/]+/(.*)\[(.*)\]", "include::\g<1>[]", input) -input = applyTransformation(input) -output.write(input) - -# parse book-product.json file and create document attributes -with open('../book-product.json') as data_file: - data = json.load(data_file) - -variables = data['variables'] - -def makeAttributes(variables, variable, list): - for i in variables.keys(): - if variable is None: - tmp = i - else: - tmp = variable + '_' + i - if isinstance(variables[i],dict): - makeAttributes(variables[i], tmp, list) - elif isinstance(variables[i],bool): - boolval = 'false' - if variables[i]: - boolval = 'true' - list.append({tmp: boolval}) - else: - list.append({tmp: str(variables[i])}) - - -attributeList = [] -makeAttributes(variables, None, attributeList) - -output = open(os.path.join(targetdir, 'document-attributes.adoc'), 'w') -for attribute in attributeList: - for k in attribute.keys(): - output.write(':book_' + k + ": " + attribute[k] + "\n") - - - - - - - - - diff --git a/pom.xml b/pom.xml new file mode 100644 index 00000000000..1151ca62936 --- /dev/null +++ b/pom.xml @@ -0,0 +1,135 @@ + + + 4.0.0 + + Keycloak Documentation Parent + org.keycloak.documentation + documentation-parent + 1.0.0-SNAPSHOT + pom + + + index + + UTF-8 + 1.5.5 + 3.0.0 + 3.0.2 + 3.0.1 + 1.8 + + + + authorization_services + getting_started + securing_apps + server_admin + server_development + server_installation + aggregation + + + + + product + + + product + + + + master + + + + + + + + + org.apache.maven.plugins + maven-antrun-plugin + ${version.plugin.antrun} + + + org.apache.maven.plugins + maven-dependency-plugin + ${version.plugin.dependency} + + + org.asciidoctor + asciidoctor-maven-plugin + ${version.plugin.asciidoctor} + + + asciidoc-to-html + generate-resources + + process-asciidoc + + + ${basedir} + ${masterFile}.adoc + html5 + coderay + + + ./ + left + left + font + true + + - + true + + + + + + + + org.apache.maven.plugins + maven-resources-plugin + ${version.plugin.resources} + + + asciidoc-copy-resources + process-resources + + copy-resources + + + + + target/generated-docs + + + + + + + org.apache.maven.plugins + maven-assembly-plugin + ${version.plugin.assembly} + + + asciidoc-html-zip + package + + single + + + false + true + + ../assembly.xml + + + + + + + + + diff --git a/scripts/buildGuides.sh b/scripts/buildGuides.sh deleted file mode 100755 index 6ffe832bbc3..00000000000 --- a/scripts/buildGuides.sh +++ /dev/null @@ -1,119 +0,0 @@ -# Establish global variables to the docs and script dirs -CURRENT_DIR="$( pwd -P)" -SCRIPT_SRC="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd -P )" -DOCS_SRC="$( dirname $SCRIPT_SRC )" -BUILD_RESULTS="Build Results:" -BUILD_MESSAGE=$BUILD_RESULTS -BLACK='\033[0;30m' -RED='\033[0;31m' -NO_COLOR="\033[0m" - -usage(){ - cat < - -DESCRIPTION: Build all of the guides (default) or a single guide. - -Run this script from either the root of your cloned repo or from the 'scripts' -directory. Example: - cd eap-documentation/scripts - $0 - -OPTIONS: - -h Print help. - -EXAMPLES: - Build all guides: - $0 - - Build a specific guide(s) from $DOCS_SRC: - $0 authorization_services - $0 securing_apps - $0 authorization_services securing_apps - -EOM -# Now list the valid book values -listvalidbooks -} - -listvalidbooks(){ - echo "" - echo " Valid book argument values are:" - cd $DOCS_SRC - subdirs=`find . -maxdepth 1 -type d ! -iname ".*" ! -iname "topics" ! -iname "images" ! -iname "scripts" | sort` - for subdir in $subdirs - do - echo " ${subdir##*/}" - done - echo "" - # Return to where we started as a courtesy. - cd $CURRENT_DIR -} - -OPTIND=1 -while getopts "h" c - do - case "$c" in - h) usage - exit 1;; - \?) echo "Unknown option: -$OPTARG." >&2 - usage - exit 1;; - esac - done -shift $(($OPTIND - 1)) - -# Use $DOCS_SRC so we don't have to worry about relative paths. -cd $DOCS_SRC - -# Set the list of docs to build to whatever the user passed in (if anyting) -subdirs=$@ -if [ $# -gt 0 ]; then - echo "=== Bulding $@ ===" -else - echo "=== Building all the guides ===" - # Recurse through the guide directories and build them. - subdirs=`find . -maxdepth 1 -type d ! -iname ".*" ! -iname "topics" ! -iname "images" ! -iname "scripts" | sort` -fi -echo $PWD -for subdir in $subdirs -do - echo "Building $DOCS_SRC/${subdir##*/}" - # Navigate to the dirctory and build it - if ! [ -e $DOCS_SRC/${subdir##*/} ]; then - BUILD_MESSAGE="$BUILD_MESSAGE\nERROR: $DOCS_SRC/${subdir##*/} does not exist." - # This is a book argument error so we should list the valid arguments. - LIST_BOOKS="true" - continue - fi - cd $DOCS_SRC/${subdir##*/} - GUIDE_NAME=${PWD##*/} - python gitlab-conversion.py - ./buildGuide.sh - - if [ "$?" = "1" ]; then - BUILD_ERROR="ERROR: Build of $GUIDE_NAME failed. See the log above for details." - BUILD_MESSAGE="$BUILD_MESSAGE\n$BUILD_ERROR" - fi - - # Return to the parent directory - cd $SCRIPT_SRC -done - -# Return to where we started as a courtesy. -cd $CURRENT_DIR - -# Report any errors -echo "" -if [ "$BUILD_MESSAGE" == "$BUILD_RESULTS" ]; then - echo "Build was successful!" -else - echo -e "${RED}$BUILD_MESSAGE${NO_COLOR}" - if [ "$LIST_BOOKS" ]; then - listvalidbooks - else - # This is a build error. - echo -e "${RED}Please fix all issues before requesting a merge!${NO_COLOR}" - fi -fi -exit; diff --git a/securing_apps/README.adoc b/securing_apps/README.adoc deleted file mode 100755 index 71130c269ff..00000000000 --- a/securing_apps/README.adoc +++ /dev/null @@ -1,9 +0,0 @@ - -= Securing Applications and Services - -image:images/keycloak_logo.png[alt="Keycloak"] - -{{book.project.name}} {{book.project.version}} - -http://www.keycloak.org - diff --git a/securing_apps/SUMMARY.adoc b/securing_apps/SUMMARY.adoc deleted file mode 100644 index 20070156e18..00000000000 --- a/securing_apps/SUMMARY.adoc +++ /dev/null @@ -1,92 +0,0 @@ -= Securing Applications and Services Guide - - .. link:securing_apps/topics/overview/overview.adoc[Overview] - ... link:securing_apps/topics/overview/what-are-client-adapters.adoc[What are Client Adapters?] - ... link:securing_apps/topics/overview/supported-platforms.adoc[Supported Platforms] - ... link:securing_apps/topics/overview/supported-protocols.adoc[Supported Protocols] - - .. link:securing_apps/topics/oidc/oidc-overview.adoc[OpenID Connect] - - ... link:securing_apps/topics/oidc/java/java-adapters.adoc[Java Adapters] - .... link:securing_apps/topics/oidc/java/java-adapter-config.adoc[Java Adapters Config] - .... link:securing_apps/topics/oidc/java/jboss-adapter.adoc[JBoss EAP/Wildfly Adapter] - .... link:securing_apps/topics/oidc/java/fuse-adapter.adoc[JBoss Fuse Adapter] - ..... link:securing_apps/topics/oidc/java/fuse/install-feature.adoc[Install Feature] - ..... link:securing_apps/topics/oidc/java/fuse/classic-war.adoc[Classic WAR application] - ..... link:securing_apps/topics/oidc/java/fuse/servlet-whiteboard.adoc[Servlet Deployed as OSGI Service] - ..... link:securing_apps/topics/oidc/java/fuse/camel.adoc[Apache Camel] - ..... link:securing_apps/topics/oidc/java/fuse/cxf-separate.adoc[Apache CXF on Separate Jetty] - ..... link:securing_apps/topics/oidc/java/fuse/cxf-builtin.adoc[Apache CXF on default Jetty] - ..... link:securing_apps/topics/oidc/java/fuse/fuse-admin.adoc[Fuse Admin Services] - ..... link:securing_apps/topics/oidc/java/fuse/hawtio.adoc[Hawtio Admin Console] - {% if book.community %} - .... link:securing_apps/topics/oidc/java/tomcat-adapter.adoc[Tomcat 6, 7 and 8 Adapters] - .... link:securing_apps/topics/oidc/java/jetty9-adapter.adoc[Jetty 9.x Adapters] - .... link:securing_apps/topics/oidc/java/jetty8-adapter.adoc[Jetty 8.1.x Adapter] - .... link:securing_apps/topics/oidc/java/spring-boot-adapter.adoc[Spring Boot Adapter] - .... link:securing_apps/topics/oidc/java/spring-security-adapter.adoc[Spring Security Adapter] - {% endif %} - {% if book.community %} - .... link:securing_apps/topics/oidc/java/servlet-filter-adapter.adoc[Java Servlet Filter Adapter] - .... link:securing_apps/topics/oidc/java/jaas.adoc[JAAS plugin] - {% endif %} - .... link:securing_apps/topics/oidc/java/adapter-context.adoc[Security Context] - .... link:securing_apps/topics/oidc/java/adapter_error_handling.adoc[Error Handling] - .... link:securing_apps/topics/oidc/java/logout.adoc[Logout] - .... link:securing_apps/topics/oidc/java/params_forwarding.adoc[Parameters Forwarding] - .... link:securing_apps/topics/oidc/java/client-authentication.adoc[Client Authentication] - .... link:securing_apps/topics/oidc/java/multi-tenancy.adoc[Multi Tenancy] - .... link:securing_apps/topics/oidc/java/application-clustering.adoc[Application Clustering] - - ... link:securing_apps/topics/oidc/javascript-adapter.adoc[JavaScript Adapter] - - ... link:securing_apps/topics/oidc/nodejs-adapter.adoc[Node.js Adapter] - - ... link:securing_apps/topics/oidc/oidc-generic.adoc[Other OpenID Connect libraries] - {% if book.community %} - .... link:securing_apps/topics/oidc/mod-auth-openidc.adoc[mod_auth_oidc Apache HTTPD Module] - {% endif %} - - .. link:securing_apps/topics/saml/saml-overview.adoc[SAML] - ... link:securing_apps/topics/saml/java/java-adapters.adoc[Java Adapters] - .... link:securing_apps/topics/saml/java/general-config.adoc[General Adapter Config] - ..... link:securing_apps/topics/saml/java/general-config/sp_element.adoc[SP Element] - ..... link:securing_apps/topics/saml/java/general-config/sp-keys.adoc[SP Keys and Key elements] - ...... link:securing_apps/topics/saml/java/general-config/sp-keys/keystore_element.adoc[KeyStore Element] - ...... link:securing_apps/topics/saml/java/general-config/sp-keys/key_pems.adoc[Key PEMS] - ..... link:securing_apps/topics/saml/java/general-config/sp_principalname_mapping_element.adoc[SP PrincipalNameMapping element] - ..... link:securing_apps/topics/saml/java/general-config/roleidentifiers_element.adoc[RoleIdentifiers element] - ..... link:securing_apps/topics/saml/java/general-config/idp_element.adoc[IDP Element] - ..... link:securing_apps/topics/saml/java/general-config/idp_singlesignonservice_subelement.adoc[IDP SingleSignOnService sub element] - ..... link:securing_apps/topics/saml/java/general-config/idp_singlelogoutservice_subelement.adoc[IDP SingleLogoutService sub element] - ..... link:securing_apps/topics/saml/java/general-config/idp_keys_subelement.adoc[IDP Keys subelement] - ..... link:securing_apps/topics/saml/java/general-config/idp_httpclient_subelement.adoc[IDP HttpClient subelement] - .... link:securing_apps/topics/saml/java/saml-jboss-adapter.adoc[JBoss EAP/Wildfly Adapter] - ..... link:securing_apps/topics/saml/java/jboss-adapter/jboss_adapter_installation.adoc[Adapter Installation] - ..... link:securing_apps/topics/saml/java/jboss-adapter/required_per_war_configuration.adoc[Per WAR Configuration] - ..... link:securing_apps/topics/saml/java/jboss-adapter/securing_wars.adoc[Securing WARs via SAML Subsystem] - {% if book.community %} - .... link:securing_apps/topics/saml/java/tomcat-adapter.adoc[Tomcat SAML adapters] - ..... link:securing_apps/topics/saml/java/tomcat-adapter/tomcat_adapter_installation.adoc[Adapter Installation] - ..... link:securing_apps/topics/saml/java/tomcat-adapter/tomcat_adapter_per_war_config.adoc[Per WAR Configuration] - .... link:securing_apps/topics/saml/java/jetty-adapter.adoc[Jetty SAML Adapters] - ..... link:securing_apps/topics/saml/java/jetty-adapter/jetty9_installation.adoc[Jetty 9 Adapter Installation] - ..... link:securing_apps/topics/saml/java/jetty-adapter/jetty9_per_war_config.adoc[Jetty 9 Per WAR Configuration] - ..... link:securing_apps/topics/saml/java/jetty-adapter/jetty8-installation.adoc[Jetty 8 Adapter Installation] - ..... link:securing_apps/topics/saml/java/jetty-adapter/jetty8-per_war_config.adoc[Jetty 8 Per WAR Configuration] - {% endif %} - {% if book.community %} - .... link:securing_apps/topics/saml/java/servlet-filter-adapter.adoc[Java Servlet Filter Adapter] - {% endif %} - .... link:securing_apps/topics/saml/java/idp-registration.adoc[Registering with an IDP] - .... link:securing_apps/topics/saml/java/logout.adoc[Logout] - .... link:securing_apps/topics/saml/java/assertion-api.adoc[Obtaining Assertion Attributes] - .... link:securing_apps/topics/saml/java/error_handling.adoc[Error Handling] - .... link:securing_apps/topics/saml/java/debugging.adoc[Troubleshooting] - {% if book.community %} - .... link:securing_apps/topics/saml/java/MigrationFromOlderVersions.adoc[Migration from older versions] - {% endif %} - ... link:securing_apps/topics/saml/mod-auth-mellon.adoc[mod_auth_mellon Apache HTTPD Module] - .. link:securing_apps/topics/docker/docker-overview.adoc[Docker] - .. link:securing_apps/topics/client-registration.adoc[Client Registration] - ... link:securing_apps/topics/client-registration/client-registration-cli.adoc[Client Registration CLI] diff --git a/securing_apps/book-product.json b/securing_apps/book-product.json deleted file mode 100755 index 6ae6fa3aa0c..00000000000 --- a/securing_apps/book-product.json +++ /dev/null @@ -1,35 +0,0 @@ -{ - "gitbook": "2.x.x", - "structure": { - "readme": "README.adoc" - }, - "plugins": [ - "toggle-chapters", - "ungrey", - "splitter" - ], - "variables": { - "title": "Securing Applications and Services Guide", - "project": { - "name": "Red Hat Single Sign-On", - "version": "7.1.0", - "versionMvn": "2.5.5.Final-redhat-1", - "versionNpm": "2.5.5-Final-redhat-1", - "doc_base_url": "https://access.redhat.com/documentation/en/red-hat-single-sign-on/", - "doc_info_version_url": "7.1" - }, - "community": false, - "product": true, - "images": "rhsso-images", - "adminguide": { - "name": "Server Administration Guide", - "link": "https://access.redhat.com/documentation/en/red-hat-single-sign-on/7.1/html-single/server-administration-guide/" - }, - "fuseVersion": "JBoss Fuse 6.3.0 Rollup 2", - "subsystem": { - "undertow": "urn:jboss:domain:undertow:3.1" - }, - "hawtioEAPVersion": "JBoss EAP 6.4", - "hawtioWARVersion": "hawtio-wildfly-1.4.0.redhat-630254.war" - } -} diff --git a/securing_apps/buildGuide.sh b/securing_apps/buildGuide.sh deleted file mode 100755 index b37f0c97dd0..00000000000 --- a/securing_apps/buildGuide.sh +++ /dev/null @@ -1,80 +0,0 @@ -# Build the guide - -# Find the directory name and full path -CURRENT_GUIDE=${PWD##*/} -CURRENT_DIRECTORY=$(pwd) - -usage(){ - cat <&2 - usage - exit 1;; - esac -done - -echo "" -echo "********************************************" -echo " Building $CURRENT_GUIDE " -echo "********************************************" -if [ ! -d target ]; then - echo "You must run 'python gitlab-conversion.py' to convert the content before you run this script." - exit -fi - -# Remove the guide directory path from the master.adoc file as it is not needed -echo "" -echo "***************************************************************************************" -echo "Removing the guide directory path from the master.adoc file as it is not needed." -echo "NOTE: The guide directory path should probably be removed from the SUMMARY.adoc file," -echo "but since we do not know if it will break the upstream build, we are doing this here. " -echo "If it can not be removed from the SUMMARY.adoc file, this should really be done in the " -echo "Python script because otherwise you must run this script before porting content!" -echo "***************************************************************************************" -echo "" -find . -name 'master.adoc' -print | xargs sed -i "s/include::$CURRENT_GUIDE\//include::/g" - -# Remove the html and build directories and then recreate the html/images/ directory -if [ -d target/html ]; then - rm -r target/html/ -fi -if [ -d target/html ]; then - rm -r target/html/ -fi - -mkdir -p html -cp -r target/images/ target/html/ - -echo "Building an asciidoctor version of the guide" -asciidoctor -t -dbook -a toc -o target/html/$CURRENT_GUIDE.html target/master.adoc - -echo "" -echo "Building a ccutil version of the guide" -ccutil compile --lang en_US --format html-single --main-file target/master.adoc - -cd .. - -echo "View the asciidoctor build here: " file://$CURRENT_DIRECTORY/target/html/$CURRENT_GUIDE.html - -if [ -d $CURRENT_DIRECTORY/build/tmp/en-US/html-single/ ]; then - echo "View the ccutil build here: " file://$CURRENT_DIRECTORY/build/tmp/en-US/html-single/index.html - exit 0 -else - echo -e "${RED}Build using ccutil failed!" - echo -e "${BLACK}See the log above for details." - exit 1 -fi diff --git a/securing_apps/gitlab-conversion.py b/securing_apps/gitlab-conversion.py deleted file mode 100755 index f2e87906cc9..00000000000 --- a/securing_apps/gitlab-conversion.py +++ /dev/null @@ -1,113 +0,0 @@ -import sys, os, re, json, shutil, errno - -def transform(root, f, targetdir): - full = os.path.join(root, f) - input = open(full, 'r').read() - dir = os.path.join(targetdir, root) - if not os.path.exists(dir): - os.makedirs(dir) - output = open(os.path.join(dir, f), 'w') - input = applyTransformation(input) - output.write(input) - - -def applyTransformation(input): - for variable in re.findall(r"\{\{(.*?)\}\}", input): - tmp = variable.replace('.', '_') - input = input.replace(variable, tmp) - input = input.replace('{{', '{').replace('}}', '}') - input = re.sub(r"<}==true]\g<2>endif::[]", input) - input = re.sub(r"image:(\.\./)*", "image:", input) - input = re.sub(r"image::(\.\./)*", "image::", input) - return input - - -indir = 'topics' -targetdir = 'target' -if len(sys.argv) > 1: - targetdir = sys.argv[1] - -if os.path.exists(targetdir): - shutil.rmtree(targetdir) - -if os.path.isdir('images'): - shutil.copytree('images',os.path.join(targetdir, 'images')) -if os.path.isdir('keycloak-images'): - shutil.copytree('keycloak-images',os.path.join(targetdir, 'keycloak-images')) -if os.path.isdir('rhsso-images'): - shutil.copytree('rhsso-images',os.path.join(targetdir, 'rhsso-images')) - -shutil.copyfile('metadata.ini', os.path.join(targetdir, 'metadata.ini')); -shutil.copyfile('master-docinfo.xml', os.path.join(targetdir, 'master-docinfo.xml')); - -tmp = os.path.join(targetdir, 'topics') -if not os.path.exists(tmp): - os.makedirs(tmp) - -# transform files -for root, dirs, filenames in os.walk(indir): - for f in filenames: - transform(root,f,targetdir) - -# Create master.doc includes -input = open('SUMMARY.adoc', 'r').read() -output = open(os.path.join(targetdir, 'master.adoc'), 'w') - -output.write(""" -:toc: -:toclevels: 3 -:numbered: - -include::document-attributes.adoc[] -""") - -input = re.sub(r"[ ]*\.+\s*link:[^/]+/(.*)\[(.*)\]", "include::\g<1>[]", input) -input = applyTransformation(input) -output.write(input) - -# parse book-product.json file and create document attributes -with open('book-product.json') as data_file: - data = json.load(data_file) - -variables = data['variables'] - -def makeAttributes(variables, variable, list): - for i in variables.keys(): - if variable is None: - tmp = i - else: - tmp = variable + '_' + i - if isinstance(variables[i],dict): - makeAttributes(variables[i], tmp, list) - elif isinstance(variables[i],bool): - boolval = 'false' - if variables[i]: - boolval = 'true' - list.append({tmp: boolval}) - else: - list.append({tmp: str(variables[i])}) - - -attributeList = [] -makeAttributes(variables, None, attributeList) - -output = open(os.path.join(targetdir, 'document-attributes.adoc'), 'w') -for attribute in attributeList: - for k in attribute.keys(): - output.write(':book_' + k + ": " + attribute[k] + "\n") - -print "Transformation complete!" - - - - - - - - - diff --git a/securing_apps/index.adoc b/securing_apps/index.adoc new file mode 100644 index 00000000000..7e6c6cf73db --- /dev/null +++ b/securing_apps/index.adoc @@ -0,0 +1,6 @@ +:toc: +:toclevels: 3 +:numbered: + +include::../document-attributes-community.adoc[] +include::topics.adoc[] \ No newline at end of file diff --git a/securing_apps/master-docinfo.xml b/securing_apps/master-docinfo.xml old mode 100755 new mode 100644 index 441adff99e6..bafad791bec --- a/securing_apps/master-docinfo.xml +++ b/securing_apps/master-docinfo.xml @@ -1,10 +1,10 @@ -{book_project_name} -{book_project_doc_info_version_url} -For Use with {book_project_name} {book_project_doc_info_version_url} -{book_title} +{project_name} +{project_doc_info_version_url} +For Use with {project_name} {project_doc_info_version_url} +{title} {doc_info_version_url} - This guide consists of information for securing applications and services using {book_project_name} {book_project_doc_info_version_url} + This guide consists of information for securing applications and services using {project_name} {project_doc_info_version_url} Red Hat Customer Content Services diff --git a/securing_apps/master.adoc b/securing_apps/master.adoc new file mode 100644 index 00000000000..cc0fdffa8d3 --- /dev/null +++ b/securing_apps/master.adoc @@ -0,0 +1,6 @@ +:toc: +:toclevels: 3 +:numbered: + +include::../document-attributes-product.adoc[] +include::topics.adoc[] \ No newline at end of file diff --git a/securing_apps/pom.xml b/securing_apps/pom.xml new file mode 100644 index 00000000000..b4df1f18308 --- /dev/null +++ b/securing_apps/pom.xml @@ -0,0 +1,29 @@ + + + 4.0.0 + + + org.keycloak.documentation + documentation-parent + 1.0.0-SNAPSHOT + ../ + + + Securing Applications and Services + securing-apps + pom + + + + + org.asciidoctor + asciidoctor-maven-plugin + + + asciidoc-to-html + + + + + + diff --git a/securing_apps/topics.adoc b/securing_apps/topics.adoc new file mode 100644 index 00000000000..8b34ad5984f --- /dev/null +++ b/securing_apps/topics.adoc @@ -0,0 +1,90 @@ +include::topics/overview/overview.adoc[] +include::topics/overview/what-are-client-adapters.adoc[] +include::topics/overview/supported-platforms.adoc[] +include::topics/overview/supported-protocols.adoc[] + +include::topics/oidc/oidc-overview.adoc[] + +include::topics/oidc/java/java-adapters.adoc[] +include::topics/oidc/java/java-adapter-config.adoc[] +include::topics/oidc/java/jboss-adapter.adoc[] +include::topics/oidc/java/fuse-adapter.adoc[] +include::topics/oidc/java/fuse/install-feature.adoc[] +include::topics/oidc/java/fuse/classic-war.adoc[] +include::topics/oidc/java/fuse/servlet-whiteboard.adoc[] +include::topics/oidc/java/fuse/camel.adoc[] +include::topics/oidc/java/fuse/cxf-separate.adoc[] +include::topics/oidc/java/fuse/cxf-builtin.adoc[] +include::topics/oidc/java/fuse/fuse-admin.adoc[] +include::topics/oidc/java/fuse/hawtio.adoc[] +ifeval::[{project_community}==true] +include::topics/oidc/java/tomcat-adapter.adoc[] +include::topics/oidc/java/jetty9-adapter.adoc[] +include::topics/oidc/java/jetty8-adapter.adoc[] +include::topics/oidc/java/spring-boot-adapter.adoc[] +include::topics/oidc/java/spring-security-adapter.adoc[] +endif::[] +ifeval::[{project_community}==true] +include::topics/oidc/java/servlet-filter-adapter.adoc[] +include::topics/oidc/java/jaas.adoc[] +endif::[] +include::topics/oidc/java/adapter-context.adoc[] +include::topics/oidc/java/adapter_error_handling.adoc[] +include::topics/oidc/java/logout.adoc[] +include::topics/oidc/java/params_forwarding.adoc[] +include::topics/oidc/java/client-authentication.adoc[] +include::topics/oidc/java/multi-tenancy.adoc[] +include::topics/oidc/java/application-clustering.adoc[] + +include::topics/oidc/javascript-adapter.adoc[] + +include::topics/oidc/nodejs-adapter.adoc[] + +include::topics/oidc/oidc-generic.adoc[] +ifeval::[{project_community}==true] +include::topics/oidc/mod-auth-openidc.adoc[] +endif::[] + +include::topics/saml/saml-overview.adoc[] +include::topics/saml/java/java-adapters.adoc[] +include::topics/saml/java/general-config.adoc[] +include::topics/saml/java/general-config/sp_element.adoc[] +include::topics/saml/java/general-config/sp-keys.adoc[] +include::topics/saml/java/general-config/sp-keys/keystore_element.adoc[] +include::topics/saml/java/general-config/sp-keys/key_pems.adoc[] +include::topics/saml/java/general-config/sp_principalname_mapping_element.adoc[] +include::topics/saml/java/general-config/roleidentifiers_element.adoc[] +include::topics/saml/java/general-config/idp_element.adoc[] +include::topics/saml/java/general-config/idp_singlesignonservice_subelement.adoc[] +include::topics/saml/java/general-config/idp_singlelogoutservice_subelement.adoc[] +include::topics/saml/java/general-config/idp_keys_subelement.adoc[] +include::topics/saml/java/general-config/idp_httpclient_subelement.adoc[] +include::topics/saml/java/saml-jboss-adapter.adoc[] +include::topics/saml/java/jboss-adapter/jboss_adapter_installation.adoc[] +include::topics/saml/java/jboss-adapter/required_per_war_configuration.adoc[] +include::topics/saml/java/jboss-adapter/securing_wars.adoc[] +ifeval::[{project_community}==true] +include::topics/saml/java/tomcat-adapter.adoc[] +include::topics/saml/java/tomcat-adapter/tomcat_adapter_installation.adoc[] +include::topics/saml/java/tomcat-adapter/tomcat_adapter_per_war_config.adoc[] +include::topics/saml/java/jetty-adapter.adoc[] +include::topics/saml/java/jetty-adapter/jetty9_installation.adoc[] +include::topics/saml/java/jetty-adapter/jetty9_per_war_config.adoc[] +include::topics/saml/java/jetty-adapter/jetty8-installation.adoc[] +include::topics/saml/java/jetty-adapter/jetty8-per_war_config.adoc[] +endif::[] +ifeval::[{project_community}==true] +include::topics/saml/java/servlet-filter-adapter.adoc[] +endif::[] +include::topics/saml/java/idp-registration.adoc[] +include::topics/saml/java/logout.adoc[] +include::topics/saml/java/assertion-api.adoc[] +include::topics/saml/java/error_handling.adoc[] +include::topics/saml/java/debugging.adoc[] +ifeval::[{project_community}==true] +include::topics/saml/java/MigrationFromOlderVersions.adoc[] +endif::[] +include::topics/saml/mod-auth-mellon.adoc[] +include::topics/docker/docker-overview.adoc[] +include::topics/client-registration.adoc[] +include::topics/client-registration/client-registration-cli.adoc[] diff --git a/securing_apps/topics/client-registration.adoc b/securing_apps/topics/client-registration.adoc index 01a6e43d8d1..024a5ae2ae0 100644 --- a/securing_apps/topics/client-registration.adoc +++ b/securing_apps/topics/client-registration.adoc @@ -1,17 +1,17 @@ [[_client_registration]] == Client Registration -In order for an application or service to utilize {{book.project.name}} it has to register a client in {{book.project.name}}. -An admin can do this through the admin console (or admin REST endpoints), but clients can also register themselves through the {{book.project.name}} client +In order for an application or service to utilize {project_name} it has to register a client in {project_name}. +An admin can do this through the admin console (or admin REST endpoints), but clients can also register themselves through the {project_name} client registration service. -The Client Registration Service provides built-in support for {{book.project.name}} Client Representations, OpenID Connect Client Meta Data and SAML Entity Descriptors. +The Client Registration Service provides built-in support for {project_name} Client Representations, OpenID Connect Client Meta Data and SAML Entity Descriptors. The Client Registration Service endpoint is `/realms//clients-registrations/`. The built-in supported `providers` are: -* default - {{book.project.name}} Client Representation (JSON) -* install - {{book.project.name}} Adapter Configuration (JSON) +* default - {project_name} Client Representation (JSON) +* install - {project_name} Adapter Configuration (JSON) * openid-connect - OpenID Connect Client Metadata Description (JSON) * saml2-entity-descriptor - SAML Entity Descriptor (XML) @@ -24,13 +24,13 @@ There is an alternative to register new client without any token as well, but th ==== Bearer Token -The bearer token can be issued on behalf of a user or a Service Account. The following permissions are required to invoke the endpoints (see link:{{book.adminguide.link}}[{{book.adminguide.name}}] for more details): +The bearer token can be issued on behalf of a user or a Service Account. The following permissions are required to invoke the endpoints (see link:{adminguide_link}[{adminguide_name}] for more details): * create-client or manage-client - To create clients * view-client or manage-client - To view clients * manage-client - To update or delete client -If you are using a bearer token to create clients it's recommend to use a token from a Service Account with only the `create-client` role (see link:{{book.adminguide.link}}[{{book.adminguide.name}}] for more details). +If you are using a bearer token to create clients it's recommend to use a token from a Service Account with only the `create-client` role (see link:{adminguide_link}[{adminguide_name}] for more details). ==== Initial Access Token @@ -66,10 +66,10 @@ If a client was created outside of the Client Registration Service it won't have You can create one through the admin console. This can also be useful if you loose the token for a particular client. To create a new token find the client in the admin console and click on `Credentials`. Then click on `Generate registration access token`. -=== {{book.project.name}} Representations +=== {project_name} Representations The `default` client registration provider can be used to create, retrieve, update and delete a client. -It uses {{book.project.name}} Client Representation format which provides support for configuring clients exactly as they can be configured through the admin +It uses {project_name} Client Representation format which provides support for configuring clients exactly as they can be configured through the admin console, including for example configuring protocol mappers. To create a client create a Client Representation (JSON) then do a HTTP POST to `/realms//clients-registrations/default`. @@ -89,7 +89,7 @@ It will also return a new registration access token. To delete the Client Representation then do a HTTP DELETE to: `/realms//clients-registrations/default/` -=== {{book.project.name}} Adapter Configuration +=== {project_name} Adapter Configuration The `installation` client registration provider can be used to retrieve the adapter configuration for a client. In addition to token authentication you can also authenticate with client credentials using HTTP basic authentication. @@ -103,13 +103,13 @@ Authorization: basic BASE64(client-id + ':' + client-secret) To retrieve the Adapter Configuration then do a HTTP GET to `/realms//clients-registrations/install/`. No authentication is required for public clients. -This means that for the JavaScript adapter you can load the client configuration directly from {{book.project.name}} using the above URL. +This means that for the JavaScript adapter you can load the client configuration directly from {project_name} using the above URL. === OpenID Connect Dynamic Client Registration -{{book.project.name}} implements https://openid.net/specs/openid-connect-registration-1_0.html[OpenID Connect Dynamic Client Registration], which extends https://tools.ietf.org/html/rfc7591[OAuth 2.0 Dynamic Client Registration Protocol] and https://tools.ietf.org/html/rfc7592[OAuth 2.0 Dynamic Client Registration Management Protocol]. +{project_name} implements https://openid.net/specs/openid-connect-registration-1_0.html[OpenID Connect Dynamic Client Registration], which extends https://tools.ietf.org/html/rfc7591[OAuth 2.0 Dynamic Client Registration Protocol] and https://tools.ietf.org/html/rfc7592[OAuth 2.0 Dynamic Client Registration Management Protocol]. -The endpoint to use these specifications to register clients in {{book.project.name}} is `/realms//clients-registrations/openid-connect[/]`. +The endpoint to use these specifications to register clients in {project_name} is `/realms//clients-registrations/openid-connect[/]`. This endpoints can also be found in the OpenID Connect Discovery endpoint for the realm, `/realms//.well-known/openid-configuration`. @@ -117,8 +117,8 @@ This endpoints can also be found in the OpenID Connect Discovery endpoint for th The SAML Entity Descriptor endpoint only supports using SAML v2 Entity Descriptors to create clients. It doesn't support retrieving, updating or deleting clients. -For those operations the {{book.project.name}} representation endpoints should be used. -When creating a client a {{book.project.name}} Client Representation is returned with details about the created client, including a registration access token. +For those operations the {project_name} representation endpoints should be used. +When creating a client a {project_name} Client Representation is returned with details about the created client, including a registration access token. To create a client do a HTTP POST with the SAML Entity Descriptor to `/realms//clients-registrations/saml2-entity-descriptor`. @@ -164,7 +164,7 @@ String registrationAccessToken = client.getRegistrationAccessToken(); === Client Registration Policies -{{book.project.name}} currently supports 2 ways how can be new clients registered through Client Registration Service. +{project_name} currently supports 2 ways how can be new clients registered through Client Registration Service. * Authenticated requests - Request to register new client must contain either `Initial Access Token` or `Bearer Token` as mentioned above. @@ -173,7 +173,7 @@ String registrationAccessToken = client.getRegistrationAccessToken(); Anonymous client registration requests are very interesting and powerful feature, however you usually don't want that anyone is able to register new client without any limitations. Hence we have `Client Registration Policy SPI`, which provide a way to limit who can register new clients and under which conditions. -In {{book.project.name}} admin console, you can click to `Client Registration` tab and then `Client Registration Policies` sub-tab. Here you will see what policies +In {project_name} admin console, you can click to `Client Registration` tab and then `Client Registration Policies` sub-tab. Here you will see what policies are configured by default for anonymous requests and what policies are configured for authenticated requests. NOTE: The anonymous requests (requests without any token) are allowed just for creating (registration) of new clients. So when you register diff --git a/securing_apps/topics/client-registration/client-registration-cli.adoc b/securing_apps/topics/client-registration/client-registration-cli.adoc index 51d0d574017..612925da6bd 100644 --- a/securing_apps/topics/client-registration/client-registration-cli.adoc +++ b/securing_apps/topics/client-registration/client-registration-cli.adoc @@ -1,19 +1,19 @@ [[_client_registration_cli]] == Client Registration CLI -{% if book.product %} +ifeval::[{project_product}==true] NOTE: Client Registration CLI is a Technology Preview feature and is not fully supported. -{% endif %} +endif::[] `Client Registration CLI` is a command line interface tool that can be used by application developers to configure new clients -to integrate with {book_project_name}. It is specifically designed to interact with {{book.project.name}} Client Registration REST endpoints. +to integrate with {project_name}. It is specifically designed to interact with {project_name} Client Registration REST endpoints. It is necessary to create a new client configuration for each new application hosted on a unique hostname in order for Keycloak to be able to interact with the application (and vice-versa) and perform its function of providing a login page, SSO session management etc. `Client Registration CLI` allows you to configure application clients from a command line, and can be used in shell scripts as well. -To allow a particular user to use `Client Registration CLI` a {book_project_name} administrator will typically use `Admin Console` to configure +To allow a particular user to use `Client Registration CLI` a {project_name} administrator will typically use `Admin Console` to configure a new user, or configure a new client, and a client secret, to protect access to `Client Registration REST API`. @@ -133,7 +133,7 @@ If you need to manage different realms, you need to configure users in different web interface or `Admin Client CLI` once it's available. When `kcreg` successfully logs in it receives authorization tokens and saves them into a private config file so they can be -used for subsequent invocations. See <> for more info on configuration file. +used for subsequent invocations. See <<_working_with_alternative_configurations, next chapter>> for more info on configuration file. See built-in help for more information on using `Client Registration CLI`. @@ -222,7 +222,7 @@ created client. As long as the same configuration file is used for all client op authenticate in order to read, update, or delete a client they created. -You can read more about Initial Access and Registration Access Tokens in <>. +You can read more about Initial Access and Registration Access Tokens in <<_client_registration,Client Registration chapter>>. See `kcreg config initial-token --help` and `kcreg config registration-token --help` for more information on how to configure them with `Client Registration CLI`. diff --git a/securing_apps/topics/docker/docker-overview.adoc b/securing_apps/topics/docker/docker-overview.adoc index 120f714d1c3..ebcc0f4b52f 100644 --- a/securing_apps/topics/docker/docker-overview.adoc +++ b/securing_apps/topics/docker/docker-overview.adoc @@ -1,9 +1,9 @@ == Docker Registry Configuration -NOTE: Docker authentication is disabled by default. To enable see link:{{book.installguide.profile.link}}[{{book.installguide.profile.name}}]. +NOTE: Docker authentication is disabled by default. To enable see link:{installguide_profile_link}[{installguide_profile_name}]. -This section describes how you can configure a Docker registry to use {{book.project.name}} as its authentication server. +This section describes how you can configure a Docker registry to use {project_name} as its authentication server. Fore more information on how to set up and configure a Docker registry, see the link:https://docs.docker.com/registry/configuration/[Docker Registry Configuration Guide]. @@ -11,7 +11,7 @@ Fore more information on how to set up and configure a Docker registry, see the === Docker Registry Configuration File Installation -For users with more advanced docker registry configurations, it is generally recommended to provide your own registry configuration file. The {{book.project.name}} docker provider supports this mechanism via the _Registry Config File_ Format Option. Choosing this option will generate output similar to the following: +For users with more advanced docker registry configurations, it is generally recommended to provide your own registry configuration file. The {project_name} docker provider supports this mechanism via the _Registry Config File_ Format Option. Choosing this option will generate output similar to the following: auth: token: @@ -21,7 +21,7 @@ For users with more advanced docker registry configurations, it is generally rec This output can then be copied into any existing registry config file. See the link:https://docs.docker.com/registry/configuration/[registry config file specification] for more information on how the file should be set up, or start with href:https://github.com/docker/distribution/blob/master/cmd/registry/config-example.yml[a basic example]. -WARNING: Don't forget to configure the `rootcertbundle` field with the location of the {{book.project.name}} realm's pulic certificate. The auth configuration will not work without this argument. +WARNING: Don't forget to configure the `rootcertbundle` field with the location of the {project_name} realm's pulic certificate. The auth configuration will not work without this argument. === Docker Registry Environment Variable Override Installation @@ -32,7 +32,7 @@ Often times it is appropriate to use a simple environment variable override for REGISTRY_AUTH_TOKEN_SERVICE: docker-test REGISTRY_AUTH_TOKEN_ISSUER: http://localhost:8080/auth/auth/realms/master -WARNING: Don't forget to configure the `REGISTRY_AUTH_TOKEN_ROOTCERTBUNDLE` override with the location of the {{book.project.name}} realm's pulic certificate. The auth configuration will not work without this argument. +WARNING: Don't forget to configure the `REGISTRY_AUTH_TOKEN_ROOTCERTBUNDLE` override with the location of the {project_name} realm's pulic certificate. The auth configuration will not work without this argument. === Docker Compose YAML File @@ -42,9 +42,9 @@ WARNING: This installation method is meant to be an easy way to get a docker reg The zip file installation mechanism provides a quickstart for developers who want to understand how the keycloak server can interact with the docker registry. In order to configure: 1. From the desired realm, create a client configuration. At this point you won't have a docker registry - the quickstart will take care of that part. - 1. Choose the "Docker Compose YAML" option from the installation tab and download the .zip file - 1. Unzip the archive to the desired location, and open the directory. - 1. Start the docker registry with `docker-compose up` + 2. Choose the "Docker Compose YAML" option from the installation tab and download the .zip file + 3. Unzip the archive to the desired location, and open the directory. + 4. Start the docker registry with `docker-compose up` INFO: it is recommended that you configure the docker registry client in a realm other than 'master', since the HTTP Basic auth flow will not present forms. diff --git a/securing_apps/topics/oidc/java/adapter-context.adoc b/securing_apps/topics/oidc/java/adapter-context.adoc index 92f7c8b8347..a04d36967d3 100644 --- a/securing_apps/topics/oidc/java/adapter-context.adoc +++ b/securing_apps/topics/oidc/java/adapter-context.adoc @@ -1,7 +1,7 @@ ==== Security Context The `KeycloakSecurityContext` interface is available if you need to access to the tokens directly. This could be useful if you want to retrieve additional -details from the token (such as user profile information) or you want to invoke a RESTful service that is protected by {{book.project.name}}. +details from the token (such as user profile information) or you want to invoke a RESTful service that is protected by {project_name}. In servlet environments it is available in secured invocations as an attribute in HttpServletRequest: [source,java] diff --git a/securing_apps/topics/oidc/java/adapter_error_handling.adoc b/securing_apps/topics/oidc/java/adapter_error_handling.adoc index 969e5897a2f..cb9a5c59667 100644 --- a/securing_apps/topics/oidc/java/adapter_error_handling.adoc +++ b/securing_apps/topics/oidc/java/adapter_error_handling.adoc @@ -2,10 +2,10 @@ [[_adapter_error_handling]] ==== Error Handling -{{book.project.name}} has some error handling facilities for servlet based client adapters. -When an error is encountered in authentication, {{book.project.name}} will call `HttpServletResponse.sendError()`. +{project_name} has some error handling facilities for servlet based client adapters. +When an error is encountered in authentication, {project_name} will call `HttpServletResponse.sendError()`. You can set up an error-page within your `web.xml` file to handle the error however you want. -{{book.project.name}} can throw 400, 401, 403, and 500 errors. +{project_name} can throw 400, 401, 403, and 500 errors. [source,xml] ---- @@ -15,7 +15,7 @@ You can set up an error-page within your `web.xml` file to handle the error howe ---- -{{book.project.name}} also sets a `HttpServletRequest` attribute that you can retrieve. +{project_name} also sets a `HttpServletRequest` attribute that you can retrieve. The attribute name is `org.keycloak.adapters.spi.AuthenticationError`, which should be casted to `org.keycloak.adapters.OIDCAuthenticationError`. For example: diff --git a/securing_apps/topics/oidc/java/application-clustering.adoc b/securing_apps/topics/oidc/java/application-clustering.adoc index 798d7347e8e..dba2a9e7c17 100644 --- a/securing_apps/topics/oidc/java/application-clustering.adoc +++ b/securing_apps/topics/oidc/java/application-clustering.adoc @@ -1,26 +1,26 @@ [[_applicationclustering]] ==== Application Clustering -{% if book.community %} +ifeval::[{project_community}==true] This chapter is related to supporting clustered applications deployed to JBoss EAP, WildFly and JBoss AS. -{% endif %} -{% if book.product %} +endif::[] +ifeval::[{project_product}==true] This chapter is related to supporting clustered applications deployed to JBoss EAP. -{% endif %} +endif::[] There are a few options available depending on whether your application is: * Stateless or stateful * Distributable (replicated http session) or non-distributable * Relying on sticky sessions provided by load balancer -* Hosted on same domain as {{book.project.name}} +* Hosted on same domain as {project_name} Dealing with clustering is not quite as simple as for a regular application. Mainly due to the fact that both the browser and the server-side application -sends requests to {{book.project.name}}, so it's not as simple as enabling sticky sessions on your load balancer. +sends requests to {project_name}, so it's not as simple as enabling sticky sessions on your load balancer. ===== Stateless token store -By default, the web application secured by {{book.project.name}} uses the HTTP session to store security context. This means that you either have to +By default, the web application secured by {project_name} uses the HTTP session to store security context. This means that you either have to enable sticky sessions or replicate the HTTP session. As an alternative to storing the security context in the HTTP session the adapter can be configured to store this in a cookie instead. This is useful if you want @@ -38,29 +38,29 @@ One limitation of using the cookie store is that the whole security context is p Another small limitation is limited support for Single-Sign Out. It works without issues if you init servlet logout (HttpServletRequest.logout) from the application itself as the adapter will delete the KEYCLOAK_ADAPTER_STATE cookie. However, back-channel logout initialized from a different application isn't -propagated by {{book.project.name}} to applications using cookie store. Hence it's recommended to use a short value for the access token timeout (for example 1 minute). +propagated by {project_name} to applications using cookie store. Hence it's recommended to use a short value for the access token timeout (for example 1 minute). ===== Relative URI optimization -In deployment scenarios where {{book.project.name}} and the application is hosted on the same domain (through a reverse proxy or load balancer) it can be +In deployment scenarios where {project_name} and the application is hosted on the same domain (through a reverse proxy or load balancer) it can be convenient to use relative URI options in your client configuration. -With relative URIs the URI is resolved as relative to the URL of the URL used to access {{book.project.name}}. +With relative URIs the URI is resolved as relative to the URL of the URL used to access {project_name}. -For example if the URL to your application is `$$https://acme.org/myapp$$` and the URL to {{book.project.name}} is `$$https://acme.org/auth$$`, then you can use +For example if the URL to your application is `$$https://acme.org/myapp$$` and the URL to {project_name} is `$$https://acme.org/auth$$`, then you can use the redirect-uri `/myapp` instead of `$$https://acme.org/myapp$$`. ===== Admin URL configuration -Admin URL for a particular client can be configured in the {{book.project.name}} Administration Console. -It's used by the {{book.project.name}} server to send backend requests to the application for various tasks, like logout users or push revocation policies. +Admin URL for a particular client can be configured in the {project_name} Administration Console. +It's used by the {project_name} server to send backend requests to the application for various tasks, like logout users or push revocation policies. For example the way backchannel logout works is: . User sends logout request from one application -. The application sends logout request to {{book.project.name}} -. The {{book.project.name}} server invalidates the user session -. The {{book.project.name}} server then sends a backchannel request to application with an admin url that are associated with the session +. The application sends logout request to {project_name} +. The {project_name} server invalidates the user session +. The {project_name} server then sends a backchannel request to application with an admin url that are associated with the session . When an application receives the logout request it invalidates the corresponding HTTP session If admin URL contains `${application.session.host}` it will be replaced with the URL to the node associated with the HTTP session. @@ -68,17 +68,17 @@ If admin URL contains `${application.session.host}` it will be replaced with the [[_registration_app_nodes]] ===== Registration of application nodes -The previous section describes how {{book.project.name}} can send logout request to node associated with a specific HTTP session. +The previous section describes how {project_name} can send logout request to node associated with a specific HTTP session. However, in some cases admin may want to propagate admin tasks to all registered cluster nodes, not just one of them. For example to push a new not before policy to the application or to logout all users from the application. -In this case {{book.project.name}} needs to be aware of all application cluster nodes, so it can send the event to all of them. +In this case {project_name} needs to be aware of all application cluster nodes, so it can send the event to all of them. To achieve this, we support auto-discovery mechanism: -. When a new application node joins the cluster, it sends a registration request to the {{book.project.name}} server -. The request may be re-sent to {{book.project.name}} in configured periodic intervals -. If the {{book.project.name}} server doesn't receive a re-registration request within a specified timeout then it automatically unregisters the specific node -. The node is also unregistered in {{book.project.name}} when it sends an unregistration request, which is usually during node shutdown or application undeployment. +. When a new application node joins the cluster, it sends a registration request to the {project_name} server +. The request may be re-sent to {project_name} in configured periodic intervals +. If the {project_name} server doesn't receive a re-registration request within a specified timeout then it automatically unregisters the specific node +. The node is also unregistered in {project_name} when it sends an unregistration request, which is usually during node shutdown or application undeployment. This may not work properly for forced shutdown when undeployment listeners are not invoked, which results in the need for automatic unregistration Sending startup registrations and periodic re-registration is disabled by default as it's only required for some clustered applications. @@ -93,7 +93,7 @@ To enable the feature edit the `WEB-INF/keycloak.json` file for your application This means the adapter will send the registration request on startup and re-register every 10 minutes. -In the {{book.project.name}} Administration Console you can specify the maximum node re-registration timeout (should be larger than _register-node-period_ from +In the {project_name} Administration Console you can specify the maximum node re-registration timeout (should be larger than _register-node-period_ from the adapter configuration). You can also manually add and remove cluster nodes in through the Adminstration Console, which is useful if you don't want to rely on the automatic registration feature or if you want to remove stale application nodes in the event your not using the automatic unregistration feature. @@ -101,7 +101,7 @@ on the automatic registration feature or if you want to remove stale application ===== Refresh token in each request By default the application adapter will only refresh the access token when it's expired. However, you can also configure the adapter to refresh the token on every -request. This may have a performance impact as your application will send more requests to the {{book.project.name}} server. +request. This may have a performance impact as your application will send more requests to the {project_name} server. To enable the feature edit the `WEB-INF/keycloak.json` file for your application and add: diff --git a/securing_apps/topics/oidc/java/client-authentication.adoc b/securing_apps/topics/oidc/java/client-authentication.adoc index d23507fd0a2..ccd2c78fac5 100644 --- a/securing_apps/topics/oidc/java/client-authentication.adoc +++ b/securing_apps/topics/oidc/java/client-authentication.adoc @@ -1,12 +1,12 @@ [[_client_authentication_adapter]] ==== Client Authentication -When a confidential OIDC client needs to send a backchannel request (for example, to exchange code for the token, or to refresh the token) it needs to authenticate against the {{book.project.name}} server. By default, there are two ways to authenticate the client: client ID and client secret, or client authentication with signed JWT. +When a confidential OIDC client needs to send a backchannel request (for example, to exchange code for the token, or to refresh the token) it needs to authenticate against the {project_name} server. By default, there are two ways to authenticate the client: client ID and client secret, or client authentication with signed JWT. ===== Client ID and Client Secret -This is the traditional method described in the OAuth2 specification. The client has a secret, which needs to be known to both the adapter (application) and the {{book.project.name}} server. -You can generate the secret for a particular client in the {{book.project.name}} administration console, and then paste this secret into the `keycloak.json` file on the application side: +This is the traditional method described in the OAuth2 specification. The client has a secret, which needs to be known to both the adapter (application) and the {project_name} server. +You can generate the secret for a particular client in the {project_name} administration console, and then paste this secret into the `keycloak.json` file on the application side: [source] @@ -20,19 +20,19 @@ You can generate the secret for a particular client in the {{book.project.name}} This is based on the https://tools.ietf.org/html/rfc7523[RFC7523] specification. It works this way: -* The client must have the private key and certificate. For {{book.project.name}} this is available through the traditional `keystore` file, which is either available on the client application's classpath or somewhere on the file system. +* The client must have the private key and certificate. For {project_name} this is available through the traditional `keystore` file, which is either available on the client application's classpath or somewhere on the file system. -* Once the client application is started, it allows to download its public key in https://self-issued.info/docs/draft-ietf-jose-json-web-key.html[JWKS] format using a URL such as \http://myhost.com/myapp/k_jwks, assuming that \http://myhost.com/myapp is the base URL of your client application. This URL can be used by {{book.project.name}} (see below). +* Once the client application is started, it allows to download its public key in https://self-issued.info/docs/draft-ietf-jose-json-web-key.html[JWKS] format using a URL such as \http://myhost.com/myapp/k_jwks, assuming that \http://myhost.com/myapp is the base URL of your client application. This URL can be used by {project_name} (see below). -* During authentication, the client generates a JWT token and signs it with its private key and sends it to {{book.project.name}} in +* During authentication, the client generates a JWT token and signs it with its private key and sends it to {project_name} in the particular backchannel request (for example, code-to-token request) in the `client_assertion` parameter. -* {{book.project.name}} must have the public key or certificate of the client so that it can verify the signature on JWT. In {{book.project.name}} you need to configure client credentials for your client. First you need to choose `Signed JWT` as the method of authenticating your client in the tab `Credentials` in administration console. +* {project_name} must have the public key or certificate of the client so that it can verify the signature on JWT. In {project_name} you need to configure client credentials for your client. First you need to choose `Signed JWT` as the method of authenticating your client in the tab `Credentials` in administration console. Then you can choose to either: -** Configure the JWKS URL where {{book.project.name}} can download the client's public keys. This can be a URL such as \http://myhost.com/myapp/k_jwks (see details above). This option is the most flexible, since the client can rotate its keys anytime and {{book.project.name}} then always downloads new keys when needed without needing to change the configuration. More accurately, {{book.project.name}} downloads new keys when it sees the token signed by an unknown `kid` (Key ID). +** Configure the JWKS URL where {project_name} can download the client's public keys. This can be a URL such as \http://myhost.com/myapp/k_jwks (see details above). This option is the most flexible, since the client can rotate its keys anytime and {project_name} then always downloads new keys when needed without needing to change the configuration. More accurately, {project_name} downloads new keys when it sees the token signed by an unknown `kid` (Key ID). ** Upload the client's public key or certificate, either in PEM format, in JWK format, or from the keystore. With this option, the public key is hardcoded and must be changed when the client generates a new key pair. -You can even generate your own keystore from the {{book.project.name}} admininstration console if you don't have your own available. -For more details on how to set up the {{book.project.name}} administration console see {{book.adminguide.link}}[{{book.adminguide.name}}]. +You can even generate your own keystore from the {project_name} admininstration console if you don't have your own available. +For more details on how to set up the {project_name} administration console see {adminguide_link}[{adminguide_name}]. For set up on the adapter side you need to have something like this in your `keycloak.json` file: @@ -53,13 +53,13 @@ For set up on the adapter side you need to have something like this in your `key With this configuration, the keystore file `keystore-client.jks` must be available on classpath in your WAR. If you do not use the prefix `classpath:` you can point to any file on the file system where the client application is running. -{% if book.community %} +ifeval::[{project_community}==true] For inspiration, you can take a look at the examples distribution into the main demo example into the `product-portal` application. ===== Add Your Own Client Authentication Method -You can add your own client authentication method as well. You will need to implement both client-side and server-side providers. For more details see the `Authentication SPI` section in link:{{book.developerguide.link}}[{{book.developerguide.name}}]. -{% endif %} +You can add your own client authentication method as well. You will need to implement both client-side and server-side providers. For more details see the `Authentication SPI` section in link:{developerguide_link}[{developerguide_name}]. +endif::[] diff --git a/securing_apps/topics/oidc/java/fuse-adapter.adoc b/securing_apps/topics/oidc/java/fuse-adapter.adoc old mode 100755 new mode 100644 index f2027a43ce1..41ab4de9cf7 --- a/securing_apps/topics/oidc/java/fuse-adapter.adoc +++ b/securing_apps/topics/oidc/java/fuse-adapter.adoc @@ -2,14 +2,14 @@ [[_fuse_adapter]] ==== JBoss Fuse Adapter -Currently {{book.project.name}} supports securing your web applications running inside http://developers.redhat.com/products/fuse/overview/[JBoss Fuse]. +Currently {project_name} supports securing your web applications running inside http://developers.redhat.com/products/fuse/overview/[JBoss Fuse]. -{% if book.community %} -It leverages <> as {{book.fuseVersion}} is bundled with http://eclipse.org/jetty/[Jetty 9.2 server] +ifeval::[{project_community}==true] +It leverages <<_jetty9_adapter,Jetty 9 adapter>> as {fuseVersion} is bundled with http://eclipse.org/jetty/[Jetty 9.2 server] under the covers and Jetty is used for running various kinds of web applications. -{% endif %} +endif::[] -WARNING: The only supported version of Fuse is {{book.fuseVersion}}. If you use earlier versions of Fuse, it is possible that some functions will not work correctly. In particular, the http://hawt.io[Hawtio] integration will not work with earlier versions of Fuse. +WARNING: The only supported version of Fuse is {fuseVersion}. If you use earlier versions of Fuse, it is possible that some functions will not work correctly. In particular, the http://hawt.io[Hawtio] integration will not work with earlier versions of Fuse. Security for the following items is supported for Fuse: @@ -23,10 +23,10 @@ Security for the following items is supported for Fuse: ===== Securing Your Web Applications Inside Fuse -You must first install the {{book.project.name}} Karaf feature. Next you will need to perform the steps according to the type of application you want to secure. -All referenced web applications require injecting the {{book.project.name}} Jetty authenticator into the underlying Jetty server. The steps to achieve this depend on the application type. The details are described below. +You must first install the {project_name} Karaf feature. Next you will need to perform the steps according to the type of application you want to secure. +All referenced web applications require injecting the {project_name} Jetty authenticator into the underlying Jetty server. The steps to achieve this depend on the application type. The details are described below. -{% if book.community %} -The best place to start is look at Fuse demo bundled as part of {{book.project.name}} examples in directory `fuse` . Most of the steps should be understandable from testing and +ifeval::[{project_community}==true] +The best place to start is look at Fuse demo bundled as part of {project_name} examples in directory `fuse` . Most of the steps should be understandable from testing and understanding the demo. -{% endif %} \ No newline at end of file +endif::[] \ No newline at end of file diff --git a/securing_apps/topics/oidc/java/fuse/camel.adoc b/securing_apps/topics/oidc/java/fuse/camel.adoc index 0b527190ba1..ac68c095d5a 100644 --- a/securing_apps/topics/oidc/java/fuse/camel.adoc +++ b/securing_apps/topics/oidc/java/fuse/camel.adoc @@ -2,7 +2,7 @@ ===== Securing an Apache Camel Application -You can secure Apache camel endpoints implemented with the http://camel.apache.org/jetty.html[camel-jetty] component by adding securityHandler with `KeycloakJettyAuthenticator` and the proper security constraints injected. You can add the `OSGI-INF/blueprint/blueprint.xml` file to your camel application with a similar configuration as below. The roles, security constraint mappings, and {{book.project.name}} adapter configuration might differ slightly depending on your environment and needs. +You can secure Apache camel endpoints implemented with the http://camel.apache.org/jetty.html[camel-jetty] component by adding securityHandler with `KeycloakJettyAuthenticator` and the proper security constraints injected. You can add the `OSGI-INF/blueprint/blueprint.xml` file to your camel application with a similar configuration as below. The roles, security constraint mappings, and {project_name} adapter configuration might differ slightly depending on your environment and needs. For example: @@ -87,7 +87,7 @@ org.apache.camel;version="[2.13,3)", org.eclipse.jetty.security;version="[8,10)", org.eclipse.jetty.server.nio;version="[8,10)", org.eclipse.jetty.util.security;version="[8,10)", -org.keycloak.*;version="{{book.project.versionMvn}}", +org.keycloak.*;version="{project_versionMvn}", org.osgi.service.blueprint, org.osgi.service.blueprint.container, org.osgi.service.event, @@ -95,7 +95,7 @@ org.osgi.service.event, ===== Camel RestDSL -Camel RestDSL is a Camel feature used to define your REST endpoints in a fluent way. But you must still use specific implementation classes and provide instructions on how to integrate with {{book.project.name}}. +Camel RestDSL is a Camel feature used to define your REST endpoints in a fluent way. But you must still use specific implementation classes and provide instructions on how to integrate with {project_name}. The way to configure the integration mechanism depends on the Camel component for which you configure your RestDSL-defined routes. diff --git a/securing_apps/topics/oidc/java/fuse/classic-war.adoc b/securing_apps/topics/oidc/java/fuse/classic-war.adoc index c35860e5678..0a9acb9941d 100644 --- a/securing_apps/topics/oidc/java/fuse/classic-war.adoc +++ b/securing_apps/topics/oidc/java/fuse/classic-war.adoc @@ -68,7 +68,7 @@ For example: ---- -. Within the `/WEB-INF/` directory of your WAR, create a new file, keycloak.json. The format of this configuration file is described in the <> section. It is also possible to make this file available externally as described in xref:config_external_adapter[Configuring the External Adapter]. +. Within the `/WEB-INF/` directory of your WAR, create a new file, keycloak.json. The format of this configuration file is described in the <<_java_adapter_config,Java Adapters Config>> section. It is also possible to make this file available externally as described in xref:config_external_adapter[Configuring the External Adapter]. . Ensure your WAR application imports `org.keycloak.adapters.jetty` and maybe some more packages in the `META-INF/MANIFEST.MF` file, under the `Import-Package` header. Using `maven-bundle-plugin` in your project properly generates OSGI headers in manifest. Note that "*" resolution for the package does not import the `org.keycloak.adapters.jetty` package, since it is not used by the application or the Blueprint or Spring descriptor, but is rather used in the `jetty-web.xml` file. @@ -77,11 +77,11 @@ The list of the packages to import might look like this: + [source, subs="attributes"] ---- -org.keycloak.adapters.jetty;version="{{book.project.versionMvn}}", -org.keycloak.adapters;version="{{book.project.versionMvn}}", -org.keycloak.constants;version="{{book.project.versionMvn}}", -org.keycloak.util;version="{{book.project.versionMvn}}", -org.keycloak.*;version="{{book.project.versionMvn}}", +org.keycloak.adapters.jetty;version="{project_versionMvn}", +org.keycloak.adapters;version="{project_versionMvn}", +org.keycloak.constants;version="{project_versionMvn}", +org.keycloak.util;version="{project_versionMvn}", +org.keycloak.*;version="{project_versionMvn}", *;resolution:=optional ---- diff --git a/securing_apps/topics/oidc/java/fuse/cxf-builtin.adoc b/securing_apps/topics/oidc/java/fuse/cxf-builtin.adoc index ccccfca253c..f7660cea24e 100644 --- a/securing_apps/topics/oidc/java/fuse/cxf-builtin.adoc +++ b/securing_apps/topics/oidc/java/fuse/cxf-builtin.adoc @@ -2,7 +2,7 @@ [[_fuse_adapter_cxf_builtin]] ===== Securing an Apache CXF Endpoint on the Default Jetty Engine -Some services automatically come with deployed servlets on startup. One such service is the CXF servlet running in the $$http://localhost:8181/cxf$$ context. Securing such endpoints can be complicated. One approach, which {{book.project.name}} is currently using, is ServletReregistrationService, which undeploys a built-in servlet at startup, enabling you to redeploy it on a context secured by {{book.project.name}}. +Some services automatically come with deployed servlets on startup. One such service is the CXF servlet running in the $$http://localhost:8181/cxf$$ context. Securing such endpoints can be complicated. One approach, which {project_name} is currently using, is ServletReregistrationService, which undeploys a built-in servlet at startup, enabling you to redeploy it on a context secured by {project_name}. The configuration file `OSGI-INF/blueprint/blueprint.xml` inside your application might resemble the one below. Note that it adds the JAX-RS `customerservice` endpoint, which is endpoint-specific to your application, but more importantly, secures the entire `/cxf` context. @@ -70,10 +70,10 @@ The configuration file `OSGI-INF/blueprint/blueprint.xml` inside your applicatio ---- -As a result, all other CXF services running on the default CXF HTTP destination are also secured. Similarly, when the application is undeployed, the entire `/cxf` context becomes unsecured as well. For this reason, using your own Jetty engine for your applications as described in <> then gives you more +As a result, all other CXF services running on the default CXF HTTP destination are also secured. Similarly, when the application is undeployed, the entire `/cxf` context becomes unsecured as well. For this reason, using your own Jetty engine for your applications as described in <<_fuse_adapter_cxf_separate,Secure CXF Application on separate Jetty Engine>> then gives you more control over security for each individual application. -* The `WEB-INF` directory might need to be inside your project (even if your project is not a web application). You might also need to edit the `/WEB-INF/jetty-web.xml` and `/WEB-INF/keycloak.json` files in a similar way as in <>. +* The `WEB-INF` directory might need to be inside your project (even if your project is not a web application). You might also need to edit the `/WEB-INF/jetty-web.xml` and `/WEB-INF/keycloak.json` files in a similar way as in <<_fuse_adapter_classic_war,Classic WAR application>>. Note that you do not need the `web.xml` file as the security constraints are declared in the blueprint configuration file. * The `Import-Package` in `META-INF/MANIFEST.MF` must contain these imports: @@ -87,8 +87,8 @@ org.apache.cxf.*;version="[2.7,3.2)", com.fasterxml.jackson.jaxrs.json;version="[2.5,3)", org.eclipse.jetty.security;version="[8,10)", org.eclipse.jetty.util.security;version="[8,10)", -org.keycloak.*;version="{{book.project.versionMvn}}", -org.keycloak.adapters.jetty;version="{{book.project.versionMvn}}", +org.keycloak.*;version="{project_versionMvn}", +org.keycloak.adapters.jetty;version="{project_versionMvn}", *;resolution:=optional ---- diff --git a/securing_apps/topics/oidc/java/fuse/cxf-separate.adoc b/securing_apps/topics/oidc/java/fuse/cxf-separate.adoc index 18047e7976b..19bc84e5ccc 100644 --- a/securing_apps/topics/oidc/java/fuse/cxf-separate.adoc +++ b/securing_apps/topics/oidc/java/fuse/cxf-separate.adoc @@ -2,7 +2,7 @@ [[_fuse_adapter_cxf_separate]] ===== Securing an Apache CXF Endpoint on a Separate Jetty Engine -To run your CXF endpoints secured by {{book.project.name}} on separate Jetty engines, complete the following steps: +To run your CXF endpoints secured by {project_name} on separate Jetty engines, complete the following steps: . Add `META-INF/spring/beans.xml` to your application, and in it, declare `httpj:engine-factory` with Jetty SecurityHandler with injected `KeycloakJettyAuthenticator`. The configuration for a CFX JAX-wS application might resemble this one: + @@ -106,5 +106,5 @@ org.apache.cxf.*;version="[2.7,3.2)", org.springframework.beans.factory.config, org.eclipse.jetty.security;version="[8,10)", org.eclipse.jetty.util.security;version="[8,10)", -org.keycloak.*;version="{{book.project.versionMvn}}" +org.keycloak.*;version="{project_versionMvn}" ---- \ No newline at end of file diff --git a/securing_apps/topics/oidc/java/fuse/fuse-admin.adoc b/securing_apps/topics/oidc/java/fuse/fuse-admin.adoc index 8b6ec810ba8..84f2cb77766 100644 --- a/securing_apps/topics/oidc/java/fuse/fuse-admin.adoc +++ b/securing_apps/topics/oidc/java/fuse/fuse-admin.adoc @@ -4,13 +4,13 @@ ====== Using SSH Authentication to Fuse Terminal -{{book.project.name}} mainly addresses use cases for authentication of web applications; however, if your other web services and applications are protected -with {{book.project.name}}, protecting non-web administration services such as SSH with {{book.project.name}} credentials is a best pracrice. You can do this using the JAAS login module, which allows remote connection to {{book.project.name}} and verifies credentials based on -<>. +{project_name} mainly addresses use cases for authentication of web applications; however, if your other web services and applications are protected +with {project_name}, protecting non-web administration services such as SSH with {project_name} credentials is a best pracrice. You can do this using the JAAS login module, which allows remote connection to {project_name} and verifies credentials based on +<<_resource_owner_password_credentials_flow,Resource Owner Password Credentials>>. To enable SSH authentication, complete the following steps: -. In {{book.project.name}} create a client (for example, `ssh-jmx-admin-client`), which will be used for SSH authentication. +. In {project_name} create a client (for example, `ssh-jmx-admin-client`), which will be used for SSH authentication. This client needs to have `Direct Access Grants Enabled` selected to `On`. . In the `$FUSE_HOME/etc/org.apache.karaf.shell.cfg` file, update or specify this property: @@ -20,7 +20,7 @@ This client needs to have `Direct Access Grants Enabled` selected to `On`. sshRealm=keycloak ---- -. Add the `$FUSE_HOME/etc/keycloak-direct-access.json` file with content similar to the following (based on your environment and {{book.project.name}} client settings): +. Add the `$FUSE_HOME/etc/keycloak-direct-access.json` file with content similar to the following (based on your environment and {project_name} client settings): + [source,json] ---- @@ -42,7 +42,7 @@ Use these commands in the Fuse terminal: + [source, subs="attributes"] ---- -features:addurl mvn:org.keycloak/keycloak-osgi-features/{{book.project.versionMvn}}/xml/features +features:addurl mvn:org.keycloak/keycloak-osgi-features/{project_versionMvn}/xml/features features:install keycloak-jaas ---- @@ -54,13 +54,13 @@ ssh -o PubkeyAuthentication=no -p 8101 admin@localhost . Log in with password `password`. -NOTE: On some later operating systems, you might also need to use the SSH command's -o option `-o HostKeyAlgorithms=+ssh-dss` because later SSH clients do not allow use of the `ssh-dss` algorithm, by default. However, by default, it is currently used in {{book.fuseVersion}}. +NOTE: On some later operating systems, you might also need to use the SSH command's -o option `-o HostKeyAlgorithms=+ssh-dss` because later SSH clients do not allow use of the `ssh-dss` algorithm, by default. However, by default, it is currently used in {fuseVersion}. Note that the user needs to have realm role `admin` to perform all operations or another role to perform a subset of operations (for example, the *viewer* role that restricts the user to run only read-only Karaf commands). The available roles are configured in `$FUSE_HOME/etc/org.apache.karaf.shell.cfg` or `$FUSE_HOME/etc/system.properties`. ====== Using JMX Authentication -JMX authentication might be necessary if you want to use jconsole or another external tool to remotely connect to JMX through RMI. Otherwise it might be better to use hawt.io/jolokia, since the jolokia agent is installed in hawt.io by default. For more details see <>. +JMX authentication might be necessary if you want to use jconsole or another external tool to remotely connect to JMX through RMI. Otherwise it might be better to use hawt.io/jolokia, since the jolokia agent is installed in hawt.io by default. For more details see <<_hawtio,Hawtio Admin Console>>. To use JMX authentication, complete the following steps: diff --git a/securing_apps/topics/oidc/java/fuse/hawtio.adoc b/securing_apps/topics/oidc/java/fuse/hawtio.adoc index 6c0779599a5..1775804c616 100644 --- a/securing_apps/topics/oidc/java/fuse/hawtio.adoc +++ b/securing_apps/topics/oidc/java/fuse/hawtio.adoc @@ -2,7 +2,7 @@ [[_hawtio]] ===== Securing the Hawtio Administration Console -To secure the Hawtio Administration Console with {{book.project.name}}, complete the following steps: +To secure the Hawtio Administration Console with {project_name}, complete the following steps: . Add these properties to the `$FUSE_HOME/etc/system.properties` file: + @@ -14,9 +14,9 @@ hawtio.keycloakClientConfig=${karaf.base}/etc/keycloak-hawtio-client.json hawtio.rolePrincipalClasses=org.keycloak.adapters.jaas.RolePrincipal,org.apache.karaf.jaas.boot.principal.RolePrincipal ---- -. Create a client in the {{book.project.name}} administration console in your realm. For example, in the {{book.project.name}} `demo` realm, create a client `hawtio-client`, specify `public` as the Access Type, and specify a redirect URI pointing to Hawtio: \http://localhost:8181/hawtio/*. You must also have a corresponding Web Origin configured (in this case, \http://localhost:8181). +. Create a client in the {project_name} administration console in your realm. For example, in the {project_name} `demo` realm, create a client `hawtio-client`, specify `public` as the Access Type, and specify a redirect URI pointing to Hawtio: \http://localhost:8181/hawtio/*. You must also have a corresponding Web Origin configured (in this case, \http://localhost:8181). -. Create the `keycloak-hawtio-client.json` file in the `$FUSE_HOME/etc` directory using content similar to that shown in the example below. Change the `realm`, `resource`, and `auth-server-url` properties according to your {{book.project.name}} environment. The `resource` property must point to the client created in the previous step. This file is used by the client (Hawtio Javascript application) side. +. Create the `keycloak-hawtio-client.json` file in the `$FUSE_HOME/etc` directory using content similar to that shown in the example below. Change the `realm`, `resource`, and `auth-server-url` properties according to your {project_name} environment. The `resource` property must point to the client created in the previous step. This file is used by the client (Hawtio Javascript application) side. + [source,json] ---- @@ -29,7 +29,7 @@ hawtio.rolePrincipalClasses=org.keycloak.adapters.jaas.RolePrincipal,org.apache. } ---- -. Create the `keycloak-hawtio.json` file in the `$FUSE_HOME/etc` dicrectory using content similar to that shown in the example below. Change the `realm` and `auth-server-url` properties according to your {{book.project.name}} environment. This file is used by the adapters on the server (JAAS Login module) side. +. Create the `keycloak-hawtio.json` file in the `$FUSE_HOME/etc` dicrectory using content similar to that shown in the example below. Change the `realm` and `auth-server-url` properties according to your {project_name} environment. This file is used by the adapters on the server (JAAS Login module) side. + [source,json] ---- @@ -44,32 +44,32 @@ hawtio.rolePrincipalClasses=org.keycloak.adapters.jaas.RolePrincipal,org.apache. } ---- -. Start {{book.fuseVersion}} and install the keycloak feature if you have not already done so. The commands in Karaf terminal are similar to this example: +. Start {fuseVersion} and install the keycloak feature if you have not already done so. The commands in Karaf terminal are similar to this example: + [source, subs="attributes"] ---- -features:addurl mvn:org.keycloak/keycloak-osgi-features/{{book.project.versionMvn}}/xml/features +features:addurl mvn:org.keycloak/keycloak-osgi-features/{project_versionMvn}/xml/features features:install keycloak ---- -. Go to http://localhost:8181/hawtio and log in as a user from your {{book.project.name}} realm. +. Go to http://localhost:8181/hawtio and log in as a user from your {project_name} realm. + Note that the user needs to have the proper realm role to successfully authenticate to Hawtio. The available roles are configured in the `$FUSE_HOME/etc/system.properties` file in `hawtio.roles`. -====== Securing Hawtio on {{book.hawtioEAPVersion}} +====== Securing Hawtio on {hawtioEAPVersion} -To run Hawtio on the {{book.hawtioEAPVersion}} server, complete the following steps: +To run Hawtio on the {hawtioEAPVersion} server, complete the following steps: -. Set up {{book.project.name}} as described in the previous section, Securing the Hawtio Administration Console. It is assumed that: -* you have a {{book.project.name}} realm `demo` and client `hawtio-client` -* your {{book.project.name}} is running on `localhost:8080` -* the {{book.hawtioEAPVersion}} server with deployed Hawtio will be running on `localhost:8181`. The directory with this server is referred in next steps as `$EAP_HOME`. +. Set up {project_name} as described in the previous section, Securing the Hawtio Administration Console. It is assumed that: +* you have a {project_name} realm `demo` and client `hawtio-client` +* your {project_name} is running on `localhost:8080` +* the {hawtioEAPVersion} server with deployed Hawtio will be running on `localhost:8181`. The directory with this server is referred in next steps as `$EAP_HOME`. -. Copy the `{{book.hawtioWARVersion}}` archive to the `$EAP_HOME/standalone/configuration` directory. For more details about deploying Hawtio see the https://access.redhat.com/documentation/en-us/red_hat_jboss_fuse/6.3/html-single/deploying_into_a_web_server/eapcamelsubsystem#idm140313338064000[Fuse Hawtio documentation]. +. Copy the `{hawtioWARVersion}` archive to the `$EAP_HOME/standalone/configuration` directory. For more details about deploying Hawtio see the https://access.redhat.com/documentation/en-us/red_hat_jboss_fuse/6.3/html-single/deploying_into_a_web_server/eapcamelsubsystem#idm140313338064000[Fuse Hawtio documentation]. . Copy the `keycloak-hawtio.json` and `keycloak-hawtio-client.json` files with the above content to the `$EAP_HOME/standalone/configuration` directory. -. Install the {{book.project.name}} adapter subsystem to your {{book.hawtioEAPVersion}} server as described in the <>. +. Install the {project_name} adapter subsystem to your {hawtioEAPVersion} server as described in the <<_jboss_adapter,JBoss adapter documentation>>. . In the `$EAP_HOME/standalone/configuration/standalone.xml` file configure the system properties as in this example: + @@ -109,11 +109,11 @@ To run Hawtio on the {{book.hawtioEAPVersion}} server, complete the following st [source,xml,options="nowrap",subs="attributes+"] ---- - + ---- -. Restart the {{book.hawtioEAPVersion}} server with Hawtio: +. Restart the {hawtioEAPVersion} server with Hawtio: + [source,xml] ---- @@ -121,5 +121,5 @@ cd $EAP_HOME/bin ./standalone.sh -Djboss.socket.binding.port-offset=101 ---- -. Access Hawtio at http://localhost:8181/hawtio. It is secured by {{book.project.name}}. +. Access Hawtio at http://localhost:8181/hawtio. It is secured by {project_name}. diff --git a/securing_apps/topics/oidc/java/fuse/install-feature.adoc b/securing_apps/topics/oidc/java/fuse/install-feature.adoc index b7bd03b5b94..76ec96aeb9f 100644 --- a/securing_apps/topics/oidc/java/fuse/install-feature.adoc +++ b/securing_apps/topics/oidc/java/fuse/install-feature.adoc @@ -8,11 +8,11 @@ You must first install the `keycloak` feature in the JBoss Fuse environment. The As a prequisite, you must be online and have access to the Maven repository. -{% if book.community %} +ifeval::[{project_community}==true] For community it's sufficient to be online as all the artifacts and 3rd party dependencies should be available in the maven central repository. -{% endif %} -{% if book.product %} -For {{book.project.name}} you first need to configure a proper Maven repository, so you can install the artifacts. For more information see the +endif::[] +ifeval::[{project_product}==true] +For {project_name} you first need to configure a proper Maven repository, so you can install the artifacts. For more information see the https://access.redhat.com/maven-repository[JBoss Enterprise Maven repository] page. Assuming the Maven repository is https://maven.repository.redhat.com/ga/, add the following to the `$FUSE_HOME/etc/org.ops4j.pax.url.mvn.cfg` file and add the repository to the list of supported repositories. For example: @@ -24,15 +24,15 @@ Assuming the Maven repository is https://maven.repository.redhat.com/ga/, add th http://repo1.maven.org/maven2@id=maven.central.repo, \ ... ---- -{% endif %} +endif::[] To install the keycloak feature using the Maven repository, complete the following steps: -. Start {{book.fuseVersion}}; then in the Karaf terminal type: +. Start {fuseVersion}; then in the Karaf terminal type: + [source,subs="attributes"] ---- -features:addurl mvn:org.keycloak/keycloak-osgi-features/{{book.project.versionMvn}}/xml/features +features:addurl mvn:org.keycloak/keycloak-osgi-features/{project_versionMvn}/xml/features features:install keycloak ---- @@ -43,7 +43,7 @@ features:install keycloak features:install keycloak-jetty9-adapter ---- + -NOTE: If you are using JBoss Fuse 6.2 or later, use `keycloak-jetty8-adapter`. However, upgrading to {{book.fuseVersion}} is recommended. +NOTE: If you are using JBoss Fuse 6.2 or later, use `keycloak-jetty8-adapter`. However, upgrading to {fuseVersion} is recommended. . Ensure that the features were installed: @@ -58,26 +58,26 @@ This is useful if you are offline or do not want to use Maven to obtain the JAR To install the Fuse adapter from the ZIP archive, complete the following steps: -. Download the {{book.project.name}} Fuse adapter ZIP archive. +. Download the {project_name} Fuse adapter ZIP archive. . Unzip it into the root directory of JBoss Fuse. The dependencies are then installed under the `system` directory. You can overwrite all existing jar files. + -Use this for {{book.fuseVersion}}: +Use this for {fuseVersion}: + [source,subs="attributes"] ---- cd /path-to-fuse/jboss-fuse-6.3.0.redhat-254 -{% if book.community %} -unzip -q /path-to-adapter-zip/keycloak-fuse-adapter-{{book.project.versionMvn}}.zip -{% endif %} -{% if book.product %} -unzip -q /path-to-adapter-zip/rh-sso-{{book.project.version}}-fuse-adapter.zip -{% endif %} +ifeval::[{project_community}==true] +unzip -q /path-to-adapter-zip/keycloak-fuse-adapter-{project_versionMvn}.zip +endif::[] +ifeval::[{project_product}==true] +unzip -q /path-to-adapter-zip/rh-sso-{project_version}-fuse-adapter.zip +endif::[] ---- . Start Fuse and run these commands in the fuse/karaf terminal: + [source,subs="attributes"] ---- -features:addurl mvn:org.keycloak/keycloak-osgi-features/{{book.project.versionMvn}}/xml/features +features:addurl mvn:org.keycloak/keycloak-osgi-features/{project_versionMvn}/xml/features features:install keycloak ---- diff --git a/securing_apps/topics/oidc/java/fuse/servlet-whiteboard.adoc b/securing_apps/topics/oidc/java/fuse/servlet-whiteboard.adoc index 924a328294b..863b79a9bc6 100644 --- a/securing_apps/topics/oidc/java/fuse/servlet-whiteboard.adoc +++ b/securing_apps/topics/oidc/java/fuse/servlet-whiteboard.adoc @@ -4,9 +4,9 @@ You can use this method if you have a servlet class inside your OSGI bundled project that is not deployed as a classic WAR application. Fuse uses https://ops4j1.jira.com/wiki/display/ops4j/Pax+Web+Extender+-+Whiteboard[Pax Web Whiteboard Extender] to deploy such servlets as web applications. -To secure your servlet with {{book.project.name}}, complete the following steps: +To secure your servlet with {project_name}, complete the following steps: -. {{book.project.name}} provides PaxWebIntegrationService, which allows injecting jetty-web.xml and configuring security constraints for your application. You need to declare such services in the `OSGI-INF/blueprint/blueprint.xml` file inside your application. Note that your servlet needs to depend on it. +. {project_name} provides PaxWebIntegrationService, which allows injecting jetty-web.xml and configuring security constraints for your application. You need to declare such services in the `OSGI-INF/blueprint/blueprint.xml` file inside your application. Note that your servlet needs to depend on it. An example configuration: + [source,xml] @@ -59,17 +59,17 @@ An example configuration: ---- -* You might need to have the `WEB-INF` directory inside your project (even if your project is not a web application) and create the `/WEB-INF/jetty-web.xml` and `/WEB-INF/keycloak.json` files as in the <> section. +* You might need to have the `WEB-INF` directory inside your project (even if your project is not a web application) and create the `/WEB-INF/jetty-web.xml` and `/WEB-INF/keycloak.json` files as in the <<_fuse_adapter_classic_war,Classic WAR application>> section. Note you don't need the `web.xml` file as the security-constraints are declared in the blueprint configuration file. . The `Import-Package` in `META-INF/MANIFEST.MF` must contain at least these imports: + [source, subs="attributes"] ---- -org.keycloak.adapters.jetty;version="{{book.project.versionMvn}}", -org.keycloak.adapters;version="{{book.project.versionMvn}}", -org.keycloak.constants;version="{{book.project.versionMvn}}", -org.keycloak.util;version="{{book.project.versionMvn}}", -org.keycloak.*;version="{{book.project.versionMvn}}", +org.keycloak.adapters.jetty;version="{project_versionMvn}", +org.keycloak.adapters;version="{project_versionMvn}", +org.keycloak.constants;version="{project_versionMvn}", +org.keycloak.util;version="{project_versionMvn}", +org.keycloak.*;version="{project_versionMvn}", *;resolution:=optional ---- diff --git a/securing_apps/topics/oidc/java/jaas.adoc b/securing_apps/topics/oidc/java/jaas.adoc index 19e21dd1182..7350990385d 100644 --- a/securing_apps/topics/oidc/java/jaas.adoc +++ b/securing_apps/topics/oidc/java/jaas.adoc @@ -3,19 +3,19 @@ It's generally not needed to use JAAS for most of the applications, especially if they are HTTP based, and you should most likely choose one of our other adapters. However, some applications and systems may still rely on pure legacy JAAS solution. -{{book.project.name}} provides two login modules to help in these situations. +{project_name} provides two login modules to help in these situations. The provided login modules are: org.keycloak.adapters.jaas.DirectAccessGrantsLoginModule:: - This login module allows to authenticate with username/password from {{book.project.name}}. - It's using <> flow to validate if the provided - username/password is valid. It's useful for non-web based systems, which need to rely on JAAS and want to use {{book.project.name}}, but can't use the standard browser + This login module allows to authenticate with username/password from {project_name}. + It's using <<_resource_owner_password_credentials_flow,Resource Owner Password Credentials>> flow to validate if the provided + username/password is valid. It's useful for non-web based systems, which need to rely on JAAS and want to use {project_name}, but can't use the standard browser based flows due to their non-web nature. Example of such application could be messaging or SSH. org.keycloak.adapters.jaas.BearerTokenLoginModule:: - This login module allows to authenticate with {{book.project.name}} access token passed to it through CallbackHandler as password. - It may be useful for example in case, when you have {{book.project.name}} access token from standard based authentication flow and your web application then + This login module allows to authenticate with {project_name} access token passed to it through CallbackHandler as password. + It may be useful for example in case, when you have {project_name} access token from standard based authentication flow and your web application then needs to talk to external non-web based system, which rely on JAAS. For example a messaging system. Both modules use the following configuration properties: diff --git a/securing_apps/topics/oidc/java/java-adapter-config.adoc b/securing_apps/topics/oidc/java/java-adapter-config.adoc index 44656f84c19..400583e26cd 100644 --- a/securing_apps/topics/oidc/java/java-adapter-config.adoc +++ b/securing_apps/topics/oidc/java/java-adapter-config.adoc @@ -2,7 +2,7 @@ [[_java_adapter_config]] ==== Java Adapter Config -Each Java adapter supported by {{book.project.name}} can be configured by a simple JSON file. +Each Java adapter supported by {project_name} can be configured by a simple JSON file. This is what one might look like: [source,json] @@ -42,7 +42,7 @@ This is what one might look like: } ---- -You can use `${...}` enclosure for system property replacement. For example `${jboss.server.config.dir}` would be replaced by `/path/to/{{book.project.name}}`. +You can use `${...}` enclosure for system property replacement. For example `${jboss.server.config.dir}` would be replaced by `/path/to/{project_name}`. Replacement of environment variables is also supported via the `env` prefix, e.g. `${env.MY_ENVIRONMENT_VARIABLE}`. The initial config file can be obtained from the the admin console. This can be done by opening the admin console, select `Clients` from the menu and clicking @@ -60,16 +60,16 @@ resource:: realm-public-key:: PEM format of the realm public key. You can obtain this from the administration console. - This is _OPTIONAL_ and it's not recommended to set it. If not set, the adapter will download this from {{book.project.name}} and - it will always re-download it when needed (eg. {{book.project.name}} rotate it's keys). However if realm-public-key is set, then adapter - will never download new keys from {{book.project.name}}, so when {{book.project.name}} rotate it's keys, adapter will break. + This is _OPTIONAL_ and it's not recommended to set it. If not set, the adapter will download this from {project_name} and + it will always re-download it when needed (eg. {project_name} rotate it's keys). However if realm-public-key is set, then adapter + will never download new keys from {project_name}, so when {project_name} rotate it's keys, adapter will break. auth-server-url:: - The base URL of the {{book.project.name}} server. All other {{book.project.name}} pages and REST service endpoints are derived from this. It is usually of the form `$$https://host:port/auth$$`. + The base URL of the {project_name} server. All other {project_name} pages and REST service endpoints are derived from this. It is usually of the form `$$https://host:port/auth$$`. This is _REQUIRED._ ssl-required:: - Ensures that all communication to and from the {{book.project.name}} server is over HTTPS. + Ensures that all communication to and from the {project_name} server is over HTTPS. In production this should be set to `all`. This is _OPTIONAL_. The default value is _external_ meaning that HTTPS is required by default for external requests. @@ -81,7 +81,7 @@ use-resource-role-mappings:: The default value is _false_. public-client:: - If set to true, the adapter will not send credentials for the client to {{book.project.name}}. + If set to true, the adapter will not send credentials for the client to {project_name}. This is _OPTIONAL_. The default value is _false_. @@ -140,19 +140,19 @@ credentials:: Currently password and jwt is supported. This is _REQUIRED_ only for clients with 'Confidential' access type. connection-pool-size:: - Adapters will make separate HTTP invocations to the {{book.project.name}} server to turn an access code into an access token. - This config option defines how many connections to the {{book.project.name}} server should be pooled. + Adapters will make separate HTTP invocations to the {project_name} server to turn an access code into an access token. + This config option defines how many connections to the {project_name} server should be pooled. This is _OPTIONAL_. The default value is `20`. disable-trust-manager:: - If the {{book.project.name}} server requires HTTPS and this config option is set to `true` you do not have to specify a truststore. + If the {project_name} server requires HTTPS and this config option is set to `true` you do not have to specify a truststore. This setting should only be used during development and *never* in production as it will disable verification of SSL certificates. This is _OPTIONAL_. The default value is `false`. allow-any-hostname:: - If the {{book.project.name}} server requires HTTPS and this config option is set to `true` the {{book.project.name}} server's certificate is validated via the truststore, + If the {project_name} server requires HTTPS and this config option is set to `true` the {project_name} server's certificate is validated via the truststore, but host name validation is not done. This setting should only be used during development and *never* in production as it will disable verification of SSL certificates. This seting may be useful in test environments This is _OPTIONAL_. @@ -164,11 +164,11 @@ proxy-url:: truststore:: The value is the file path to a keystore file. If you prefix the path with `classpath:`, then the truststore will be obtained from the deployment's classpath instead. - Used for outgoing HTTPS communications to the {{book.project.name}} server. + Used for outgoing HTTPS communications to the {project_name} server. Client making HTTPS requests need a way to verify the host of the server they are talking to. This is what the trustore does. The keystore contains one or more trusted host certificates or certificate authorities. - You can create this truststore by extracting the public certificate of the {{book.project.name}} server's SSL keystore. + You can create this truststore by extracting the public certificate of the {project_name} server's SSL keystore. This is _REQUIRED_ unless `ssl-required` is `none` or `disable-trust-manager` is `true`. truststore-password:: @@ -177,7 +177,7 @@ truststore-password:: client-keystore:: This is the file path to a keystore file. - This keystore contains client certificate for two-way SSL when the adapter makes HTTPS requests to the {{book.project.name}} server. + This keystore contains client certificate for two-way SSL when the adapter makes HTTPS requests to the {project_name} server. This is _OPTIONAL_. client-keystore-password:: @@ -192,20 +192,20 @@ always-refresh-token:: If _true_, the adapter will refresh token in every request. register-node-at-startup:: - If _true_, then adapter will send registration request to {{book.project.name}}. + If _true_, then adapter will send registration request to {project_name}. It's _false_ by default and useful only when application is clustered. - See <> for details + See <<_applicationclustering,Application Clustering>> for details register-node-period:: - Period for re-registration adapter to {{book.project.name}}. + Period for re-registration adapter to {project_name}. Useful when application is clustered. - See <> for details + See <<_applicationclustering,Application Clustering>> for details token-store:: Possible values are _session_ and _cookie_. Default is _session_, which means that adapter stores account info in HTTP Session. Alternative _cookie_ means storage of info in cookie. - See <> for details + See <<_applicationclustering,Application Clustering>> for details principal-attribute:: OpenID Connection ID Token attribute to populate the UserPrincipal name with. @@ -217,20 +217,20 @@ turn-off-change-session-id-on-login:: The default value is _false_. token-minimum-time-to-live:: - Amount of time, in seconds, to preemptively refresh an active access token with the {{book.project.name}} server before it expires. + Amount of time, in seconds, to preemptively refresh an active access token with the {project_name} server before it expires. This is especially useful when the access token is sent to another REST client where it could expire before being evaluated. This value should never exceed the realm's access token lifespan. This is _OPTIONAL_. The default value is `0` seconds, so adapter will refresh access token just if it's expired. min-time-between-jwks-requests:: - Amount of time, in seconds, specifying minimum interval between two requests to {{book.project.name}} to retrieve new public keys. + Amount of time, in seconds, specifying minimum interval between two requests to {project_name} to retrieve new public keys. It is 10 seconds by default. Adapter will always try to download new public key when it recognize token with unknown `kid` . However it won't try it more than once per 10 seconds (by default). This is to avoid DoS when attacker sends lots of tokens with bad `kid` forcing adapter - to send lots of requests to {{book.project.name}}. + to send lots of requests to {project_name}. public-key-cache-ttl:: - Amount of time, in seconds, specifying maximum interval between two requests to {{book.project.name}} to retrieve new public keys. + Amount of time, in seconds, specifying maximum interval between two requests to {project_name} to retrieve new public keys. It is 86400 seconds (1 day) by default. Adapter will always try to download new public key when it recognize token with unknown `kid` . If it recognize token with known `kid`, it will just use the public key downloaded previously. However at least once per this configured interval (1 day by default) will be new diff --git a/securing_apps/topics/oidc/java/java-adapters.adoc b/securing_apps/topics/oidc/java/java-adapters.adoc index 697c559fad2..014f61b04e3 100644 --- a/securing_apps/topics/oidc/java/java-adapters.adoc +++ b/securing_apps/topics/oidc/java/java-adapters.adoc @@ -1,5 +1,5 @@ === Java Adapters -{{book.project.name}} comes with a range of different adapters for Java application. Selecting the correct adapter depends on the target platform. +{project_name} comes with a range of different adapters for Java application. Selecting the correct adapter depends on the target platform. -All Java adapters share a set of common configuration options described in the <> chapter. \ No newline at end of file +All Java adapters share a set of common configuration options described in the <<_java_adapter_config,Java Adapters Config>> chapter. \ No newline at end of file diff --git a/securing_apps/topics/oidc/java/jboss-adapter.adoc b/securing_apps/topics/oidc/java/jboss-adapter.adoc index 355df53f298..3c65d26a887 100644 --- a/securing_apps/topics/oidc/java/jboss-adapter.adoc +++ b/securing_apps/topics/oidc/java/jboss-adapter.adoc @@ -1,24 +1,24 @@ [[_jboss_adapter]] -{% if book.community %} +ifeval::[{project_community}==true] ==== JBoss EAP/Wildfly Adapter -{% endif %} -{% if book.product %} +endif::[] +ifeval::[{project_product}==true] ==== JBoss EAP Adapter -{% endif %} +endif::[] -{% if book.community %} +ifeval::[{project_community}==true] To be able to secure WAR apps deployed on JBoss EAP, WildFly or JBoss AS, you must install and configure the -{{book.project.name}} adapter subsystem. You then have two options to secure your WARs. -{% endif %} -{% if book.product %} +{project_name} adapter subsystem. You then have two options to secure your WARs. +endif::[] +ifeval::[{project_product}==true] To be able to secure WAR apps deployed on JBoss EAP, you must install and configure the -{{book.project.name}} adapter subsystem. You then have two options to secure your WARs. -{% endif %} +{project_name} adapter subsystem. You then have two options to secure your WARs. +endif::[] You can provide an adapter config file in your WAR and change the auth-method to KEYCLOAK within web.xml. -Alternatively, you don't have to modify your WAR at all and you can secure it via the {{book.project.name}} adapter subsystem configuration in `standalone.xml`. +Alternatively, you don't have to modify your WAR at all and you can secure it via the {project_name} adapter subsystem configuration in `standalone.xml`. Both methods are described in this section. [[_jboss_adapter_installation]] @@ -26,13 +26,13 @@ Both methods are described in this section. Adapters are available as a separate archive depending on what server version you are using. -{% if book.community %} +ifeval::[{project_community}==true] Install on Wildfly 9, 10 or 11: [source, subs="attributes"] ---- $ cd $WILDFLY_HOME -$ unzip keycloak-wildfly-adapter-dist-{{book.project.version}}.zip +$ unzip keycloak-wildfly-adapter-dist-{project_version}.zip ---- Install on Wildfly 8: @@ -40,7 +40,7 @@ Install on Wildfly 8: [source, subs="attributes"] ---- $ cd $WILDFLY_HOME -$ unzip keycloak-wf8-adapter-dist-{{book.project.version}}.zip +$ unzip keycloak-wf8-adapter-dist-{project_version}.zip ---- Install on JBoss EAP 7: @@ -48,7 +48,7 @@ Install on JBoss EAP 7: [source, subs="attributes"] ---- $ cd $EAP_HOME -$ unzip keycloak-eap7-adapter-dist-{{book.project.version}}.zip +$ unzip keycloak-eap7-adapter-dist-{project_version}.zip ---- Install on JBoss EAP 6: @@ -56,7 +56,7 @@ Install on JBoss EAP 6: [source, subs="attributes"] ---- $ cd $EAP_HOME -$ unzip keycloak-eap6-adapter-dist-{{book.project.version}}.zip +$ unzip keycloak-eap6-adapter-dist-{project_version}.zip ---- Install on JBoss AS 7.1: @@ -64,17 +64,17 @@ Install on JBoss AS 7.1: [source, subs="attributes"] ---- $ cd $JBOSS_HOME -$ unzip keycloak-as7-adapter-dist-{{book.project.version}}.zip +$ unzip keycloak-as7-adapter-dist-{project_version}.zip ---- -{% endif %} +endif::[] -{% if book.product %} +ifeval::[{project_product}==true] Install on JBoss EAP 7: [source, subs="attributes"] ---- $ cd $EAP_HOME -$ unzip rh-sso-{{book.project.version}}-eap7-adapter.zip +$ unzip rh-sso-{project_version}-eap7-adapter.zip ---- Install on JBoss EAP 6: @@ -82,22 +82,22 @@ Install on JBoss EAP 6: [source, subs="attributes"] ---- $ cd $EAP_HOME -$ unzip rh-sso-{{book.project.version}}-eap6-adapter.zip +$ unzip rh-sso-{project_version}-eap6-adapter.zip ---- -{% endif %} +endif::[] -This ZIP archive contains JBoss Modules specific to the {{book.project.name}} adapter. It also contains JBoss CLI scripts +This ZIP archive contains JBoss Modules specific to the {project_name} adapter. It also contains JBoss CLI scripts to configure the adapter subsystem. To configure the adapter subsystem if the server is not running execute: -{% if book.community %} +ifeval::[{project_community}==true] .Wildfly 11 [source] ---- $ ./bin/jboss-cli.sh --file=adapter-elytron-install-offline.cli ---- -{% endif %} +endif::[] .Any other server but Wildfly 11 [source] @@ -109,13 +109,13 @@ NOTE: The offline script is not available for JBoss EAP 6 Alternatively, if the server is running execute: -{% if book.community %} +ifeval::[{project_community}==true] .Wildfly 11 [source] ---- $ ./bin/jboss-cli.sh --file=adapter-elytron-install.cli ---- -{% endif %} +endif::[] .Any other server but Wildfly 11 [source] @@ -129,7 +129,7 @@ This section describes how to secure a WAR directly by adding configuration and The first thing you must do is create a `keycloak.json` adapter configuration file within the `WEB-INF` directory of your WAR. -The format of this configuration file is described in the <> section. +The format of this configuration file is described in the <<_java_adapter_config,Java adapter configuration>> section. Next you must set the `auth-method` to `KEYCLOAK` in `web.xml`. You also have to use standard servlet security to specify role-base constraints on your URLs. @@ -187,10 +187,10 @@ Here's an example: ===== Securing WARs via Adapter Subsystem -You do not have to modify your WAR to secure it with {{book.project.name}}. Instead you can externally secure it via the {{book.project.name}} Adapter Subsystem. +You do not have to modify your WAR to secure it with {project_name}. Instead you can externally secure it via the {project_name} Adapter Subsystem. While you don't have to specify KEYCLOAK as an `auth-method`, you still have to define the `security-constraints` in `web.xml`. You do not, however, have to create a `WEB-INF/keycloak.json` file. -This metadata is instead defined within server configuration (i.e. `standalone.xml`) in the {{book.project.name}} subsystem definition. +This metadata is instead defined within server configuration (i.e. `standalone.xml`) in the {project_name} subsystem definition. [source,xml] ---- @@ -212,11 +212,11 @@ This metadata is instead defined within server configuration (i.e. `standalone.x ---- The `secure-deployment` `name` attribute identifies the WAR you want to secure. -Its value is the `module-name` defined in `web.xml` with `.war` appended. The rest of the configuration corresponds pretty much one to one with the `keycloak.json` configuration options defined in <>. +Its value is the `module-name` defined in `web.xml` with `.war` appended. The rest of the configuration corresponds pretty much one to one with the `keycloak.json` configuration options defined in <<_java_adapter_config,Java adapter configuration>>. The exception is the `credential` element. -To make it easier for you, you can go to the {{book.project.name}} Administration Console and go to the Client/Installation tab of the application this WAR is aligned with. +To make it easier for you, you can go to the {project_name} Administration Console and go to the Client/Installation tab of the application this WAR is aligned with. It provides an example XML file you can cut and paste. If you have multiple deployments secured by the same realm you can share the realm configuration in a separate element. For example: diff --git a/securing_apps/topics/oidc/java/jetty8-adapter.adoc b/securing_apps/topics/oidc/java/jetty8-adapter.adoc old mode 100755 new mode 100644 index 9aacb754738..cc552719191 --- a/securing_apps/topics/oidc/java/jetty8-adapter.adoc +++ b/securing_apps/topics/oidc/java/jetty8-adapter.adoc @@ -44,4 +44,4 @@ OPTIONS=Server,jsp,jmx,resources,websocket,ext,plus,annotations,keycloak Enabling Keycloak for your WARs is the same as the Jetty 9.x adapter. Our 8.1.x adapter supports both keycloak.json and the jboss-web.xml advanced configuration. -See <> \ No newline at end of file +See <<_jetty9_per_war,Required Per WAR Configuration>> \ No newline at end of file diff --git a/securing_apps/topics/oidc/java/jetty9-adapter.adoc b/securing_apps/topics/oidc/java/jetty9-adapter.adoc old mode 100755 new mode 100644 index 42a0fcc7579..3dbcf335331 --- a/securing_apps/topics/oidc/java/jetty9-adapter.adoc +++ b/securing_apps/topics/oidc/java/jetty9-adapter.adoc @@ -57,7 +57,7 @@ This is a Jetty specific config file and you must define a Keycloak specific aut Next you must create a `keycloak.json` adapter config file within the `WEB-INF` directory of your WAR. -The format of this config file is describe in the <> section. +The format of this config file is describe in the <<_java_adapter_config,Java adapter configuration>> section. WARNING: The Jetty 9.1.x adapter will not be able to find the `keycloak.json` file. You will have to define all adapter settings within the `jetty-web.xml` file as described below. diff --git a/securing_apps/topics/oidc/java/logout.adoc b/securing_apps/topics/oidc/java/logout.adoc old mode 100755 new mode 100644 diff --git a/securing_apps/topics/oidc/java/multi-tenancy.adoc b/securing_apps/topics/oidc/java/multi-tenancy.adoc old mode 100755 new mode 100644 index 120218e5b03..3da625fee69 --- a/securing_apps/topics/oidc/java/multi-tenancy.adoc +++ b/securing_apps/topics/oidc/java/multi-tenancy.adoc @@ -1,15 +1,15 @@ ==== Multi Tenancy -Multi Tenancy, in our context, means that a single target application (WAR) can be secured with multiple {{book.project.name}} realms. The realms can be located -one the same {{book.project.name}} instance or on different instances. +Multi Tenancy, in our context, means that a single target application (WAR) can be secured with multiple {project_name} realms. The realms can be located +one the same {project_name} instance or on different instances. In practice, this means that the application needs to have multiple `keycloak.json` adapter configuration files. You could have multiple instances of your WAR with different adapter configuration files deployed to different context-paths. However, this may be inconvenient and you may also want to select the realm based on something else than context-path. -{{book.project.name}} makes it possible to have a custom config resolver so you can choose what adapter config is used for each request. +{project_name} makes it possible to have a custom config resolver so you can choose what adapter config is used for each request. To achieve this first you need to create an implementation of `org.keycloak.adapters.KeycloakConfigResolver`. For example: diff --git a/securing_apps/topics/oidc/java/params_forwarding.adoc b/securing_apps/topics/oidc/java/params_forwarding.adoc index 665446cc08a..1e8252d08fe 100644 --- a/securing_apps/topics/oidc/java/params_forwarding.adoc +++ b/securing_apps/topics/oidc/java/params_forwarding.adoc @@ -1,10 +1,10 @@ ==== Parameters Forwarding -The {{book.project.name}} initial authorization endpoint request has support for various parameters. Most of the parameters are described in +The {project_name} initial authorization endpoint request has support for various parameters. Most of the parameters are described in http://openid.net/specs/openid-connect-core-1_0.html#AuthorizationEndpoint[OIDC specification]. Some parameters are added automatically by the adapter based on the adapter configuration. However, there are also a few parameters that can be added on a per-invocation basis. When you open the secured application URI, -the particular parameter will be forwarded to the {{book.project.name}} authorization endpoint. +the particular parameter will be forwarded to the {project_name} authorization endpoint. For example, if you request an offline token, then you can open the secured application URI with the `scope` parameter like: @@ -13,7 +13,7 @@ For example, if you request an offline token, then you can open the secured appl http://myappserver/mysecuredapp?scope=offline_access ---- -and the parameter `scope=offline_access` will be automatically forwarded to the {{book.project.name}} authorization endpoint. +and the parameter `scope=offline_access` will be automatically forwarded to the {project_name} authorization endpoint. The supported parameters are: @@ -28,5 +28,5 @@ The supported parameters are: * kc_idp_hint Most of the parameters are described in the http://openid.net/specs/openid-connect-core-1_0.html#AuthorizationEndpoint[OIDC specification]. -The only exception is parameter `kc_idp_hint`, which is specific to {{book.project.name}} and contains the name of the identity provider to automatically use. -For more information see the `Identity Brokering` section in link:{{book.adminguide.link}}[{{book.adminguide.name}}]. +The only exception is parameter `kc_idp_hint`, which is specific to {project_name} and contains the name of the identity provider to automatically use. +For more information see the `Identity Brokering` section in link:{adminguide_link}[{adminguide_name}]. diff --git a/securing_apps/topics/oidc/java/servlet-filter-adapter.adoc b/securing_apps/topics/oidc/java/servlet-filter-adapter.adoc index 9815d546c87..341099fbbb3 100644 --- a/securing_apps/topics/oidc/java/servlet-filter-adapter.adoc +++ b/securing_apps/topics/oidc/java/servlet-filter-adapter.adoc @@ -1,9 +1,9 @@ [[_servlet_filter_adapter]] ==== Java Servlet Filter Adapter -If you are deploying your Java Servlet application on a platform where there is no {{book.project.name}} adapter you opt to use the servlet filter adapter. +If you are deploying your Java Servlet application on a platform where there is no {project_name} adapter you opt to use the servlet filter adapter. This adapter works a bit differently than the other adapters. You do not define security constraints in web.xml. -Instead you define a filter mapping using the {{book.project.name}} servlet filter adapter to secure the url patterns you want to secure. +Instead you define a filter mapping using the {project_name} servlet filter adapter to secure the url patterns you want to secure. WARNING: Backchannel logout works a bit differently than the standard adapters. Instead of invalidating the HTTP session it marks the session id as logged out. @@ -31,7 +31,7 @@ There's no standard way to invalidate an HTTP session based on a session id. ---- In the snippet above there are two url-patterns. - _/protected/*_ are the files we want protected, while the _/keycloak/*_ url-pattern handles callbacks from the {{book.project.name}} server. + _/protected/*_ are the files we want protected, while the _/keycloak/*_ url-pattern handles callbacks from the {project_name} server. If you need to exclude some paths beneath the configured `url-patterns` you can use the Filter init-param `keycloak.config.skipPattern` to configure a regular expression that describes a path-pattern for which the keycloak filter should immediately delegate to the filter-chain. @@ -47,12 +47,12 @@ Patterns are matched against the `requestURI` without the `context-path`. Given ---- -Note that you should configure your client in the {{book.project.name}} Admin Console with an Admin URL that points to a secured section covered by the filter's url-pattern. +Note that you should configure your client in the {project_name} Admin Console with an Admin URL that points to a secured section covered by the filter's url-pattern. The Admin URL will make callbacks to the Admin URL to do things like backchannel logout. So, the Admin URL in this example should be `http[s]://hostname/{context-root}/keycloak`. -The {{book.project.name}} filter has the same configuration parameters as the other adapters except you must define them as filter init params instead of context params. +The {project_name} filter has the same configuration parameters as the other adapters except you must define them as filter init params instead of context params. To use this filter, include this maven artifact in your WAR poms: @@ -61,6 +61,6 @@ To use this filter, include this maven artifact in your WAR poms: org.keycloak keycloak-servlet-filter-adapter - {{book.project.versionMvn}} + {project_versionMvn} ---- diff --git a/securing_apps/topics/oidc/java/spring-boot-adapter.adoc b/securing_apps/topics/oidc/java/spring-boot-adapter.adoc old mode 100755 new mode 100644 index e8895e3fbe9..bf1d81a0a74 --- a/securing_apps/topics/oidc/java/spring-boot-adapter.adoc +++ b/securing_apps/topics/oidc/java/spring-boot-adapter.adoc @@ -34,7 +34,7 @@ Make also sure to add the Adapter BOM dependency : org.keycloak.bom keycloak-adapter-bom - {{book.project.versionMvn}} + {project_versionMvn} pom import diff --git a/securing_apps/topics/oidc/java/spring-security-adapter.adoc b/securing_apps/topics/oidc/java/spring-security-adapter.adoc old mode 100755 new mode 100644 index c21ce6d7565..50031820b76 --- a/securing_apps/topics/oidc/java/spring-security-adapter.adoc +++ b/securing_apps/topics/oidc/java/spring-security-adapter.adoc @@ -17,7 +17,7 @@ Add Keycloak Spring Security adapter as a dependency to your Maven POM or Gradle org.keycloak keycloak-spring-security-adapter - {{book.project.versionMvn}} + {project_versionMvn} ---- @@ -153,7 +153,7 @@ While Spring Security's XML namespace simplifies configuration, customizing the The Keycloak Spring Security adapter also supports multi tenancy. Instead of injecting `AdapterDeploymentContextFactoryBean` with the path to `keycloak.json` you can inject an implementation of the `KeycloakConfigResolver` interface. -More details on how to implement the `KeycloakConfigResolver` can be found in <>. +More details on how to implement the `KeycloakConfigResolver` can be found in <<_multi_tenancy,Multi Tenancy>>. ===== Naming Security Roles diff --git a/securing_apps/topics/oidc/java/tomcat-adapter.adoc b/securing_apps/topics/oidc/java/tomcat-adapter.adoc old mode 100755 new mode 100644 index 4d646ca7bef..6780f91cdd6 --- a/securing_apps/topics/oidc/java/tomcat-adapter.adoc +++ b/securing_apps/topics/oidc/java/tomcat-adapter.adoc @@ -46,7 +46,7 @@ This is a Tomcat specific config file and you must define a Keycloak specific Va Next you must create a `keycloak.json` adapter config file within the `WEB-INF` directory of your WAR. -The format of this config file is describe in the <> +The format of this config file is describe in the <<_java_adapter_config,Java adapter configuration>> Finally you must specify both a `login-config` and use standard servlet security to specify role-base constraints on your URLs. Here's an example: diff --git a/securing_apps/topics/oidc/javascript-adapter.adoc b/securing_apps/topics/oidc/javascript-adapter.adoc index ac682d60937..272aa3320ae 100644 --- a/securing_apps/topics/oidc/javascript-adapter.adoc +++ b/securing_apps/topics/oidc/javascript-adapter.adoc @@ -1,16 +1,16 @@ [[_javascript_adapter]] === Javascript Adapter -{{book.project.name}} comes with a client-side JavaScript library that can be used to secure HTML5/JavaScript applications. The JavaScript adapter has built-in support for Cordova applications. +{project_name} comes with a client-side JavaScript library that can be used to secure HTML5/JavaScript applications. The JavaScript adapter has built-in support for Cordova applications. -The library can be retrieved directly from the {{book.project.name}} server at `/auth/js/keycloak.js` and is also distributed as a ZIP archive. +The library can be retrieved directly from the {project_name} server at `/auth/js/keycloak.js` and is also distributed as a ZIP archive. -A best practice is to load the JavaScript adapter directly from {{book.project.name}} Server as it will automatically be updated when you upgrade the server. If you copy the adapter to your web application instead, make sure you upgrade the adapter only after you have upgraded the server. +A best practice is to load the JavaScript adapter directly from {project_name} Server as it will automatically be updated when you upgrade the server. If you copy the adapter to your web application instead, make sure you upgrade the adapter only after you have upgraded the server. One important thing to note about using client-side applications is that the client has to be a public client as there is no secure way to store client credentials in a client-side application. This makes it very important to make sure the redirect URIs you have configured for the client are correct and as specific as possible. -To use the JavaScript adapter you must first create a client for your application in the {{book.project.name}} Administration Console. Make sure `public` +To use the JavaScript adapter you must first create a client for your application in the {project_name} Administration Console. Make sure `public` is selected for `Access Type`. You also need to configure valid redirect URIs and valid web origins. Be as specific as possible as failing to do so may result in a security vulnerability. @@ -56,7 +56,7 @@ var keycloak = Keycloak({ ---- By default to authenticate you need to call the `login` function. However, there are two options available to make the adapter automatically authenticate. You -can pass `login-required` or `check-sso` to the init function. `login-required` will authenticate the client if the user is logged-in to {{book.project.name}} +can pass `login-required` or `check-sso` to the init function. `login-required` will authenticate the client if the user is logged-in to {project_name} or display the login page if not. `check-sso` will only authenticate the client if the user is already logged-in, if the user is not logged-in the browser will be redirected back to the application and remain unauthenticated. @@ -67,7 +67,7 @@ To enable `login-required` set `onLoad` to `login-required` and pass to the init keycloak.init({ onLoad: 'login-required' }) ---- -After the user is authenticated the application can make requests to RESTful services secured by {{book.project.name}} by including the bearer token in the +After the user is authenticated the application can make requests to RESTful services secured by {project_name} by including the bearer token in the `Authorization` header. For example: [source,javascript] @@ -115,7 +115,7 @@ By default, the JavaScript adapter creates a hidden iframe that is used to detec This does not require any network traffic, instead the status is retrieved by looking at a special status cookie. This feature can be disabled by setting `checkLoginIframe: false` in the options passed to the `init` method. -You should not rely on looking at this cookie directly. It's format can change and it's also associated with the URL of the {{book.project.name}} server, not +You should not rely on looking at this cookie directly. It's format can change and it's also associated with the URL of the {project_name} server, not your application. [[_javascript_implicit_flow]] @@ -123,17 +123,17 @@ your application. By default, the JavaScript adapter uses the http://openid.net/specs/openid-connect-core-1_0.html#CodeFlowAuth[Authorization Code] flow. -With this flow the {{book.project.name}} server returns an authorization code, not an authentication token, to the application. The JavaScript adapter exchanges +With this flow the {project_name} server returns an authorization code, not an authentication token, to the application. The JavaScript adapter exchanges the `code` for an access token and a refresh token after the browser is redirected back to the application. -{{book.project.name}} also supports the http://openid.net/specs/openid-connect-core-1_0.html#ImplicitFlowAuth[Implicit] flow where an access token -is sent immediately after successful authentication with {{book.project.name}}. This may have better performance than standard flow, as there is no additional +{project_name} also supports the http://openid.net/specs/openid-connect-core-1_0.html#ImplicitFlowAuth[Implicit] flow where an access token +is sent immediately after successful authentication with {project_name}. This may have better performance than standard flow, as there is no additional request to exchange the code for tokens, but it has implications when the access token expires. However, sending the access token in the URL fragment can be a security vulnerability. For example the token could be leaked through web server logs and or browser history. -To enable implicit flow, you need to enable the `Implicit Flow Enabled` flag for the client in the {{book.project.name}} Administration Console. +To enable implicit flow, you need to enable the `Implicit Flow Enabled` flag for the client in the {project_name} Administration Console. You also need to pass the parameter `flow` with value `implicit` to `init` method: [source,javascript] @@ -142,12 +142,12 @@ keycloak.init({ flow: 'implicit' }) ---- One thing to note is that only an access token is provided and there is no refresh token. This means that once the access token has expired the application -has to do the redirect to the {{book.project.name}} again to obtain a new access token. +has to do the redirect to the {project_name} again to obtain a new access token. -{{book.project.name}} also supports the http://openid.net/specs/openid-connect-core-1_0.html#HybridFlowAuth[Hybrid] flow. +{project_name} also supports the http://openid.net/specs/openid-connect-core-1_0.html#HybridFlowAuth[Hybrid] flow. This requires the client to have both the `Standard Flow Enabled` and `Implicit Flow Enabled` flags enabled in the admin console. -The {{book.project.name}} server will then send both the code and tokens to your application. +The {project_name} server will then send both the code and tokens to your application. The access token can be used immediately while the code can be exchanged for access and refresh tokens. Similar to the implicit flow, the hybrid flow is good for performance because the access token is available immediately. But, the token is still sent in the URL, and the security vulnerability mentioned earlier may still apply. @@ -215,7 +215,7 @@ refreshTokenParsed:: The parsed refresh token as a JavaScript object. timeSkew:: - The estimated time difference between the browser time and the {{book.project.name}} server in seconds. This value is just an estimation, but is accurate + The estimated time difference between the browser time and the {project_name} server in seconds. This value is just an estimation, but is accurate enough when determining if a token is expired or not. responseMode:: @@ -225,7 +225,7 @@ flow:: Flow passed in init. responseType:: - Response type sent to {{book.project.name}} with login requests. This is determined based on the flow value used during initialization, but can be overridden by setting this value. + Response type sent to {project_name} with login requests. This is determined based on the flow value used during initialization, but can be overridden by setting this value. ===== Methods @@ -239,10 +239,10 @@ Options is an Object, where: * token - Set an initial value for the token. * refreshToken - Set an initial value for the refresh token. * idToken - Set an initial value for the id token (only together with token or refreshToken). -* timeSkew - Set an initial value for skew between local time and {{book.project.name}} server in seconds (only together with token or refreshToken). +* timeSkew - Set an initial value for skew between local time and {project_name} server in seconds (only together with token or refreshToken). * checkLoginIframe - Set to enable/disable monitoring login state (default is true). * checkLoginIframeInterval - Set the interval to check login state (default is 5 seconds). -* responseMode - Set the OpenID Connect response mode send to {{book.project.name}} server at login request. Valid values are query or fragment . Default value is fragment, which means that after successful authentication will {{book.project.name}} redirect to javascript application with OpenID Connect parameters added in URL fragment. This is generally safer and recommended over query. +* responseMode - Set the OpenID Connect response mode send to {project_name} server at login request. Valid values are query or fragment . Default value is fragment, which means that after successful authentication will {project_name} redirect to javascript application with OpenID Connect parameters added in URL fragment. This is generally safer and recommended over query. * flow - Set the OpenID Connect flow. Valid values are standard, implicit or hybrid. Returns promise to set functions to be invoked on success or error. @@ -254,7 +254,7 @@ Redirects to login form on (options is an optional object with redirectUri and/o Options is an Object, where: * redirectUri - Specifies the uri to redirect to after login. -* prompt - By default the login screen is displayed if the user is not logged-in to {{book.project.name}}. To only authenticate to the application if the user is already logged-in and not display the login page if the user is not logged-in, set this option to `none`. To always require re-authentication and ignore SSO, set this option to `login` . +* prompt - By default the login screen is displayed if the user is not logged-in to {project_name}. To only authenticate to the application if the user is already logged-in and not display the login page if the user is not logged-in, set this option to `none`. To always require re-authentication and ignore SSO, set this option to `login` . * maxAge - Used just if user is already authenticated. Specifies maximum time since the authentication of user happened. If user is already authenticated for longer time than `maxAge`, the SSO is ignored and he will need to re-authenticate again. * loginHint - Used to pre-fill the username/email field on the login form. * action - If value is 'register' then user is redirected to registration page, otherwise to login page. diff --git a/securing_apps/topics/oidc/nodejs-adapter.adoc b/securing_apps/topics/oidc/nodejs-adapter.adoc index 4021f2dfa89..bb4a4832e95 100644 --- a/securing_apps/topics/oidc/nodejs-adapter.adoc +++ b/securing_apps/topics/oidc/nodejs-adapter.adoc @@ -1,16 +1,16 @@ [[_nodejs_adapter]] === Node.js Adapter -{{book.project.name}} provides a Node.js adapter built on top of https://github.com/senchalabs/connect[Connect] to protect server-side JavaScript apps — the goal was to be flexible enough to integrate with frameworks like https://expressjs.com/[Express.js]. +{project_name} provides a Node.js adapter built on top of https://github.com/senchalabs/connect[Connect] to protect server-side JavaScript apps — the goal was to be flexible enough to integrate with frameworks like https://expressjs.com/[Express.js]. -{% if book.community %} -The library can be downloaded directly from https://www.npmjs.com/package/keycloak-connect[ {{book.project.name}} organization] and the source is available at +ifeval::[{project_community}==true] +The library can be downloaded directly from https://www.npmjs.com/package/keycloak-connect[ {project_name} organization] and the source is available at https://github.com/keycloak/keycloak-nodejs-connect[GitHub]. -{% endif %} +endif::[] -To use the Node.js adapter, first you must create a client for your application in the {{book.project.name}} Administration Console. The adapter supports public, confidential, and bearer-only access type. Which one to choose depends on the use-case scenario. +To use the Node.js adapter, first you must create a client for your application in the {project_name} Administration Console. The adapter supports public, confidential, and bearer-only access type. Which one to choose depends on the use-case scenario. -Once the client is created click the `Installation` tab, select `{{book.project.name}} OIDC JSON` for `Format Option`, and then click `Download`. The downloaded `keycloak.json` file should be at the root folder of your project. +Once the client is created click the `Installation` tab, select `{project_name} OIDC JSON` for `Format Option`, and then click `Download`. The downloaded `keycloak.json` file should be at the root folder of your project. ==== Installation @@ -18,29 +18,29 @@ Assuming you've already installed https://nodejs.org[Node.js], create a folder f mkdir myapp && cd myapp -Use `npm init` command to create a `package.json` for your application. Now add the {{book.project.name}} connect adapter in the dependencies list: +Use `npm init` command to create a `package.json` for your application. Now add the {project_name} connect adapter in the dependencies list: -{% if book.community %} +ifeval::[{project_community}==true] [source,json,subs="attributes"] ---- "dependencies": { - "keycloak-connect": "{{book.project.versionNpm}}" + "keycloak-connect": "{project_versionNpm}" } ---- -{% endif %} +endif::[] -{% if book.product %} +ifeval::[{project_product}==true] [source,json,subs="attributes"] ---- "dependencies": { - "keycloak-connect": "file:keycloak-connect-{{book.project.versionNpm}}.tgz" + "keycloak-connect": "file:keycloak-connect-{project_versionNpm}.tgz" } ---- -{% endif %} +endif::[] ==== Usage Instantiate a Keycloak class:: @@ -61,7 +61,7 @@ involves no arguments. By default, this will locate a file named `keycloak.json` alongside the main executable of your application to initialize keycloak-specific settings (public key, realm name, various URLs). The `keycloak.json` file -is obtained from the {{book.project.name}} Admin Console. +is obtained from the {project_name} Admin Console. Instantiation with this method results in all of the reasonable defaults being used. As alternative, it's also possible to provide a configuration @@ -96,7 +96,7 @@ session store that `express-session` is using. ---- Passing a custom scope value:: -By default, the scope value `openid` is passed as a query parameter to {{book.project.name}}'s login URL, but you can add an additional custom value: +By default, the scope value `openid` is passed as a query parameter to {project_name}'s login URL, but you can add an additional custom value: [source,javascript] var keycloak = new Keycloak({ scope: 'offline_access' }); @@ -161,14 +161,14 @@ for each section: Explicit user-triggered logout:: By default, the middleware catches calls to `/logout` to send the user through a -{{book.project.name}}-centric logout workflow. This can be changed by specifying a `logout` +{project_name}-centric logout workflow. This can be changed by specifying a `logout` configuration parameter to the `middleware()` call: [source,javascript] app.use( keycloak.middleware( { logout: '/logoff' } )); -{{book.project.name}} Admin Callbacks:: +{project_name} Admin Callbacks:: -Also, the middleware supports callbacks from the {{book.project.name}} console to log out a single +Also, the middleware supports callbacks from the {project_name} console to log out a single session or all sessions. By default, these type of admin callbacks occur relative to the root URL of `/` but can be changed by providing an `admin` parameter to the `middleware()` call: diff --git a/securing_apps/topics/oidc/oidc-generic.adoc b/securing_apps/topics/oidc/oidc-generic.adoc index d40188449d5..a78e471fe66 100644 --- a/securing_apps/topics/oidc/oidc-generic.adoc +++ b/securing_apps/topics/oidc/oidc-generic.adoc @@ -1,16 +1,16 @@ === Other OpenID Connect Libraries -{{book.project.name}} can be secured by supplied adapters that are usually easier to use and provide better integration with {{book.project.name}}. However, if an adapter is not available for your programming language, framework, or platform you might opt to use a generic OpenID Connect Resource Provider (RP) library instead. This chapter describes details specific to {{book.project.name}} and does not contain specific protocol details. For more information see the http://openid.net/connect/[OpenID Connect specifications] and https://tools.ietf.org/html/rfc6749[OAuth2 specification]. +{project_name} can be secured by supplied adapters that are usually easier to use and provide better integration with {project_name}. However, if an adapter is not available for your programming language, framework, or platform you might opt to use a generic OpenID Connect Resource Provider (RP) library instead. This chapter describes details specific to {project_name} and does not contain specific protocol details. For more information see the http://openid.net/connect/[OpenID Connect specifications] and https://tools.ietf.org/html/rfc6749[OAuth2 specification]. ==== Endpoints -The most important endpoint to understand is the `well-known` configuration endpoint. It lists endpoints and other configuration options relevant to the OpenID Connect implementation in {{book.project.name}}. The endpoint is: +The most important endpoint to understand is the `well-known` configuration endpoint. It lists endpoints and other configuration options relevant to the OpenID Connect implementation in {project_name}. The endpoint is: .... /realms/{realm-name}/.well-known/openid-configuration .... -To obtain the full URL, add the base URL for {{book.project.name}} and replace `{realm-name}` with the name of your realm. For example: +To obtain the full URL, add the base URL for {project_name} and replace `{realm-name}` with the name of your realm. For example: $$http://localhost:8080/auth/realms/master/.well-known/openid-configuration$$ @@ -60,7 +60,7 @@ The endpoint can also be invoked directly by the application. To invoke this end /realms/{realm-name}/protocol/openid-connect/certs .... -The certificate endpoint returns the public keys enabled by the realm, encoded as a JSON Web Key (JWK). Depending on the realm settings there can be one or more keys enabled for verifying tokens. For more information see the link:{{book.adminguide.link}}[{{book.adminguide.name}}] and the https://tools.ietf.org/html/rfc7517[JSON Web Key specification]. +The certificate endpoint returns the public keys enabled by the realm, encoded as a JSON Web Key (JWK). Depending on the realm settings there can be one or more keys enabled for verifying tokens. For more information see the link:{adminguide_link}[{adminguide_name}] and the https://tools.ietf.org/html/rfc7517[JSON Web Key specification]. ===== Introspection Endpoint .... @@ -78,7 +78,7 @@ For more details see https://tools.ietf.org/html/rfc7662[OAuth 2.0 Token Introsp The dynamic client registration endpoint is used to dynamically register clients. -For more details see the <> and the +For more details see the <<_client_registration,Client Registration chapter>> and the https://openid.net/specs/openid-connect-registration-1_0.html[OpenID Connect Dynamic Client Registration specification]. @@ -86,9 +86,9 @@ https://openid.net/specs/openid-connect-registration-1_0.html[OpenID Connect Dyn ===== Authorization Code -The Authorization Code flow redirects the user agent to {{book.project.name}}. Once the user has successfully authenticated with {{book.project.name}} an +The Authorization Code flow redirects the user agent to {project_name}. Once the user has successfully authenticated with {project_name} an Authorization Code is created and the user agent is redirected back to the application. The application then uses the authorization code along with its -credentials to obtain an Access Token, Refresh Token and ID Token from {{book.project.name}}. +credentials to obtain an Access Token, Refresh Token and ID Token from {project_name}. The flow is targeted towards web applications, but is also recommended for native applications, including mobile applications, where it is possible to embed a user agent. @@ -113,7 +113,7 @@ For more details refer to the http://openid.net/specs/openid-connect-core-1_0.ht [[_resource_owner_password_credentials_flow]] ===== Resource Owner Password Credentials -Resource Owner Password Credentials, referred to as Direct Grant in {{book.project.name}}, allows exchanging user credentials for tokens. It's not recommended +Resource Owner Password Credentials, referred to as Direct Grant in {project_name}, allows exchanging user credentials for tokens. It's not recommended to use this flow unless you absolutely need to. Examples where this could be useful are legacy applications and command-line interfaces. There are a number of limitations of using this flow, including: @@ -152,7 +152,7 @@ curl \ Client Credentials is used when clients (applications and services) wants to obtain access on behalf of themselves rather than on behalf of a user. This can for example be useful for background services that applies changes to the system in general rather than for a specific user. -{{book.project.name}} provides support for clients to authenticate either with a secret or with public/private keys. +{project_name} provides support for clients to authenticate either with a secret or with public/private keys. This flow is not included in OpenID Connect, but is a part of the OAuth 2.0 specification. @@ -164,7 +164,7 @@ When using the redirect based flows it's important to use valid redirect uris fo especially applies to client-side (public clients) applications. Failing to do so could result in: * Open redirects - this can allow attackers to create spoof links that looks like they are coming from your domain -* Unauthorized entry - when users are already authenticated with {{book.project.name}} an attacker can use a public client where redirect uris have not be configured correctly to gain access by redirecting the user without the users knowledge +* Unauthorized entry - when users are already authenticated with {project_name} an attacker can use a public client where redirect uris have not be configured correctly to gain access by redirecting the user without the users knowledge In production for web applications always use `https` for all redirect URIs. Do not allow redirects to http. @@ -180,6 +180,6 @@ There's also a few special redirect URIs: `urn:ietf:wg:oauth:2.0:oob`:: If its not possible to start a web server in the client (or a browser is not available) it is possible to use the special `urn:ietf:wg:oauth:2.0:oob` redirect uri. - When this redirect uri is used {{book.project.name}} displays a page with the code in the title and in a box on the page. + When this redirect uri is used {project_name} displays a page with the code in the title and in a box on the page. The application can either detect that the browser title has changed, or the user can copy/paste the code manually to the application. With this redirect uri it is also possible for a user to use a different device to obtain a code to paste back to the application. diff --git a/securing_apps/topics/oidc/oidc-overview.adoc b/securing_apps/topics/oidc/oidc-overview.adoc index 8436712c35b..c5ebfd4b6ad 100644 --- a/securing_apps/topics/oidc/oidc-overview.adoc +++ b/securing_apps/topics/oidc/oidc-overview.adoc @@ -1,4 +1,4 @@ == OpenID Connect -This section describes how you can secure applications and services with OpenID Connect using either {{book.project.name}} adapters or generic OpenID Connect +This section describes how you can secure applications and services with OpenID Connect using either {project_name} adapters or generic OpenID Connect Resource Provider libraries. \ No newline at end of file diff --git a/securing_apps/topics/overview/overview.adoc b/securing_apps/topics/overview/overview.adoc index fdb03621925..67c8ffa41b8 100644 --- a/securing_apps/topics/overview/overview.adoc +++ b/securing_apps/topics/overview/overview.adoc @@ -1,9 +1,9 @@ == Overview -{{book.project.name}} supports both OpenID Connect (an extension to OAuth 2.0) and SAML 2.0. When securing clients and services the first thing you need to +{project_name} supports both OpenID Connect (an extension to OAuth 2.0) and SAML 2.0. When securing clients and services the first thing you need to decide is which of the two you are going to use. If you want you can also choose to secure some with OpenID Connect and others with SAML. -To secure clients and services you are also going to need an adapter or library for the protocol you've selected. {{book.project.name}} comes with its own +To secure clients and services you are also going to need an adapter or library for the protocol you've selected. {project_name} comes with its own adapters for selected platforms, but it is also possible to use generic OpenID Connect Resource Provider and SAML Service Provider libraries. diff --git a/securing_apps/topics/overview/supported-platforms.adoc b/securing_apps/topics/overview/supported-platforms.adoc index 204c656bb72..b12cd761798 100644 --- a/securing_apps/topics/overview/supported-platforms.adoc +++ b/securing_apps/topics/overview/supported-platforms.adoc @@ -3,77 +3,77 @@ ==== OpenID Connect ===== Java -* <> -{% if book.community %} - * <> -{% endif %} -* <> -{% if book.community %} - * <> - * <>, <> -{% endif %} +* <<_jboss_adapter,JBoss EAP>> +ifeval::[{project_community}==true] + * <<_jboss_adapter,WildFly>> +endif::[] +* <<_fuse_adapter,Fuse>> +ifeval::[{project_community}==true] + * <<_tomcat_adapter,Tomcat>> + * <<_jetty8_adapter,Jetty 8>> +endif::[] -{% if book.community %} -* <> - * <> (community) - * <> (community) -{% endif %} +ifeval::[{project_community}==true] +* <<_servlet_filter_adapter,Servlet Filter>> + * <<_spring_security_adapter,Spring Security>> (community) + * <<_spring_boot_adapter,Spring Boot>> (community) +endif::[] -{% if book.community %} +ifeval::[{project_community}==true] ===== JavaScript (client-side) -* <> -{% endif %} +* <<_javascript_adapter,JavaScript>> +endif::[] ===== Node.js (server-side) -* <> +* <<_nodejs_adapter,Node.js>> ===== JavaScript -* <> +* <<_javascript_adapter,JavaScript>> -{% if book.community %} +ifeval::[{project_community}==true] ===== Node.js -* https://github.com/keycloak/keycloak-nodejs-connect[{{book.project.name}} Connect] (community) -* https://github.com/keycloak/keycloak-nodejs-auth-utils[{{book.project.name}} Auth Utils] (community) -{% endif %} +* https://github.com/keycloak/keycloak-nodejs-connect[{project_name} Connect] (community) +* https://github.com/keycloak/keycloak-nodejs-auth-utils[{project_name} Auth Utils] (community) +endif::[] -{% if book.community %} +ifeval::[{project_community}==true] ==== C# * https://github.com/dylanplecki/KeycloakOwinAuthentication[OWIN] (community) -{% endif %} +endif::[] -{% if book.community %} +ifeval::[{project_community}==true] ==== Python * https://pypi.python.org/pypi/oic/[oidc] (generic) -{% endif %} +endif::[] -{% if book.community %} +ifeval::[{project_community}==true] ==== Android * https://github.com/openid/AppAuth-Android[AppAuth] (generic) * https://github.com/aerogear/aerogear-android-authz[AeroGear] (generic) -{% endif %} +endif::[] -{% if book.community %} +ifeval::[{project_community}==true] ==== iOS * https://github.com/openid/AppAuth-iOS[AppAuth] (generic) * https://github.com/aerogear/aerogear-ios-oauth2[AeroGear] (generic) -{% endif %} +endif::[] -{% if book.community %} +ifeval::[{project_community}==true] ===== Apache HTTP Server * https://github.com/pingidentity/mod_auth_openidc[mod_auth_openidc] -{% endif %} +endif::[] ==== SAML ===== Java -* <> -{% if book.community %} -* <> -* <> -* <> -{% endif %} +* <<_saml_jboss_adapter,JBoss EAP>> +ifeval::[{project_community}==true] +* <<_saml_jboss_adapter,WildFly>> +* <<_tomcat_adapter,Tomcat>> +* <<_jetty_saml_adapter,Jetty>> +endif::[] ===== Apache HTTP Server -* <> +* <<_mod_auth_mellon,mod_auth_mellon>> diff --git a/securing_apps/topics/overview/supported-protocols.adoc b/securing_apps/topics/overview/supported-protocols.adoc index 0d24553434b..73d2459f79c 100644 --- a/securing_apps/topics/overview/supported-protocols.adoc +++ b/securing_apps/topics/overview/supported-protocols.adoc @@ -9,14 +9,14 @@ While OAuth 2.0 is only a framework for building authorization protocols and is protocol. OIDC also makes heavy use of the link:https://jwt.io[Json Web Token] (JWT) set of standards. These standards define an identity token JSON format and ways to digitally sign and encrypt that data in a compact and web-friendly way. -There is really two types of use cases when using OIDC. The first is an application that asks the {{book.project.name}} server to authenticate +There is really two types of use cases when using OIDC. The first is an application that asks the {project_name} server to authenticate a user for them. After a successful login, the application will receive an _identity token_ and an _access token_. The _identity token_ contains information about the user such as username, email, and other profile information. The _access token_ is digitally signed by the realm and contains access information (like user role mappings) that the application can use to determine what resources the user is allowed to access on the application. -The second type of use cases is that of a client that wants to gain access to remote services. In this case, the client asks {{book.project.name}} -to obtain an _access token_ it can use to invoke on other remote services on behalf of the user. {{book.project.name}} authenticates the user +The second type of use cases is that of a client that wants to gain access to remote services. In this case, the client asks {project_name} +to obtain an _access token_ it can use to invoke on other remote services on behalf of the user. {project_name} authenticates the user then asks the user for consent to grant access to the client requesting it. The client then receives the _access token_. This _access token_ is digitally signed by the realm. The client can make REST invocations on remote services using this _access token_. The REST service extracts the _access token_, verifies the signature of the token, then decides based on access information within the token whether or not to process @@ -28,22 +28,22 @@ link:http://saml.xml.org/saml-specifications[SAML 2.0] is a similar specificatio of WS-* specifications so it tends to be a bit more verbose than OIDC. SAML 2.0 is primarily an authentication protocol that works by exchanging XML documents between the authentication server and the application. XML signatures and encryption are used to verify requests and responses. -In {{book.project.name}} SAML serves two types of use cases: browser applications and REST invocations. +In {project_name} SAML serves two types of use cases: browser applications and REST invocations. -There is really two types of use cases when using SAML. The first is an application that asks the {{book.project.name}} server to authenticate +There is really two types of use cases when using SAML. The first is an application that asks the {project_name} server to authenticate a user for them. After a successful login, the application will receive an XML document that contains something called a SAML assertion that specifies various attributes about the user. This XML document is digitally signed by the realm and contains access information (like user role mappings) that the application can use to determine what resources the user is allowed to access on the application. -The second type of use cases is that of a client that wants to gain access to remote services. In this case, the client asks {{book.project.name}} +The second type of use cases is that of a client that wants to gain access to remote services. In this case, the client asks {project_name} to obtain a SAML assertion it can use to invoke on other remote services on behalf of the user. ==== OpenID Connect vs. SAML Choosing between OpenID Connect and SAML is not just a matter of using a newer protocol (OIDC) instead of the older more mature protocol (SAML). -In most cases {{book.project.name}} recommends using OIDC. +In most cases {project_name} recommends using OIDC. SAML tends to be a bit more verbose than OIDC. diff --git a/securing_apps/topics/overview/what-are-client-adapters.adoc b/securing_apps/topics/overview/what-are-client-adapters.adoc index 47f8f83f185..c157cd06445 100644 --- a/securing_apps/topics/overview/what-are-client-adapters.adoc +++ b/securing_apps/topics/overview/what-are-client-adapters.adoc @@ -1,6 +1,6 @@ === What are Client Adapters? -{{book.project.name}} client adapters are libraries that makes it very easy to secure applications and services with {{book.project.name}}. We call them +{project_name} client adapters are libraries that makes it very easy to secure applications and services with {project_name}. We call them adapters rather than libraries as they provide a tight integration to the underlying platform and framework. This makes our adapters easy to use and they require less boilerplate code than what is typically required by a library. diff --git a/securing_apps/topics/saml/java/assertion-api.adoc b/securing_apps/topics/saml/java/assertion-api.adoc index 28e6919adbb..20a8d481267 100644 --- a/securing_apps/topics/saml/java/assertion-api.adoc +++ b/securing_apps/topics/saml/java/assertion-api.adoc @@ -2,7 +2,7 @@ ==== Obtaining Assertion Attributes After a successful SAML login, your application code may want to obtain attribute values passed with the SAML assertion. -`HttpServletRequest.getUserPrincipal()` returns a `Principal` object that you can typecast into a {{book.project.name}} specific class +`HttpServletRequest.getUserPrincipal()` returns a `Principal` object that you can typecast into a {project_name} specific class called `org.keycloak.adapters.saml.SamlPrincipal`. This object allows you to look at the raw assertion and also has convenience functions to look up attribute values. diff --git a/securing_apps/topics/saml/java/debugging.adoc b/securing_apps/topics/saml/java/debugging.adoc index e1469caa52c..d6de7c5c1fb 100644 --- a/securing_apps/topics/saml/java/debugging.adoc +++ b/securing_apps/topics/saml/java/debugging.adoc @@ -1,4 +1,4 @@ ==== Troubleshooting -The best way to troubleshoot problems is to turn on debugging for SAML in both the client adapter and {{book.project.name}} Server. Using your logging framework, set the log level to `DEBUG` for the `org.keycloak.saml` package. Turning this on allows you to see the SAML requests and response documents being sent to and from the server. +The best way to troubleshoot problems is to turn on debugging for SAML in both the client adapter and {project_name} Server. Using your logging framework, set the log level to `DEBUG` for the `org.keycloak.saml` package. Turning this on allows you to see the SAML requests and response documents being sent to and from the server. diff --git a/securing_apps/topics/saml/java/error_handling.adoc b/securing_apps/topics/saml/java/error_handling.adoc index f271adc8dbb..31d8781a50d 100644 --- a/securing_apps/topics/saml/java/error_handling.adoc +++ b/securing_apps/topics/saml/java/error_handling.adoc @@ -1,7 +1,7 @@ ==== Error Handling -{{book.project.name}} has some error handling facilities for servlet based client adapters. +{project_name} has some error handling facilities for servlet based client adapters. When an error is encountered in authentication, the client adapter will call `HttpServletResponse.sendError()`. You can set up an `error-page` within your `web.xml` file to handle the error however you want. The client adapter can throw 400, 401, 403, and 500 errors. diff --git a/securing_apps/topics/saml/java/general-config.adoc b/securing_apps/topics/saml/java/general-config.adoc index ce189c75b88..660422ab3a6 100644 --- a/securing_apps/topics/saml/java/general-config.adoc +++ b/securing_apps/topics/saml/java/general-config.adoc @@ -2,7 +2,7 @@ ==== General Adapter Config -Each SAML client adapter supported by {{book.project.name}} can be configured by a simple XML text file. +Each SAML client adapter supported by {project_name} can be configured by a simple XML text file. This is what one might look like: [source,xml] diff --git a/securing_apps/topics/saml/java/general-config/idp_httpclient_subelement.adoc b/securing_apps/topics/saml/java/general-config/idp_httpclient_subelement.adoc index bc19d4501cd..521568fed03 100644 --- a/securing_apps/topics/saml/java/general-config/idp_httpclient_subelement.adoc +++ b/securing_apps/topics/saml/java/general-config/idp_httpclient_subelement.adoc @@ -5,7 +5,7 @@ The `HttpClient` optional sub element defines the properties of HTTP client used for automatic obtaining of certificates containing public keys for IDP signature verification via SAML descriptor of the IDP when -<>. +<<_sp-idp-keys-automatic,enabled>>. [source,xml] ---- @@ -20,20 +20,20 @@ verification via SAML descriptor of the IDP when ---- connectionPoolSize:: - Adapters will make separate HTTP invocations to the {{book.project.name}} server to turn an access code into an access token. - This config option defines how many connections to the {{book.project.name}} server should be pooled. + Adapters will make separate HTTP invocations to the {project_name} server to turn an access code into an access token. + This config option defines how many connections to the {project_name} server should be pooled. This is _OPTIONAL_. The default value is `10`. disableTrustManager:: - If the {{book.project.name}} server requires HTTPS and this config option is set to `true` you do not have to specify a truststore. + If the {project_name} server requires HTTPS and this config option is set to `true` you do not have to specify a truststore. This setting should only be used during development and *never* in production as it will disable verification of SSL certificates. This is _OPTIONAL_. The default value is `false`. allowAnyHostname:: - If the {{book.project.name}} server requires HTTPS and this config option is set to `true` - the {{book.project.name}} server's certificate is validated via the truststore, + If the {project_name} server requires HTTPS and this config option is set to `true` + the {project_name} server's certificate is validated via the truststore, but host name validation is not done. This setting should only be used during development and *never* in production as it will partly disable verification of SSL certificates. @@ -43,11 +43,11 @@ allowAnyHostname:: truststore:: The value is the file path to a keystore file. If you prefix the path with `classpath:`, then the truststore will be obtained from the deployment's classpath instead. - Used for outgoing HTTPS communications to the {{book.project.name}} server. + Used for outgoing HTTPS communications to the {project_name} server. Client making HTTPS requests need a way to verify the host of the server they are talking to. This is what the trustore does. The keystore contains one or more trusted host certificates or certificate authorities. - You can create this truststore by extracting the public certificate of the {{book.project.name}} server's SSL keystore. + You can create this truststore by extracting the public certificate of the {project_name} server's SSL keystore. This is _REQUIRED_ unless `disableTrustManager` is `true`. truststorePassword:: @@ -56,7 +56,7 @@ truststorePassword:: clientKeystore:: This is the file path to a keystore file. - This keystore contains client certificate for two-way SSL when the adapter makes HTTPS requests to the {{book.project.name}} server. + This keystore contains client certificate for two-way SSL when the adapter makes HTTPS requests to the {project_name} server. This is _OPTIONAL_. clientKeystorePassword:: diff --git a/securing_apps/topics/saml/java/general-config/idp_keys_subelement.adoc b/securing_apps/topics/saml/java/general-config/idp_keys_subelement.adoc index c92cc3fafd7..af36c64d096 100644 --- a/securing_apps/topics/saml/java/general-config/idp_keys_subelement.adoc +++ b/securing_apps/topics/saml/java/general-config/idp_keys_subelement.adoc @@ -3,22 +3,22 @@ ===== IDP Keys sub element The Keys sub element of IDP is only used to define the certificate or public key to use to verify documents signed by the IDP. -It is defined in the same way as the <>. +It is defined in the same way as the <<_saml-sp-keys,SP's Keys element>>. But again, you only have to define one certificate or public key reference. Note that, if both IDP and SP are realized by -{{book.project.name}} server and adapter, respectively, there is no need to specify the keys for signature validation, see below. +{project_name} server and adapter, respectively, there is no need to specify the keys for signature validation, see below. [[_sp-idp-keys-automatic]] It is possible to configure SP to obtain public keys for IDP signature validation from published certificates automatically, provided both SP and IDP are -implemented by {{book.project.name}}. +implemented by {project_name}. This is done by removing all declarations of signature validation keys in Keys sub element. If the Keys sub element would then remain empty, it can be omitted completely. The keys are then automatically obtained by SP from SAML descriptor, location of which is derived from SAML endpoint URL specified in the -<>. +<<_sp-idp-singlesignonservice,IDP SingleSignOnService sub element>>. Settings of the HTTP client that is used for SAML descriptor retrieval usually needs no additional configuration, however it can be configured in the -<>. +<<_sp-idp-httpclient,IDP HttpClient sub element>>. It is also possible to specify multiple keys for signature verification. This is done by declaring multiple Key elements within Keys sub element that have `signing` attribute set to `true`. @@ -26,7 +26,7 @@ This is useful for example in situation when the IDP signing keys are rotated: T usually a transition period when new SAML protocol messages and assertions are signed with the new key but those signed by previous key should still be accepted. -It is not possible to configure {{book.project.name}} to both obtain the keys +It is not possible to configure {project_name} to both obtain the keys for signature verification automatically and define additional static signature verification keys. diff --git a/securing_apps/topics/saml/java/java-adapters.adoc b/securing_apps/topics/saml/java/java-adapters.adoc index db4148cdcb2..3bd7334cf38 100644 --- a/securing_apps/topics/saml/java/java-adapters.adoc +++ b/securing_apps/topics/saml/java/java-adapters.adoc @@ -1,4 +1,4 @@ === Java Adapters -{{book.project.name}} comes with a range of different adapters for Java application. Selecting the correct adapter depends on the target platform. +{project_name} comes with a range of different adapters for Java application. Selecting the correct adapter depends on the target platform. diff --git a/securing_apps/topics/saml/java/jboss-adapter/jboss_adapter_installation.adoc b/securing_apps/topics/saml/java/jboss-adapter/jboss_adapter_installation.adoc index 2639ac81921..1c328bebeae 100644 --- a/securing_apps/topics/saml/java/jboss-adapter/jboss_adapter_installation.adoc +++ b/securing_apps/topics/saml/java/jboss-adapter/jboss_adapter_installation.adoc @@ -2,9 +2,9 @@ [[_saml-jboss-adapter-installation]] ===== Adapter Installation -Each adapter is a separate download on the {{book.project.name}} download site. +Each adapter is a separate download on the {project_name} download site. -{% if book.community %} +ifeval::[{project_community}==true] Install on Wildfly 9 or 10, 11 or JBoss EAP 7: [source] @@ -13,10 +13,10 @@ Install on Wildfly 9 or 10, 11 or JBoss EAP 7: $ cd $WILDFLY_HOME $ unzip keycloak-saml-wildfly-adapter-dist.zip ---- -{% endif %} +endif::[] -{% if book.community %} +ifeval::[{project_community}==true] Install on JBoss EAP 6.x: [source] ---- @@ -24,9 +24,9 @@ Install on JBoss EAP 6.x: $ cd $JBOSS_HOME $ unzip keycloak-saml-eap6-adapter-dist.zip ---- -{% endif %} +endif::[] -{% if book.product %} +ifeval::[{project_product}==true] Install on JBoss EAP 6.x: [source] ---- @@ -42,23 +42,23 @@ Install on JBoss EAP 7.x: $ cd $JBOSS_HOME $ unzip rh-sso-saml-eap7-adapter.zip ---- -{% endif %} +endif::[] These zip files create new JBoss Modules specific to the Wildfly/JBoss EAP SAML Adapter within your Wildfly or JBoss EAP distro. -After adding the modules, you must then enable the {{book.project.name}} SAML Subsystem within your app server's server configuration: `domain.xml` or `standalone.xml`. +After adding the modules, you must then enable the {project_name} SAML Subsystem within your app server's server configuration: `domain.xml` or `standalone.xml`. There is a CLI script that will help you modify your server configuration. Start the server and run the script from the server's bin directory: -{% if book.community %} +ifeval::[{project_community}==true] .Wildfly 11 [source] ---- $ ./bin/jboss-cli.sh --file=adapter-elytron-install-saml.cli ---- -{% endif %} +endif::[] .Any other server but Wildfly 11 [source] diff --git a/securing_apps/topics/saml/java/jboss-adapter/required_per_war_configuration.adoc b/securing_apps/topics/saml/java/jboss-adapter/required_per_war_configuration.adoc index 928d10ccc5d..ea6659bcdc9 100644 --- a/securing_apps/topics/saml/java/jboss-adapter/required_per_war_configuration.adoc +++ b/securing_apps/topics/saml/java/jboss-adapter/required_per_war_configuration.adoc @@ -4,7 +4,7 @@ This section describes how to secure a WAR directly by adding config and editing files within your WAR package. The first thing you must do is create a `keycloak-saml.xml` adapter config file within the `WEB-INF` directory of your WAR. -The format of this config file is described in the <> section. +The format of this config file is described in the <<_saml-general-config,General Adapter Config>> section. Next you must set the `auth-method` to `KEYCLOAK-SAML` in `web.xml`. You also have to use standard servlet security to specify role-base constraints on your URLs. diff --git a/securing_apps/topics/saml/java/jboss-adapter/securing_wars.adoc b/securing_apps/topics/saml/java/jboss-adapter/securing_wars.adoc index 4443e4b6940..1121debcd35 100644 --- a/securing_apps/topics/saml/java/jboss-adapter/securing_wars.adoc +++ b/securing_apps/topics/saml/java/jboss-adapter/securing_wars.adoc @@ -1,8 +1,8 @@ -===== Securing WARs via {{book.project.name}} SAML Subsystem +===== Securing WARs via {project_name} SAML Subsystem -You do not have to crack open a WAR to secure it with {{book.project.name}}. -Alternatively, you can externally secure it via the {{book.project.name}} SAML Adapter Subsystem. +You do not have to crack open a WAR to secure it with {project_name}. +Alternatively, you can externally secure it via the {project_name} SAML Adapter Subsystem. While you don't have to specify KEYCLOAK-SAML as an `auth-method`, you still have to define the `security-constraints` in `web.xml`. You do not, however, have to create a `WEB-INF/keycloak-saml.xml` file. This metadata is instead defined within the XML in your server's `domain.xml` or `standalone.xml` subsystem configuration section. @@ -27,7 +27,7 @@ This metadata is instead defined within the XML in your server's `domain.xml` or The `secure-deployment` `name` attribute identifies the WAR you want to secure. Its value is the `module-name` defined in `web.xml` with `.war` appended. -The rest of the configuration uses the same XML syntax as `keycloak-saml.xml` configuration defined in <>. +The rest of the configuration uses the same XML syntax as `keycloak-saml.xml` configuration defined in <<_saml-general-config,General Adapter Config>>. An example configuration: diff --git a/securing_apps/topics/saml/java/jetty-adapter.adoc b/securing_apps/topics/saml/java/jetty-adapter.adoc index b6d9c0276ce..20945e3216d 100644 --- a/securing_apps/topics/saml/java/jetty-adapter.adoc +++ b/securing_apps/topics/saml/java/jetty-adapter.adoc @@ -2,6 +2,6 @@ ==== Jetty SAML Adapters -To be able to secure WAR apps deployed on Jetty you must install the {{book.project.name}} Jetty 9.x or 8.x SAML adapter into your Jetty installation. +To be able to secure WAR apps deployed on Jetty you must install the {project_name} Jetty 9.x or 8.x SAML adapter into your Jetty installation. You then have to provide some extra configuration in each WAR you deploy to Jetty. Let's go over these steps. diff --git a/securing_apps/topics/saml/java/jetty-adapter/jetty8-per_war_config.adoc b/securing_apps/topics/saml/java/jetty-adapter/jetty8-per_war_config.adoc index 90f66c7c573..7a8f1117520 100644 --- a/securing_apps/topics/saml/java/jetty-adapter/jetty8-per_war_config.adoc +++ b/securing_apps/topics/saml/java/jetty-adapter/jetty8-per_war_config.adoc @@ -2,4 +2,4 @@ ===== Jetty 8 Per WAR Configuration Enabling Keycloak for your WARs is the same as the Jetty 9.x adapter. -See <> +See <<_saml-jetty9-per-war, Jetty 9 Per War Configuration>> diff --git a/securing_apps/topics/saml/java/jetty-adapter/jetty9_per_war_config.adoc b/securing_apps/topics/saml/java/jetty-adapter/jetty9_per_war_config.adoc index e27def08a06..1c61ef34690 100644 --- a/securing_apps/topics/saml/java/jetty-adapter/jetty9_per_war_config.adoc +++ b/securing_apps/topics/saml/java/jetty-adapter/jetty9_per_war_config.adoc @@ -22,7 +22,7 @@ This is a Jetty specific config file and you must define a Keycloak specific aut ---- Next you must create a `keycloak-saml.xml` adapter config file within the `WEB-INF` directory of your WAR. -The format of this config file is describe in the <> section. +The format of this config file is describe in the <<_saml-general-config,General Adapter Config>> section. Finally you must specify both a `login-config` and use standard servlet security to specify role-base constraints on your URLs. Here's an example: diff --git a/securing_apps/topics/saml/java/saml-jboss-adapter.adoc b/securing_apps/topics/saml/java/saml-jboss-adapter.adoc index c090aba1251..ef7083b061e 100644 --- a/securing_apps/topics/saml/java/saml-jboss-adapter.adoc +++ b/securing_apps/topics/saml/java/saml-jboss-adapter.adoc @@ -1,18 +1,18 @@ [[_saml_jboss_adapter]] -{% if book.community %} +ifeval::[{project_community}==true] ==== JBoss EAP/Wildfly Adapter -{% endif %} -{% if book.product %} +endif::[] +ifeval::[{project_product}==true] ==== JBoss EAP Adapter -{% endif %} +endif::[] -{% if book.community %} -To be able to secure WAR apps deployed on JBoss EAP or Wildfly, you must install and configure the {{book.project.name}} SAML Adapter Subsystem. -{% endif %} -{% if book.product %} -To be able to secure WAR apps deployed on JBoss EAP, you must install and configure the {{book.project.name}} SAML Adapter Subsystem. -{% endif %} +ifeval::[{project_community}==true] +To be able to secure WAR apps deployed on JBoss EAP or Wildfly, you must install and configure the {project_name} SAML Adapter Subsystem. +endif::[] +ifeval::[{project_product}==true] +To be able to secure WAR apps deployed on JBoss EAP, you must install and configure the {project_name} SAML Adapter Subsystem. +endif::[] You then provide a keycloak config, `/WEB-INF/keycloak-saml.xml` file in your WAR and change the auth-method to KEYCLOAK-SAML within web.xml. Both methods are described in this section. diff --git a/securing_apps/topics/saml/java/servlet-filter-adapter.adoc b/securing_apps/topics/saml/java/servlet-filter-adapter.adoc index a00dd72d321..d95c5fe026b 100644 --- a/securing_apps/topics/saml/java/servlet-filter-adapter.adoc +++ b/securing_apps/topics/saml/java/servlet-filter-adapter.adoc @@ -2,12 +2,12 @@ ==== Java Servlet Filter Adapter If you want to use SAML with a Java servlet application that doesn't have an adapter for that servlet platform, you can -opt to use the servlet filter adapter that {{book.project.name}} has. +opt to use the servlet filter adapter that {project_name} has. This adapter works a little differently than the other adapters. You still have to specify a `/WEB-INF/keycloak-saml.xml` file as defined in -the <> section, but +the <<_saml-general-config,General Adapter Config>> section, but you do not define security constraints in _web.xml_. -Instead you define a filter mapping using the {{book.project.name}} servlet filter adapter to secure the url patterns you want to secure. +Instead you define a filter mapping using the {project_name} servlet filter adapter to secure the url patterns you want to secure. NOTE: Backchannel logout works a bit differently than the standard adapters. Instead of invalidating the http session it instead marks the session ID as logged out. @@ -35,7 +35,7 @@ WARNING: Backchannel logout does not currently work when you have a clustered ap ---- -The {{book.project.name}} filter has the same configuration parameters available as the other adapters except you must +The {project_name} filter has the same configuration parameters available as the other adapters except you must define them as filter init params instead of context params. You can define multiple filter mappings if you have various different secure and unsecure url patterns. @@ -52,6 +52,6 @@ To use this filter, include this maven artifact in your WAR poms: org.keycloak keycloak-saml-servlet-filter-adapter - {{book.project.versionMvn}} + {project_versionMvn} ---- diff --git a/securing_apps/topics/saml/java/tomcat-adapter/tomcat_adapter_per_war_config.adoc b/securing_apps/topics/saml/java/tomcat-adapter/tomcat_adapter_per_war_config.adoc index 3ea4a650665..27adb7cc653 100644 --- a/securing_apps/topics/saml/java/tomcat-adapter/tomcat_adapter_per_war_config.adoc +++ b/securing_apps/topics/saml/java/tomcat-adapter/tomcat_adapter_per_war_config.adoc @@ -14,7 +14,7 @@ This is a Tomcat specific config file and you must define a Keycloak specific Va ---- Next you must create a `keycloak-saml.xml` adapter config file within the `WEB-INF` directory of your WAR. -The format of this config file is describe in the <> section. +The format of this config file is describe in the <<_saml-general-config,General Adapter Config>> section. Finally you must specify both a `login-config` and use standard servlet security to specify role-base constraints on your URLs. Here's an example: diff --git a/securing_apps/topics/saml/mod-auth-mellon.adoc b/securing_apps/topics/saml/mod-auth-mellon.adoc index b0fd1bd0ece..a7792c0a17e 100644 --- a/securing_apps/topics/saml/mod-auth-mellon.adoc +++ b/securing_apps/topics/saml/mod-auth-mellon.adoc @@ -6,30 +6,30 @@ The https://github.com/UNINETT/mod_auth_mellon[mod_auth_mellon] module is an Apa To configure mod_auth_mellon you'll need: -* An Identity Provider (IdP) entity descriptor XML file, which describes the connection to {{book.project.name}} or another SAML IdP +* An Identity Provider (IdP) entity descriptor XML file, which describes the connection to {project_name} or another SAML IdP * An SP entity descriptor XML file, which describes the SAML connections and configuration for the application you are securing. * A private key PEM file, which is a text file in the PEM format that defines the private key the application uses to sign documents. * A certificate PEM file, which is a text file that defines the certificate for your application. * mod_auth_mellon-specific Apache HTTPD module configuration. -{% if book.community %} -If you have already defined and registered the client application within a realm on the {{book.project.name}} application server, {{book.project.name}} can generate all the files you need except the Apache HTTPD module configuration. +ifeval::[{project_community}==true] +If you have already defined and registered the client application within a realm on the {project_name} application server, {project_name} can generate all the files you need except the Apache HTTPD module configuration. To generate the Apache HTTPD module configuration, complete the following steps: . Go to the Installation page of your SAML client and select the Mod Auth Mellon files option. + .mod_auth_mellon config download -image:../../book.images/mod-auth-mellon-config-download.png[] +image:{project_images}/mod-auth-mellon-config-download.png[] . Click *Download* to download a zip file that contains the XML descriptor and PEM files you need. -{% endif %} +endif::[] -==== Configuring mod_auth_mellon with {{book.project.name}} +==== Configuring mod_auth_mellon with {project_name} There are two hosts involved: -* The host on which {{book.project.name}} is running, which will be referred to as $idp_host because {{book.project.name}} is a SAML identity provider (IdP). +* The host on which {project_name} is running, which will be referred to as $idp_host because {project_name} is a SAML identity provider (IdP). * The host on which the web application is running, which will be referred to as $sp_host. In SAML an application using an IdP is called a service provider (SP). @@ -140,19 +140,19 @@ mv ${file_prefix}.key /etc/httpd/saml2/mellon.key mv ${file_prefix}.xml /etc/httpd/saml2/mellon_metadata.xml ---- -===== Adding the Mellon Service Provider to the {{book.project.name}} Identity Provider +===== Adding the Mellon Service Provider to the {project_name} Identity Provider -Assumption: The {{book.project.name}} IdP has already been installed on the $idp_host. +Assumption: The {project_name} IdP has already been installed on the $idp_host. -{{book.project.name}} supports multiple tenancy where all users, clients, and so on are grouped in what is called a realm. Each realm is independent of other realms. You can use an existing realm in your {{book.project.name}}, but this example shows how to create a new realm called test_realm and use that realm. +{project_name} supports multiple tenancy where all users, clients, and so on are grouped in what is called a realm. Each realm is independent of other realms. You can use an existing realm in your {project_name}, but this example shows how to create a new realm called test_realm and use that realm. -All these operations are performed using the {{book.project.name}} administration web console. You must have the admin username and password for $idp_host. +All these operations are performed using the {project_name} administration web console. You must have the admin username and password for $idp_host. To complete the following steps: . Open the Admin Console and log on by entering the admin username and password. + -After logging into the administration console there will be an existing realm. When {{book.project.name}} is first set up a root realm, master, is created by default. Any previously created realms are listed in the upper left corner of the administration console in a drop-down list. +After logging into the administration console there will be an existing realm. When {project_name} is first set up a root realm, master, is created by default. Any previously created realms are listed in the upper left corner of the administration console in a drop-down list. . From the realm drop-down list select *Add realm*. @@ -160,7 +160,7 @@ After logging into the administration console there will be an existing realm. W ====== Adding the Mellon Service Provider as a Client of the Realm -In {{book.project.name}} SAML SPs are known as clients. To add the SP we must be in the Clients section of the realm. +In {project_name} SAML SPs are known as clients. To add the SP we must be in the Clients section of the realm. . Click the Clients menu item on the left and click *Create* in the upper right corner to create a new client. @@ -182,7 +182,7 @@ There are several client configuration parameters we suggest setting: . Change "postResponse" to "paosResponse". (The paosResponse URL is needed for SAML ECP.) . Click *Save* at the bottom. -Many SAML SPs determine authorization based on a user's membership in a group. The {{book.project.name}} IdP can manage user group information but it does not supply the user's groups unless the IdP is configured to supply it as a SAML attribute. +Many SAML SPs determine authorization based on a user's membership in a group. The {project_name} IdP can manage user group information but it does not supply the user's groups unless the IdP is configured to supply it as a SAML attribute. To configure the IdP to supply the user's groups as as a SAML attribute, complete the following steps: @@ -225,4 +225,4 @@ NOTE: Configtest is equivalent to the -t argument to apachectl. If the configura systemctl restart httpd.service ---- -You have now set up both {{book.project.name}} as a SAML IdP in the test_realm and mod_auth_mellon as SAML SP protecting the URL $sp_host/protected (and everything beneath it) by authenticating against the ``$idp_host`` IdP. +You have now set up both {project_name} as a SAML IdP in the test_realm and mod_auth_mellon as SAML SP protecting the URL $sp_host/protected (and everything beneath it) by authenticating against the ``$idp_host`` IdP. diff --git a/securing_apps/topics/saml/saml-overview.adoc b/securing_apps/topics/saml/saml-overview.adoc index 11d65a9f891..940ea23e57f 100644 --- a/securing_apps/topics/saml/saml-overview.adoc +++ b/securing_apps/topics/saml/saml-overview.adoc @@ -1,4 +1,4 @@ == SAML -This section describes how you can secure applications and services with SAML using either {{book.project.name}} client adapters or generic +This section describes how you can secure applications and services with SAML using either {project_name} client adapters or generic SAML provider libraries. \ No newline at end of file diff --git a/server_admin/README.adoc b/server_admin/README.adoc deleted file mode 100755 index 12a58a79b1e..00000000000 --- a/server_admin/README.adoc +++ /dev/null @@ -1,9 +0,0 @@ - -= Server Administration - -image:images/keycloak_logo.png[alt="Keycloak"] - -{{book.project.name}} {{book.project.version}} - -http://www.keycloak.org - diff --git a/server_admin/SUMMARY.adoc b/server_admin/SUMMARY.adoc deleted file mode 100644 index d565a8b3375..00000000000 --- a/server_admin/SUMMARY.adoc +++ /dev/null @@ -1,113 +0,0 @@ -= Server Administration Guide - -.. link:server_admin/topics/overview.adoc[Overview] -... link:server_admin/topics/overview/features.adoc[Features] -... link:server_admin/topics/overview/how.adoc[How Does Security Work?] -... link:server_admin/topics/overview/concepts.adoc[Core Concepts and Terms] -.. link:server_admin/topics/initialization.adoc[Server Initialization] -.. link:server_admin/topics/admin-console.adoc[Admin Console] -... link:server_admin/topics/realms/master.adoc[The Master Realm] -... link:server_admin/topics/realms/create.adoc[Creating a New Realm] -... link:server_admin/topics/realms/ssl.adoc[Realm SSL Mode] -... link:server_admin/topics/realms/cache.adoc[Clearing Server Caches] -... link:server_admin/topics/realms/email.adoc[Email Settings] -... link:server_admin/topics/realms/themes.adoc[Themes and Internationalization] -.. link:server_admin/topics/users.adoc[User Management] -... link:server_admin/topics/users/viewing.adoc[Viewing Users] -... link:server_admin/topics/users/create-user.adoc[Creating New Users] -... link:server_admin/topics/users/attributes.adoc[User Attributes] -... link:server_admin/topics/users/credentials.adoc[Credentials] -... link:server_admin/topics/users/required-actions.adoc[Required Actions] -... link:server_admin/topics/users/impersonation.adoc[Impersonation] -... link:server_admin/topics/users/user-registration.adoc[User Registration] -.... link:server_admin/topics/users/recaptcha.adoc[Recaptcha Support] -.. link:server_admin/topics/login-settings.adoc[Login Page Settings] -... link:server_admin/topics/login-settings/forgot-password.adoc[Forgot Password] -... link:server_admin/topics/login-settings/remember-me.adoc[Remember Me] -.. link:server_admin/topics/authentication.adoc[Authentication] -... link:server_admin/topics/authentication/password-policies.adoc[Password Policies] -... link:server_admin/topics/authentication/otp-policies.adoc[OTP Policies] -... link:server_admin/topics/authentication/flows.adoc[Authentication Flows] -... link:server_admin/topics/authentication/kerberos.adoc[Kerberos] -... link:server_admin/topics/authentication/x509.adoc[X509 Client Certificate Authentication] -.. link:server_admin/topics/sso-protocols.adoc[SSO Protocols] -... link:server_admin/topics/sso-protocols/oidc.adoc[OpenID Connect] -... link:server_admin/topics/sso-protocols/saml.adoc[SAML] -... link:server_admin/topics/sso-protocols/saml-vs-oidc.adoc[OIDC vs. SAML] -... link:server_admin/topics/sso-protocols/docker.adoc[Docker] -.. link:server_admin/topics/clients.adoc[Managing Clients] -... link:server_admin/topics/clients/client-oidc.adoc[OIDC Clients] -.... link:server_admin/topics/clients/oidc/confidential.adoc[Confidential Client Credentials] -.... link:server_admin/topics/clients/oidc/service-accounts.adoc[Service Accounts] -... link:server_admin/topics/clients/client-saml.adoc[SAML Clients] -.... link:server_admin/topics/clients/saml/idp-initiated-login.adoc[IDP Initiated Login] -.... link:server_admin/topics/clients/saml/entity-descriptors.adoc[SAML Entity Descriptors] -... link:server_admin/topics/clients/client-link.adoc[Client Links] -... link:server_admin/topics/clients/protocol-mappers.adoc[Token and Assertion Mappings] -... link:server_admin/topics/clients/installation.adoc[Generating Client Adapter Config] -... link:server_admin/topics/clients/client-templates.adoc[Client Templates] -.. link:server_admin/topics/roles.adoc[Roles] -... link:server_admin/topics/roles/realm-roles.adoc[Realm Roles] -... link:server_admin/topics/roles/client-roles.adoc[Client Roles] -... link:server_admin/topics/roles/composite.adoc[Composite Roles] -... link:server_admin/topics/roles/user-role-mappings.adoc[User Role Mappings] -.... link:server_admin/topics/roles/user-role-mappings/default-roles.adoc[Default Roles] -... link:server_admin/topics/roles/client-scope.adoc[Client Scope] -.. link:server_admin/topics/groups.adoc[Groups] -... link:server_admin/topics/groups/groups-vs-roles.adoc[Groups Vs. Roles] -... link:server_admin/topics/groups/default-groups.adoc[Default Groups] -.. link:server_admin/topics/admin-console-permissions.adoc[Admin Console Access Control and Permissions] -... link:server_admin/topics/admin-console-permissions/master-realm.adoc[Master Realm] -... link:server_admin/topics/admin-console-permissions/per-realm.adoc[Dedicated Realm Admin Consoles] -... link:server_admin/topics/admin-console-permissions/fine-grain.adoc[Fine Grain Admin Permissions] -.. link:server_admin/topics/realms/keys.adoc[Realm Keys] -.. link:server_admin/topics/identity-broker.adoc[Identity Brokering] -... link:server_admin/topics/identity-broker/overview.adoc[Brokering Overview] -... link:server_admin/topics/identity-broker/default-provider.adoc[Default Provider] -... link:server_admin/topics/identity-broker/configuration.adoc[General Configuration] -... link:server_admin/topics/identity-broker/social-login.adoc[Social Login] -.... link:server_admin/topics/identity-broker/social/google.adoc[Google] -.... link:server_admin/topics/identity-broker/social/facebook.adoc[Facebook] -.... link:server_admin/topics/identity-broker/social/twitter.adoc[Twitter] -.... link:server_admin/topics/identity-broker/social/github.adoc[Github] -.... link:server_admin/topics/identity-broker/social/linked-in.adoc[Linked-In] -.... link:server_admin/topics/identity-broker/social/microsoft.adoc[Microsoft] -.... link:server_admin/topics/identity-broker/social/stack-overflow.adoc[Stack Overflow] -.... link:server_admin/topics/identity-broker/social/openshift.adoc[Openshift] -... link:server_admin/topics/identity-broker/oidc.adoc[OIDC Providers] -... link:server_admin/topics/identity-broker/saml.adoc[SAML Providers] -... link:server_admin/topics/identity-broker/suggested.adoc[Client Suggested Identity Provider] -... link:server_admin/topics/identity-broker/mappers.adoc[Mapping Claims and Assertions] -... link:server_admin/topics/identity-broker/session-data.adoc[Available User Session Data] -... link:server_admin/topics/identity-broker/first-login-flow.adoc[First Login Flow] -... link:server_admin/topics/identity-broker/tokens.adoc[Retrieving External IDP Tokens] -.. link:server_admin/topics/sessions.adoc[User Session Management] -... link:server_admin/topics/sessions/administering.adoc[Administering Sessions] -... link:server_admin/topics/sessions/revocation.adoc[Revocation Policies] -... link:server_admin/topics/sessions/timeouts.adoc[Session and Token Timeouts] -... link:server_admin/topics/sessions/offline.adoc[Offline Access] -.. link:server_admin/topics/user-federation.adoc[User Storage Federation] -... link:server_admin/topics/user-federation/ldap.adoc[LDAP/AD Integration] -... link:server_admin/topics/user-federation/sssd.adoc[SSSD and FreeIPA/IdM Integration] -... link:server_admin/topics/user-federation/custom.adoc[Custom Providers] -.. link:server_admin/topics/events.adoc[Auditing and Events] -... link:server_admin/topics/events/login.adoc[Login Events] -... link:server_admin/topics/events/admin.adoc[Admin Events] -.. link:server_admin/topics/export-import.adoc[Export and Import] -.. link:server_admin/topics/account.adoc[User Account Service] -.. link:server_admin/topics/threat.adoc[Threat Model Mitigation] -... link:server_admin/topics/threat/brute-force.adoc[Password Guess, Brute Force Attacks] -... link:server_admin/topics/threat/clickjacking.adoc[Clickjacking] -... link:server_admin/topics/threat/ssl.adoc[SSL/HTTPS Requirement] -... link:server_admin/topics/threat/csrf.adoc[CSRF] -... link:server_admin/topics/threat/redirect.adoc[Unspecific Redirect URIs] -... link:server_admin/topics/threat/compromised-tokens.adoc[Compromised Access and Refresh tokens] -... link:server_admin/topics/threat/compromised-codes.adoc[Compromised Access Codes] -... link:server_admin/topics/threat/open-redirect.adoc[Open Redirectors] -... link:server_admin/topics/threat/password-db-compromised.adoc[Password database compromised] -... link:server_admin/topics/threat/scope.adoc[Limiting Scope] -... link:server_admin/topics/threat/sql.adoc[SQL Injection Attacks] -.. link:server_admin/topics/admin-cli.adoc[Admin CLI] -{% if book.community %} -.. link:server_admin/topics/MigrationFromOlderVersions.adoc[Migration from older versions] -{% endif %} diff --git a/server_admin/book-product.json b/server_admin/book-product.json deleted file mode 100644 index a64c08955a4..00000000000 --- a/server_admin/book-product.json +++ /dev/null @@ -1,45 +0,0 @@ -{ - "gitbook": "2.x.x", - "structure": { - "readme": "README.adoc" - }, - "plugins": [ - "toggle-chapters", - "ungrey", - "splitter" - ], - "variables": { - "title": "Server Administration Guide", - "project": { - "name": "Red Hat Single Sign-On", - "version": "7.1.0", - "doc_base_url": "https://access.redhat.com/documentation/en/red-hat-single-sign-on/", - "doc_info_version_url": "7.1" - }, - "community": false, - "product": true, - "images": "rhsso-images", - - "developerguide": { - "name": "Server Developer Guide", - "link": "https://access.redhat.com/documentation/en/red-hat-single-sign-on/7.1/html-single/server-developer-guide/" - - }, - "installguide": { - "name": "Server Installation and Configuration Guide", - "link": "https://access.redhat.com/documentation/en/red-hat-single-sign-on/7.1/html-single/server-installation-and-configuration-guide/" - }, - "adapterguide": { - "name": "Securing Applications and Services Guide", - "link": "https://access.redhat.com/documentation/en/red-hat-single-sign-on/7.1/html-single/securing-applications-and-services-guide/" - }, - "authorizationguide": { - "name": "Authorization Services Guide", - "link": "https://access.redhat.com/documentation/en/red-hat-single-sign-on/7.1/html-single/authorization_services_guide/" - }, - - "subsystem": { - "undertow": "urn:jboss:domain:undertow:3.1" - } - } -} diff --git a/server_admin/buildGuide.sh b/server_admin/buildGuide.sh deleted file mode 100755 index b37f0c97dd0..00000000000 --- a/server_admin/buildGuide.sh +++ /dev/null @@ -1,80 +0,0 @@ -# Build the guide - -# Find the directory name and full path -CURRENT_GUIDE=${PWD##*/} -CURRENT_DIRECTORY=$(pwd) - -usage(){ - cat <&2 - usage - exit 1;; - esac -done - -echo "" -echo "********************************************" -echo " Building $CURRENT_GUIDE " -echo "********************************************" -if [ ! -d target ]; then - echo "You must run 'python gitlab-conversion.py' to convert the content before you run this script." - exit -fi - -# Remove the guide directory path from the master.adoc file as it is not needed -echo "" -echo "***************************************************************************************" -echo "Removing the guide directory path from the master.adoc file as it is not needed." -echo "NOTE: The guide directory path should probably be removed from the SUMMARY.adoc file," -echo "but since we do not know if it will break the upstream build, we are doing this here. " -echo "If it can not be removed from the SUMMARY.adoc file, this should really be done in the " -echo "Python script because otherwise you must run this script before porting content!" -echo "***************************************************************************************" -echo "" -find . -name 'master.adoc' -print | xargs sed -i "s/include::$CURRENT_GUIDE\//include::/g" - -# Remove the html and build directories and then recreate the html/images/ directory -if [ -d target/html ]; then - rm -r target/html/ -fi -if [ -d target/html ]; then - rm -r target/html/ -fi - -mkdir -p html -cp -r target/images/ target/html/ - -echo "Building an asciidoctor version of the guide" -asciidoctor -t -dbook -a toc -o target/html/$CURRENT_GUIDE.html target/master.adoc - -echo "" -echo "Building a ccutil version of the guide" -ccutil compile --lang en_US --format html-single --main-file target/master.adoc - -cd .. - -echo "View the asciidoctor build here: " file://$CURRENT_DIRECTORY/target/html/$CURRENT_GUIDE.html - -if [ -d $CURRENT_DIRECTORY/build/tmp/en-US/html-single/ ]; then - echo "View the ccutil build here: " file://$CURRENT_DIRECTORY/build/tmp/en-US/html-single/index.html - exit 0 -else - echo -e "${RED}Build using ccutil failed!" - echo -e "${BLACK}See the log above for details." - exit 1 -fi diff --git a/server_admin/gitlab-conversion.py b/server_admin/gitlab-conversion.py deleted file mode 100755 index f2e87906cc9..00000000000 --- a/server_admin/gitlab-conversion.py +++ /dev/null @@ -1,113 +0,0 @@ -import sys, os, re, json, shutil, errno - -def transform(root, f, targetdir): - full = os.path.join(root, f) - input = open(full, 'r').read() - dir = os.path.join(targetdir, root) - if not os.path.exists(dir): - os.makedirs(dir) - output = open(os.path.join(dir, f), 'w') - input = applyTransformation(input) - output.write(input) - - -def applyTransformation(input): - for variable in re.findall(r"\{\{(.*?)\}\}", input): - tmp = variable.replace('.', '_') - input = input.replace(variable, tmp) - input = input.replace('{{', '{').replace('}}', '}') - input = re.sub(r"<}==true]\g<2>endif::[]", input) - input = re.sub(r"image:(\.\./)*", "image:", input) - input = re.sub(r"image::(\.\./)*", "image::", input) - return input - - -indir = 'topics' -targetdir = 'target' -if len(sys.argv) > 1: - targetdir = sys.argv[1] - -if os.path.exists(targetdir): - shutil.rmtree(targetdir) - -if os.path.isdir('images'): - shutil.copytree('images',os.path.join(targetdir, 'images')) -if os.path.isdir('keycloak-images'): - shutil.copytree('keycloak-images',os.path.join(targetdir, 'keycloak-images')) -if os.path.isdir('rhsso-images'): - shutil.copytree('rhsso-images',os.path.join(targetdir, 'rhsso-images')) - -shutil.copyfile('metadata.ini', os.path.join(targetdir, 'metadata.ini')); -shutil.copyfile('master-docinfo.xml', os.path.join(targetdir, 'master-docinfo.xml')); - -tmp = os.path.join(targetdir, 'topics') -if not os.path.exists(tmp): - os.makedirs(tmp) - -# transform files -for root, dirs, filenames in os.walk(indir): - for f in filenames: - transform(root,f,targetdir) - -# Create master.doc includes -input = open('SUMMARY.adoc', 'r').read() -output = open(os.path.join(targetdir, 'master.adoc'), 'w') - -output.write(""" -:toc: -:toclevels: 3 -:numbered: - -include::document-attributes.adoc[] -""") - -input = re.sub(r"[ ]*\.+\s*link:[^/]+/(.*)\[(.*)\]", "include::\g<1>[]", input) -input = applyTransformation(input) -output.write(input) - -# parse book-product.json file and create document attributes -with open('book-product.json') as data_file: - data = json.load(data_file) - -variables = data['variables'] - -def makeAttributes(variables, variable, list): - for i in variables.keys(): - if variable is None: - tmp = i - else: - tmp = variable + '_' + i - if isinstance(variables[i],dict): - makeAttributes(variables[i], tmp, list) - elif isinstance(variables[i],bool): - boolval = 'false' - if variables[i]: - boolval = 'true' - list.append({tmp: boolval}) - else: - list.append({tmp: str(variables[i])}) - - -attributeList = [] -makeAttributes(variables, None, attributeList) - -output = open(os.path.join(targetdir, 'document-attributes.adoc'), 'w') -for attribute in attributeList: - for k in attribute.keys(): - output.write(':book_' + k + ": " + attribute[k] + "\n") - -print "Transformation complete!" - - - - - - - - - diff --git a/server_admin/index.adoc b/server_admin/index.adoc new file mode 100644 index 00000000000..7e6c6cf73db --- /dev/null +++ b/server_admin/index.adoc @@ -0,0 +1,6 @@ +:toc: +:toclevels: 3 +:numbered: + +include::../document-attributes-community.adoc[] +include::topics.adoc[] \ No newline at end of file diff --git a/server_admin/master-docinfo.xml b/server_admin/master-docinfo.xml old mode 100755 new mode 100644 index f25f7d43d26..01c9b455fde --- a/server_admin/master-docinfo.xml +++ b/server_admin/master-docinfo.xml @@ -1,10 +1,10 @@ -{book_project_name} -{book_project_doc_info_version_url} -For Use with {book_project_name} {book_project_doc_info_version_url} -{book_title} +{project_name} +{project_doc_info_version_url} +For Use with {project_name} {project_doc_info_version_url} +{title} {doc_info_version_url} - This guide consists of information for administrators to configure {book_project_name} {book_project_doc_info_version_url} + This guide consists of information for administrators to configure {project_name} {project_doc_info_version_url} Red Hat Customer Content Services diff --git a/server_admin/master.adoc b/server_admin/master.adoc new file mode 100644 index 00000000000..cc0fdffa8d3 --- /dev/null +++ b/server_admin/master.adoc @@ -0,0 +1,6 @@ +:toc: +:toclevels: 3 +:numbered: + +include::../document-attributes-product.adoc[] +include::topics.adoc[] \ No newline at end of file diff --git a/server_admin/pom.xml b/server_admin/pom.xml new file mode 100644 index 00000000000..7254c0cd1c3 --- /dev/null +++ b/server_admin/pom.xml @@ -0,0 +1,29 @@ + + + 4.0.0 + + + org.keycloak.documentation + documentation-parent + 1.0.0-SNAPSHOT + ../ + + + Server Administration + server-admin + pom + + + + + org.asciidoctor + asciidoctor-maven-plugin + + + asciidoc-to-html + + + + + + diff --git a/server_admin/topics.adoc b/server_admin/topics.adoc new file mode 100644 index 00000000000..65da536ee65 --- /dev/null +++ b/server_admin/topics.adoc @@ -0,0 +1,111 @@ +include::topics/overview.adoc[] +include::topics/overview/features.adoc[] +include::topics/overview/how.adoc[] +include::topics/overview/concepts.adoc[] +include::topics/initialization.adoc[] +include::topics/admin-console.adoc[] +include::topics/realms/master.adoc[] +include::topics/realms/create.adoc[] +include::topics/realms/ssl.adoc[] +include::topics/realms/cache.adoc[] +include::topics/realms/email.adoc[] +include::topics/realms/themes.adoc[] +include::topics/users.adoc[] +include::topics/users/viewing.adoc[] +include::topics/users/create-user.adoc[] +include::topics/users/attributes.adoc[] +include::topics/users/credentials.adoc[] +include::topics/users/required-actions.adoc[] +include::topics/users/impersonation.adoc[] +include::topics/users/user-registration.adoc[] +include::topics/users/recaptcha.adoc[] +include::topics/login-settings.adoc[] +include::topics/login-settings/forgot-password.adoc[] +include::topics/login-settings/remember-me.adoc[] +include::topics/authentication.adoc[] +include::topics/authentication/password-policies.adoc[] +include::topics/authentication/otp-policies.adoc[] +include::topics/authentication/flows.adoc[] +include::topics/authentication/kerberos.adoc[] +include::topics/authentication/x509.adoc[] +include::topics/sso-protocols.adoc[] +include::topics/sso-protocols/oidc.adoc[] +include::topics/sso-protocols/saml.adoc[] +include::topics/sso-protocols/saml-vs-oidc.adoc[] +include::topics/sso-protocols/docker.adoc[] +include::topics/clients.adoc[] +include::topics/clients/client-oidc.adoc[] +include::topics/clients/oidc/confidential.adoc[] +include::topics/clients/oidc/service-accounts.adoc[] +include::topics/clients/client-saml.adoc[] +include::topics/clients/saml/idp-initiated-login.adoc[] +include::topics/clients/saml/entity-descriptors.adoc[] +include::topics/clients/client-link.adoc[] +include::topics/clients/protocol-mappers.adoc[] +include::topics/clients/installation.adoc[] +include::topics/clients/client-templates.adoc[] +include::topics/roles.adoc[] +include::topics/roles/realm-roles.adoc[] +include::topics/roles/client-roles.adoc[] +include::topics/roles/composite.adoc[] +include::topics/roles/user-role-mappings.adoc[] +include::topics/roles/user-role-mappings/default-roles.adoc[] +include::topics/roles/client-scope.adoc[] +include::topics/groups.adoc[] +include::topics/groups/groups-vs-roles.adoc[] +include::topics/groups/default-groups.adoc[] +include::topics/admin-console-permissions.adoc[] +include::topics/admin-console-permissions/master-realm.adoc[] +include::topics/admin-console-permissions/per-realm.adoc[] +include::topics/admin-console-permissions/fine-grain.adoc[] +include::topics/realms/keys.adoc[] +include::topics/identity-broker.adoc[] +include::topics/identity-broker/overview.adoc[] +include::topics/identity-broker/default-provider.adoc[] +include::topics/identity-broker/configuration.adoc[] +include::topics/identity-broker/social-login.adoc[] +include::topics/identity-broker/social/google.adoc[] +include::topics/identity-broker/social/facebook.adoc[] +include::topics/identity-broker/social/twitter.adoc[] +include::topics/identity-broker/social/github.adoc[] +include::topics/identity-broker/social/linked-in.adoc[] +include::topics/identity-broker/social/microsoft.adoc[] +include::topics/identity-broker/social/stack-overflow.adoc[] +include::topics/identity-broker/social/openshift.adoc[] +include::topics/identity-broker/oidc.adoc[] +include::topics/identity-broker/saml.adoc[] +include::topics/identity-broker/suggested.adoc[] +include::topics/identity-broker/mappers.adoc[] +include::topics/identity-broker/session-data.adoc[] +include::topics/identity-broker/first-login-flow.adoc[] +include::topics/identity-broker/tokens.adoc[] +include::topics/sessions.adoc[] +include::topics/sessions/administering.adoc[] +include::topics/sessions/revocation.adoc[] +include::topics/sessions/timeouts.adoc[] +include::topics/sessions/offline.adoc[] +include::topics/user-federation.adoc[] +include::topics/user-federation/ldap.adoc[] +include::topics/user-federation/sssd.adoc[] +include::topics/user-federation/custom.adoc[] +include::topics/events.adoc[] +include::topics/events/login.adoc[] +include::topics/events/admin.adoc[] +include::topics/export-import.adoc[] +include::topics/account.adoc[] +include::topics/threat.adoc[] +include::topics/threat/brute-force.adoc[] +include::topics/threat/clickjacking.adoc[] +include::topics/threat/ssl.adoc[] +include::topics/threat/csrf.adoc[] +include::topics/threat/redirect.adoc[] +include::topics/threat/compromised-tokens.adoc[] +include::topics/threat/compromised-codes.adoc[] +include::topics/threat/open-redirect.adoc[] +include::topics/threat/password-db-compromised.adoc[] +include::topics/threat/scope.adoc[] +include::topics/threat/sql.adoc[] +include::topics/admin-cli.adoc[] +ifeval::[{project_community}==true] +include::topics/MigrationFromOlderVersions.adoc[] +endif::[] diff --git a/server_admin/topics/License.adoc b/server_admin/topics/License.adoc old mode 100755 new mode 100644 diff --git a/server_admin/topics/MigrationFromOlderVersions.adoc b/server_admin/topics/MigrationFromOlderVersions.adoc index f7124ef5bd4..e8c6f622963 100644 --- a/server_admin/topics/MigrationFromOlderVersions.adoc +++ b/server_admin/topics/MigrationFromOlderVersions.adoc @@ -75,7 +75,7 @@ tags under the keycloak subsystem. Before migration, your keycloak subsystem sh ---- -The jboss-cli tool is discussed in detail in link:{{book.installguide.link}}[{{book.installguide.name}}]. +The jboss-cli tool is discussed in detail in link:{installguide_link}[{installguide_name}]. ==== migrate-json in Standalone Mode @@ -216,8 +216,8 @@ to use the more secure hashing algorithm. ===== ID Token requires scope=openid -OpenID Connect specification requires that parameter `scope` with value `openid` is used in initial authorization request. So in {{book.project.name}} -2.1.0 we changed our adapters to use `scope=openid` in the redirect URI to {{book.project.name}}. Now we changed the server part too and ID token +OpenID Connect specification requires that parameter `scope` with value `openid` is used in initial authorization request. So in {project_name} +2.1.0 we changed our adapters to use `scope=openid` in the redirect URI to {project_name}. Now we changed the server part too and ID token will be sent to the application just if `scope=openid` is really used. If it's not used, then ID token will be skipped and just Access token and Refresh token will be sent to the application. This also allows that you can ommit the generation of ID Token on purpose - for example for space or performance purposes. @@ -253,9 +253,9 @@ Finally we added some new timeouts to the admin console. This allows you for exa ===== Migration of old offline tokens If you migrate from version 2.2.0 or older and you used offline tokens, then your offline tokens didn't have KID in the token header. -We added KID to the token header in 2.3.0 together with the ability to have multiple realm keys, so {{book.project.name}} is able to find the correct key based on the token KID. +We added KID to the token header in 2.3.0 together with the ability to have multiple realm keys, so {project_name} is able to find the correct key based on the token KID. -For the offline tokens without KID, {{book.project.name}} 2.5.1 will always use the active realm key to find the proper key for the token verification. In other words, migration of old +For the offline tokens without KID, {project_name} 2.5.1 will always use the active realm key to find the proper key for the token verification. In other words, migration of old offline tokens will work. So for example, your user requested offline token in 1.9.8, then you migrate from 1.9.8 to 2.5.1 and then your user will be still able to refresh his old offline token in 2.5.1 version. @@ -285,13 +285,13 @@ APIs in keycloak-server-spi-private between minor releases. Key in SAML assertions and documents are now encrypted using RSA-OAEP encryption scheme. If you want to use encrypted assertions, make sure that service providers understand this encryption scheme. -In the unlikely case that SP would not be able to handle the new scheme, {{book.project.name}} +In the unlikely case that SP would not be able to handle the new scheme, {project_name} can be made to use legacy RSA-v1.5 encryption scheme when started with system property `keycloak.saml.key_trans.rsa_v1.5` set to `true`. ===== Infinispan caches realms and users are always local -Even if you use {{book.project.name}} in cluster, the caches `realms` and `users` defined in infinispan subsystem in `standalone-ha.xml` are +Even if you use {project_name} in cluster, the caches `realms` and `users` defined in infinispan subsystem in `standalone-ha.xml` are always local caches now. There is separate cache `work`, which handles sending invalidation messages between cluster nodes and informing whole cluster what records in underlying `realms` and `users` caches should be invalidated. diff --git a/server_admin/topics/account.adoc b/server_admin/topics/account.adoc index 44297217611..79914bf4014 100644 --- a/server_admin/topics/account.adoc +++ b/server_admin/topics/account.adoc @@ -2,45 +2,45 @@ == 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, +{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 -image:../{{book.images}}/account-service-profile.png[] +image:{project_images}/account-service-profile.png[] The initial page is the user's profile, which is the `Account` left menu item. This is where they specify basic data about themselves. This screen can be extended -to allow the user to manage additional attributes. See the link:{{book.developerguide.link}}[{{book.developerguide.name}}] for more details. +to allow the user to manage additional attributes. See the link:{developerguide_link}[{developerguide_name}] for more details. The `Password` left menu item allows the user to change their password. .Password Update -image:../{{book.images}}/account-service-password.png[] +image:{project_images}/account-service-password.png[] The `Authenticator` menu item allows the user to set up OTP if they desire. This will only show up if OTP is a valid authentication mechanism for your realm. Users are given directions to install https://fedorahosted.org/freeotp/[FreeOTP] or https://play.google.com/store/apps/details?id=com.google.android.apps.authenticator2[Google Authenticator] on their mobile device to be their OTP generator. The QR code you see in the screen shot can be scanned into the FreeOTP or Google Authenticator mobile application for nice and easy setup. .OTP Authenticator -image:../{{book.images}}/account-service-authenticator.png[] +image:{project_images}/account-service-authenticator.png[] -The `Federated Identity` menu item allows the user to link their account with an <> (this is usually used to link social provider +The `Federated Identity` menu item allows the user to link their account with an <<_identity_broker, identity broker>> (this is usually used to link social provider accounts together). This will show the list of external identity providers you have configured for your realm. .Federated Identity -image:../{{book.images}}/account-service-federated-identity.png[] +image:{project_images}/account-service-federated-identity.png[] The `Sessions` menu item allows the user to view and manage which devices are logged in and from where. They can perform logout of these sessions from this screen too. .Sessions -image:../{{book.images}}/account-service-sessions.png[] +image:{project_images}/account-service-sessions.png[] The `Applications` menu item shows users which applications they have access to. .Applications -image:../{{book.images}}/account-service-apps.png[] +image:{project_images}/account-service-apps.png[] === Themeable -Like all UIs in {{book.project.name}}, the User Account Service is completely themeable and internationalizable. -See the link:{{book.developerguide.link}}[{{book.developerguide.name}}] for more details. +Like all UIs in {project_name}, the User Account Service is completely themeable and internationalizable. +See the link:{developerguide_link}[{developerguide_name}] for more details. diff --git a/server_admin/topics/admin-cli.adoc b/server_admin/topics/admin-cli.adoc index fb65510dd0a..cefa517ca6a 100644 --- a/server_admin/topics/admin-cli.adoc +++ b/server_admin/topics/admin-cli.adoc @@ -1,21 +1,21 @@ == Admin CLI -{% if book.product %} +ifeval::[{project_product}==true] NOTE: Admin CLI is a Technology Preview feature and is not fully supported. -{% endif %} +endif::[] -In previous chapters we have described how to use the {{book.project.name}} Admin Console to perform administrative tasks. +In previous chapters we have described how to use the {project_name} Admin Console to perform administrative tasks. All those tasks can also be performed from command line by using Admin CLI command line tool. === Installing Admin CLI -Admin CLI is packaged inside {{book.project.name}} Server distribution. You can find execution scripts inside `bin` directory. +Admin CLI is packaged inside {project_name} Server distribution. You can find execution scripts inside `bin` directory. The Linux script is called `kcadm.sh`, and the one for Windows is called `kcadm.bat`. -In order to setup the client to be used from any location on the filesystem you may want to add {{book.project.name}} server directory to your PATH. +In order to setup the client to be used from any location on the filesystem you may want to add {project_name} server directory to your PATH. On Linux: @@ -51,7 +51,7 @@ Or on Windows: c:\> set /p CID= kcadm get clients/%CID%/installation/providers/keycloak-oidc-keycloak-json -In a production environment {{book.project.name}} has to be accessed with `https:` to avoid exposing tokens to network sniffers. If server's +In a production environment {project_name} has to be accessed with `https:` to avoid exposing tokens to network sniffers. If server's certificate is not issued by one of the trusted CAs that are included in Java's default certificate truststore, then you will need to prepare a truststore.jks file, and instruct `Admin CLI` to use it. @@ -86,7 +86,7 @@ associated refresh token, possibly other secrets as well in a private configurat and is located under user's home directory - it's full pathname is `$HOME/.keycloak/kcadm.config` (on Windows it's `%HOMEPATH%\.keycloak\kcadm.config`). The file can be named something else by using `-c, --config` option. -See <> for more info on configuration file. +See <<_working_with_alternative_configurations, next chapter>> for more info on configuration file. Another approach is to authenticate with each command invocation for the duration of that invocation only. This approach results in more load on the server, and more time spent with round-trips obtaining tokens, but has a benefit of not needing to save any diff --git a/server_admin/topics/admin-console-permissions.adoc b/server_admin/topics/admin-console-permissions.adoc old mode 100755 new mode 100644 index df1e5a8d00f..fdb4bf617cf --- a/server_admin/topics/admin-console-permissions.adoc +++ b/server_admin/topics/admin-console-permissions.adoc @@ -2,6 +2,6 @@ == Admin Console Access Control and Permissions -Each realm created on the {{book.project.name}} has a dedicated Admin Console from which that realm can be managed. +Each realm created on the {project_name} has a dedicated Admin Console from which that realm can be managed. The `master` realm is a special realm that allows admins to manage more than one realm on the system. You can also define fine-grained access to users in different realms to manage the server. This chapter goes over all the scenarios for this. diff --git a/server_admin/topics/admin-console-permissions/fine-grain.adoc b/server_admin/topics/admin-console-permissions/fine-grain.adoc index 1c2d05e95b9..2bc090d81ce 100644 --- a/server_admin/topics/admin-console-permissions/fine-grain.adoc +++ b/server_admin/topics/admin-console-permissions/fine-grain.adoc @@ -3,7 +3,7 @@ === Fine Grain Admin Permissions Sometimes roles like `manage-realm` or `manage-users` are too coarse grain and you want to create -restricted admin accounts that have more fine grain permissions. {{book.project.name}} allows you to define +restricted admin accounts that have more fine grain permissions. {project_name} allows you to define and assign restricted access policies for managing a realm. Things like: * Managing one specific client @@ -18,8 +18,8 @@ and assign restricted access policies for managing a realm. Things like: There's some important things to note about fine grain admin permissions: -* Fine grain admin permissions were implemented on top of link:{{book.authorizationguide.link}}[Authorization Services]. It is highly recommended that you read up on those features before diving into fine grain permissions. -* Fine grain permissions are only available within <> and admins defined within those realms. You cannot define cross-realm fine grain permissions. +* Fine grain admin permissions were implemented on top of link:{authorizationguide_link}[Authorization Services]. It is highly recommended that you read up on those features before diving into fine grain permissions. +* Fine grain permissions are only available within <<_per_realm_admin_permissions, dedicated admin consoles>> and admins defined within those realms. You cannot define cross-realm fine grain permissions. * Fine grain permissions are used to grant additional permissions. You cannot override the default behavior of the built in admin roles. @@ -38,12 +38,12 @@ The first thing we must do is login to the Admin Console so we can set up permis of the client we want to define fine-grain permissions for. .Client Management -image:../../{{book.images}}/fine-grain-client.png[] +image:{project_images}/fine-grain-client.png[] You should see a tab menu item called `Permissions`. Click on that tab. .Client Permissions Tab -image:../../{{book.images}}/fine-grain-client-permissions-tab-off.png[] +image:{project_images}/fine-grain-client-permissions-tab-off.png[] By default, each client is not enabled to do fine grain permissions. So turn the `Permissions Enabled` switch to on to initialize permissions. @@ -51,16 +51,16 @@ to initialize permissions. IMPORTANT: If you turn the `Permissions Enabled` switch to off, it will delete any and all permissions you have defined for this client. .Client Permissions Tab -image:../../{{book.images}}/fine-grain-client-permissions-tab-on.png[] +image:{project_images}/fine-grain-client-permissions-tab-on.png[] When you witch `Permissions Enabled` to on, it initializes various permission objects behind the scenes -using link:{{book.authorizationguide.link}}[Authorization Services]. For this example, we're +using link:{authorizationguide_link}[Authorization Services]. For this example, we're interested in the `manage` permission for the client. Clicking on that will redirect you to the permission that handles the `manage` permission for the client. All authorization objects are contained in the `realm-management` client's `Authorization` tab. .Client Manage Permission -image:../../{{book.images}}/fine-grain-client-manage-permissions.png[] +image:{project_images}/fine-grain-client-manage-permissions.png[] When first initialized the `manage` permission does not have any policies associated with it. You will need to create one by going to the policy tab. To get there fast, click on @@ -71,13 +71,13 @@ you can define. You can define a policy that is associated with a role or a gro rules in Javascript. For this simple example, we're going to create a `User Policy`. .User Policy -image:../../{{book.images}}/fine-grain-client-user-policy.png[] +image:{project_images}/fine-grain-client-user-policy.png[] This policy will match a hard-coded user in the user database. In this case it is the `sales-admin` user. We must then go back to the `sales-application` client's `manage` permission page and assign the policy to the permission object. .Assign User Policy -image:../../{{book.images}}/fine-grain-client-assign-user-policy.png[] +image:{project_images}/fine-grain-client-assign-user-policy.png[] The `sales-admin` user can now has permission to manage the `sales-application` client. @@ -85,7 +85,7 @@ There's one more thing we have to do. Go to the `Role Mappings` tab and assign role to the `sales-admin`. .Assign query-clients -image:../../{{book.images}}/fine-grain-assign-query-clients.png[] +image:{project_images}/fine-grain-assign-query-clients.png[] Why do you have to do this? This role tells the Admin Console @@ -96,11 +96,11 @@ IMPORTANT If you do not set the `query-clients` role, restricted admins like `sa ===== Testing It Out. -Next we log out of the master realm and and re-login to the <> for the `test` realm +Next we log out of the master realm and and re-login to the <<_per_realm_admin_permissions, dedicated admin console>> for the `test` realm using the `sales-admin` as a username. This is located under `/auth/admin/test/console`. .Sales Admin Login -image:../../{{book.images}}/fine-grain-sales-admin-login.png[] +image:{project_images}/fine-grain-sales-admin-login.png[] This admin is now able to manage this one client. @@ -116,26 +116,26 @@ and not perform any other types of user administration. The `sales-application` has defined three different client roles. .Sales Application Roles -image:../../{{book.images}}/fine-grain-sales-application-roles.png[] +image:{project_images}/fine-grain-sales-application-roles.png[] We want the `sales-admin` user to be able to map these roles to any user in the system. The first step to do this is to allow the role to be mapped by the admin. If we click on the `viewLeads` role, you'll see that there is a `Permissions` tab for this role. .View Leads Role Permission Tab -image:../../{{book.images}}/fine-grain-view-leads-role-tab.png[] +image:{project_images}/fine-grain-view-leads-role-tab.png[] If we click on that tab and turn the `Permissions Enabled` on, you'll see that there are a number of actions we can apply policies to. .View Leads Permissions -image:../../{{book.images}}/fine-grain-view-leads-permissions.png[] +image:{project_images}/fine-grain-view-leads-permissions.png[] The one we are interested in is `map-role`. Click on this permission and add the same User Policy that was created in the earlier example. .Map-roles Permission -image:../../{{book.images}}/fine-grain-map-roles-permission.png[] +image:{project_images}/fine-grain-map-roles-permission.png[] What we've done is say that the `sales-admin` can map the `viewLeads` role. What we have not done is specify which users the admin is allowed to map this role too. To do that @@ -144,7 +144,7 @@ we must go to the `Users` section of the admin console for this realm. Clicking `Permissions` tab. Click on that and enable it. .Users Permissions -image:../../{{book.images}}/fine-grain-users-permissions.png[] +image:{project_images}/fine-grain-users-permissions.png[] The permission we are interested in is `map-roles`. This is a restrictive policy in that it only allows admins the ability to map roles to a user. If we click on the @@ -155,12 +155,12 @@ The last thing we have to do is add the `view-users` role to the `sales-admin`. allow the admin to view users in the realm he wants to add the `sales-application` roles to. .Add view-users -image:../../{{book.images}}/fine-grain-add-view-users.png[] +image:{project_images}/fine-grain-add-view-users.png[] ===== Testing It Out. -Next we log out of the master realm and and re-login to the <> for the `test` realm +Next we log out of the master realm and and re-login to the <<_per_realm_admin_permissions, dedicated admin console>> for the `test` realm using the `sales-admin` as a username. This is located under `/auth/admin/test/console`. You will see that now the `sales-admin` can view users in the system. If you select one of the @@ -169,7 +169,7 @@ Going to these tab you'll find that there are no `Available` roles for the admin map to the user except when we browse the `sales-application` roles. .Add viewLeads -image:../../{{book.images}}/fine-grain-add-view-leads.png[] +image:{project_images}/fine-grain-add-view-leads.png[] We've only specified that the `sales-admin` can map the `viewLeads` role. @@ -181,7 +181,7 @@ by a client. If we log back into the admin console to our master realm admin an to the `sales-application` permissions page, you'll see the `map-roles` permission. .Client map-roles Permission -image:../../{{book.images}}/fine-grain-client-permissions-tab-on.png[] +image:{project_images}/fine-grain-client-permissions-tab-on.png[] If you grant access to this particular parmission to an admin, that admin will be able map any role defined by the client. @@ -193,7 +193,7 @@ page in the Admin Console you will see a `Permissions` tab. Clicking on that an fine grain permissions for the group will get you to something like this: .Group Permissions Tab -image:../../{{book.images}}/fine-grain-group-permissions-tab-on.png[] +image:{project_images}/fine-grain-group-permissions-tab-on.png[] In this screenshot, the group we are defining permissions for is `sales`. The `manage-members` permission allows you to define policies that allow an admin to diff --git a/server_admin/topics/admin-console-permissions/master-realm.adoc b/server_admin/topics/admin-console-permissions/master-realm.adoc index 5a8855860c2..95a561f659d 100644 --- a/server_admin/topics/admin-console-permissions/master-realm.adoc +++ b/server_admin/topics/admin-console-permissions/master-realm.adoc @@ -1,9 +1,9 @@ === Master Realm Access Control -The `master` realm in {{book.project.name}} is a special realm and treated differently than other realms. -Users in the {{book.project.name}} `master` realm can be granted permission to manage zero or more realms that are deployed on the {{book.project.name}} server. -When a realm is created, {{book.project.name}} automatically creates various roles that grant fine-grain permissions to access that new realm. +The `master` realm in {project_name} is a special realm and treated differently than other realms. +Users in the {project_name} `master` realm can be granted permission to manage zero or more realms that are deployed on the {project_name} server. +When a realm is created, {project_name} automatically creates various roles that grant fine-grain permissions to access that new realm. Access to The Admin Console and Admin REST endpoints can be controlled by mapping these roles to users in the `master` realm. It's possible to create multiple super users, as well as users that can only manage specific realms. @@ -21,7 +21,7 @@ are allowed to create new realms. They will be granted full access to any new r ==== Realm Specific Roles Admin users within the `master` realm can be granted management privileges to one or more other realms in the system. -Each realm in {{book.project.name}} is represented by a client in the `master` realm. +Each realm in {project_name} is represented by a client in the `master` realm. The name of the client is `-realm`. These clients each have client-level roles defined which define varying level of access to manage an individual realm. diff --git a/server_admin/topics/admin-console.adoc b/server_admin/topics/admin-console.adoc index 813ab69866f..4d0a05648c9 100644 --- a/server_admin/topics/admin-console.adoc +++ b/server_admin/topics/admin-console.adoc @@ -1,17 +1,17 @@ == Admin Console -The bulk of your administrative tasks will be done through the {{book.project.name}} Admin Console. +The bulk of your administrative tasks will be done through the {project_name} Admin Console. You can go to the console url directly at http://localhost:8080/auth/admin/ .Login Page -image:../{{book.images}}/login-page.png[] +image:{project_images}/login-page.png[] Enter the username and password you created on the Welcome Page or the `add-user-keycloak` script in the bin directory. -This will bring you to the {{book.project.name}} Admin Console. +This will bring you to the {project_name} Admin Console. .Admin Console -image:../{{book.images}}/admin-console.png[] +image:{project_images}/admin-console.png[] The left drop down menu allows you to pick a realm you want to manage or to create a new one. The right drop down menu allows you to view your user account or logout. If you are curious about a certain feature, button, or field within the Admin Console, simply hover your mouse diff --git a/server_admin/topics/authentication/flows.adoc b/server_admin/topics/authentication/flows.adoc index 2e0b676e97a..4baea691326 100644 --- a/server_admin/topics/authentication/flows.adoc +++ b/server_admin/topics/authentication/flows.adoc @@ -3,13 +3,13 @@ === Authentication Flows An _authentication flow_ is a container for all authentications, screens, and actions that must happen during login, registration, and other -{{book.project.name}} workflows. +{project_name} workflows. If you go to the admin console `Authentication` left menu item and go to the `Flows` tab, you can view all the defined flows in the system and what actions and checks each flow requires. This section does a walk through of the browser login flow. In the left drop down list select `browser` to come to the screen shown below: .Browser Flow -image:../../{{book.images}}/browser-flow.png[] +image:{project_images}/browser-flow.png[] If you hover over the tooltip (the tiny question mark) to the right of the flow selection list, this will describe what the flow is and does. @@ -46,7 +46,7 @@ This is better described in an example. Let's walk through the `browser` authen This is marked as _optional_. If the user has OTP set up, then this authentication type must run and be successful. If the user doesn't have OTP set up, this authentication type is ignored. -{% if book.community %} +ifeval::[{project_community}==true] === Executions Executions can be used @@ -97,4 +97,4 @@ function authenticate(context) { context.success(); } ---- -{% endif %} +endif::[] diff --git a/server_admin/topics/authentication/kerberos.adoc b/server_admin/topics/authentication/kerberos.adoc index a2b9538e86b..f440cafa851 100644 --- a/server_admin/topics/authentication/kerberos.adoc +++ b/server_admin/topics/authentication/kerberos.adoc @@ -2,31 +2,31 @@ === Kerberos -{{book.project.name}} supports login with a Kerberos ticket through the SPNEGO protocol. +{project_name} supports login with a Kerberos ticket through the SPNEGO protocol. SPNEGO (Simple and Protected GSSAPI Negotiation Mechanism) is used to authenticate transparently through the web browser after the user 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. +For non-web cases or when ticket is not available during login, {project_name} also supports login with Kerberos username/password. 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 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` -. In case that the browser has Kerberos ticket from desktop login, it transfers the desktop sign on information to the {{book.project.name}} +. User then uses his browser (IE/Firefox/Chrome) to access a web application secured by {project_name}. +. Application redirects to {project_name} login. +. {project_name} renders HTML login screen together with status 401 and HTTP header `WWW-Authenticate: Negotiate` +. In case that the browser has Kerberos ticket from desktop login, it transfers the desktop sign on information to the {project_name} in header `Authorization: Negotiate 'spnego-token'` . Otherwise it just displays the login screen. -. {{book.project.name}} validates token from the browser and authenticates the user. +. {project_name} validates token from the browser and authenticates the user. It provisions user data from LDAP (in case of LDAPFederationProvider with Kerberos authentication support) or let user to update his profile and prefill data (in case of KerberosFederationProvider). -. {{book.project.name}} returns back to the application. - Communication between {{book.project.name}} and application happens through OpenID Connect or SAML messages. - 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. +. {project_name} returns back to the application. + Communication between {project_name} and application happens through OpenID Connect or SAML messages. + The fact that {project_name} was authenticated through Kerberos is hidden from the application. + So {project_name} acts as broker to Kerberos/SPNEGO login. For setup there are 3 main parts: . Setup and configuration of Kerberos server (KDC) -. Setup and configuration of {{book.project.name}} server +. Setup and configuration of {project_name} server . Setup and configuration of client machines ==== Setup of Kerberos server @@ -40,7 +40,7 @@ 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. * 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` + For example if your {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. @@ -59,9 +59,9 @@ 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. +The Keytab file `/tmp/http.keytab` will need to be accessible on the host where {project_name} server will be running. -==== Setup and configuration of {{book.project.name}} server +==== Setup and configuration of {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. @@ -75,44 +75,44 @@ For the example realm MYDOMAIN.ORG you may configure the `domain_realm` section 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. +Next you need to export the keytab file with the HTTP principal and make sure the file is accessible to the process under which {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, +For the MIT Kerberos example above, we already exported keytab to `/tmp/http.keytab` . If your KDC and {project_name} are running on same host, you have that file already available. ===== Enable SPNEGO Processing -{{book.project.name}} does not have the SPNEGO protocol support turned on by default. So, you have to go to the <> +{project_name} does not have the SPNEGO protocol support turned on by default. So, you have to go to the <<_authentication-flows, browser flow>> and enable `Kerberos`. .Browser Flow -image:../../{{book.images}}/browser-flow.png[] +image:{project_images}/browser-flow.png[] Switch the `Kerberos` requirement from _disabled_ to either _alternative_ or _required_. _Alternative_ basically means that Kerberos is optional. If -the user's browser hasn't been configured to work with SPNEGO/Kerberos, then {{book.project.name}} will fall back to the regular login screens. If you set the requirement +the user's browser hasn't been configured to work with SPNEGO/Kerberos, then {project_name} will fall back to the regular login screens. If you set the requirement to _required_ then all users must have Kerberos enabled for their browser. ===== Configure Kerberos User Storage Federation Provider -Now that the SPNEGO protocol is turned on at the authentication server, you'll need to configure how {{book.project.name}} interprets the Kerberos ticket. -This is done through <>. We have 2 different federation providers with Kerberos authentication support. +Now that the SPNEGO protocol is turned on at the authentication server, you'll need to configure how {project_name} interprets the Kerberos ticket. +This is done through <<_user-storage-federation,User Storage Federation>>. We have 2 different federation providers with Kerberos authentication support. -If you want to authenticate with Kerberos backed by an LDAP server, you have to first configure the <>. +If you want to authenticate with Kerberos backed by an LDAP server, you have to first configure the <<_ldap, LDAP Federation Provider>>. If you look at the configuration page for your LDAP provider you'll see a `Kerberos Integration` section. .LDAP Kerberos Integration -image:../../{{book.images}}/ldap-kerberos.png[] +image:{project_images}/ldap-kerberos.png[] -Turning on the switch `Allow Kerberos authentication` will make {{book.project.name}} use the Kerberos principal to lookup information about the user so that it can -be imported into the {{book.project.name}} environment. +Turning on the switch `Allow Kerberos authentication` will make {project_name} use the Kerberos principal to lookup information about the user so that it can +be imported into the {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 `Add provider` select box. .Kerberos User Storage Provider -image:../../{{book.images}}/kerberos-provider.png[] +image:{project_images}/kerberos-provider.png[] -This provider parses the Kerberos ticket for simple principal information and does a small import into the local {{book.project.name}} database. +This provider parses the Kerberos ticket for simple principal information and does a small import into the local {project_name} database. User profile information like first name, last name, and email are not provisioned. ==== Setup and configuration of client machines @@ -124,36 +124,36 @@ URI `.mydomain.org` must be allowed in the `network.negotiate-auth.trusted-uris` 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 %} +ifeval::[{project_community}==true] ==== Example setups For easier testing with Kerberos, we provided some example setups to test. -===== {{book.project.name}} and FreeIPA docker image +===== {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}} +FreeIPA provides integrated security solution with MIT Kerberos and 389 LDAP server among other things . The image provides also {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] . ===== ApacheDS testing Kerberos server For quick testing and unit tests, we use a very simple http://directory.apache.org/apacheds/[ApacheDS] Kerberos server. -You need to build {{book.project.name}} from sources and then run the Kerberos server with maven-exec-plugin from our testsuite. +You need to build {project_name} from sources and then run the Kerberos server with maven-exec-plugin from our testsuite. See details https://github.com/keycloak/keycloak/blob/master/misc/Testsuite.md#kerberos-server[here] . -{% endif %} +endif::[] ==== Credential Delegation Kerberos 5 supports the concept of credential delegation. In this scenario, your applications may want access to the Kerberos ticket so that -they can re-use it to interact with other services secured by Kerberos. Since the SPNEGO protocol is processed in the {{book.project.name}} server, +they can re-use it to interact with other services secured by Kerberos. Since the SPNEGO protocol is processed in the {project_name} server, you have to propagate the GSS credential to your application -within the OpenID Connect token claim or a SAML assertion attribute that is transmitted to your application from the {{book.project.name}} server. +within the OpenID Connect token claim or a SAML assertion attribute that is transmitted to your application from the {project_name} server. To have this claim inserted into the token or assertion, each application will need to enable the built-in protocol mapper called `gss delegation credential`. This is enabled in the `Mappers` tab of the application's -client page. See <> chapter for more details. +client page. See <<_protocol-mappers, Protocol Mappers>> chapter for more details. -Applications will need to deserialize the claim it receives from {{book.project.name}} before it can use it to make GSS calls against other services. +Applications will need to deserialize the claim it receives from {project_name} before it can use it to make GSS calls against other services. Once you deserialize the credential from the access token to the GSSCredential object, the GSSContext will need to be created with this credential passed to the method `GSSManager.createContext` for example like this: @@ -175,11 +175,11 @@ GSSContext context = gssManager.createContext(serviceName, krb5Oid, deserializedGssCredential, GSSContext.DEFAULT_LIFETIME); ---- -{% if book.community %} +ifeval::[{project_community}==true] We have an example, that shows this in detail. -It's in `examples/kerberos` in the {{book.project.name}} example distribution or demo distribution download. +It's in `examples/kerberos` in the {project_name} example distribution or demo distribution download. You can also check the example sources directly https://github.com/keycloak/keycloak/blob/master/examples/kerberos[here] . -{% endif %} +endif::[] Note that you also need to configure `forwardable` kerberos tickets in `krb5.conf` file and add support for delegated credentials to your browser. diff --git a/server_admin/topics/authentication/otp-policies.adoc b/server_admin/topics/authentication/otp-policies.adoc index ff6aff8ca83..b6d89ccfd67 100644 --- a/server_admin/topics/authentication/otp-policies.adoc +++ b/server_admin/topics/authentication/otp-policies.adoc @@ -1,14 +1,14 @@ === OTP Policies -{{book.project.name}} has a number of policies you can set up for your FreeOTP or Google Authenticator One-Time Password +{project_name} has a number of policies you can set up for your FreeOTP or Google Authenticator One-Time Password generator. Click on the `Authentication` left menu item and go to the `OTP Policy` tab. .OTP Policy -image:../../{{book.images}}/otp-policy.png[] +image:{project_images}/otp-policy.png[] Any policies you set here will be used to validate one-time passwords. When configuring OTP, FreeOTP and Google Authenticator -can scan a QR code that is generated on the OTP set up page that {{book.project.name}} has. The bar code is also +can scan a QR code that is generated on the OTP set up page that {project_name} has. The bar code is also generated from information configured on the `OTP Policy` tab. ==== TOTP vs. HOTP @@ -21,11 +21,11 @@ change after a successful login. TOTP is considered a little more secure because the matchable OTP is only valid for a short window of time while the OTP for HOTP can be valid for an indeterminate amount of time. HOTP is much more user friendly as the user won't have to hurry to enter in their -OTP before the time interval is up. With the way {{book.project.name}} has implemented TOTP this distinction becomes a little more +OTP before the time interval is up. With the way {project_name} has implemented TOTP this distinction becomes a little more blurry. HOTP requires a database update every time the server wants to increment the counter. This can be a performance drain on the authentication server when there is heavy load. So, to provide a more efficient alternative, TOTP does not remember passwords used. This bypasses the need to do any DB updates, but the downside is that TOTPs can be re-used in the valid time interval. For future -versions of {{book.project.name}} it is planned that you will be able to configure whether TOTP checks older OTPs in the time interval. +versions of {project_name} it is planned that you will be able to configure whether TOTP checks older OTPs in the time interval. ==== TOTP Configuration Options diff --git a/server_admin/topics/authentication/password-policies.adoc b/server_admin/topics/authentication/password-policies.adoc index 95c9c7dfff0..dad4eb654e2 100644 --- a/server_admin/topics/authentication/password-policies.adoc +++ b/server_admin/topics/authentication/password-policies.adoc @@ -3,8 +3,8 @@ === Password Policies Each new realm created has no password policies associated with it. Users can have as short, as long, as complex, -as insecure a password, as they want. Simple settings are fine for development or learning {{book.project.name}}, -but unacceptable in production environments. {{book.project.name}} has a rich set of password policies you can enable +as insecure a password, as they want. Simple settings are fine for development or learning {project_name}, +but unacceptable in production environments. {project_name} has a rich set of password policies you can enable through the Admin Console. Click on the `Authentication` left menu item and go to the `Password Policy` tab. Choose the policy you want to add in the @@ -12,13 +12,13 @@ right side drop down list box. This will add the policy in the table on the scr Hit the `Save` button to store your changes. .Password Policy -image:../../{{book.images}}/password-policy.png[] +image:{project_images}/password-policy.png[] After saving your policy, user registration and the Update Password required action will enforce your new policy. An example of a user failing the policy check: .Failed Password Policy -image:../../{{book.images}}/failed-password-policy.png[] +image:{project_images}/failed-password-policy.png[] If the password policy is updated, an Update Password action must be set for every user. An automatic trigger is scheduled as a future enhancement. @@ -27,18 +27,18 @@ If the password policy is updated, an Update Password action must be set for eve Here's an explanation of each policy type: -{% if book.community %} +ifeval::[{project_community}==true] HashAlgorithm:: Passwords are not stored as clear text. Instead they are hashed using standard hashing algorithms before they are stored or validated. - The only built-in and default algorithm available is PBKDF2. See the link:{{book.developerguide.link}}[{{book.developerguide.name}}] + The only built-in and default algorithm available is PBKDF2. See the link:{developerguide_link}[{developerguide_name}] on how to plug in your own algorithm. Note that if you do change the algorithm, password hashes will not change in storage until the next time the user logs in. -{% endif %} -{% if book.product %} +endif::[] +ifeval::[{project_product}==true] Hashing Algorithm:: Passwords are not stored as clear text. Instead they are hashed using standard hashing algorithms before they are stored or validated. Supported values are pbkdf2, pbkdf2-sha256 and pbkdf2-sha512. -{% endif %} +endif::[] Hashing Iterations:: This value specifies the number of times a password will be hashed before it is stored or verified. The default value is 20,000. This hashing is done in the rare case that a hacker gets access to your password database. Once they have access to the database, diff --git a/server_admin/topics/authentication/x509.adoc b/server_admin/topics/authentication/x509.adoc index 5c93dddf6ff..e3dd8e2a409 100644 --- a/server_admin/topics/authentication/x509.adoc +++ b/server_admin/topics/authentication/x509.adoc @@ -113,7 +113,7 @@ See link:https://docs.jboss.org/author/display/WFLY10/Admin+Guide#AdminGuide-HTT [source,xml,subs="attributes+"] ---- - + .... > is the preferred protocol to secure applications. It was designed from the ground up to be web friendly +<<_oidc,OpenID Connect>> is the preferred protocol to secure applications. It was designed from the ground up to be web friendly and work best with HTML5/JavaScript applications. To create an OIDC client go to the `Clients` left menu item. On this page you'll see a `Create` button on the right. .Clients -image:../../{{book.images}}/clients.png[] +image:{project_images}/clients.png[] This will bring you to the `Add Client` page. .Add Client -image:../../{{book.images}}/add-client-oidc.png[] +image:{project_images}/add-client-oidc.png[] Enter in the `Client ID` of the client. This should be a simple -alpha-numeric string that will be used in requests and in the {{book.project.name}} database to identity the client. +alpha-numeric string that will be used in requests and in the {project_name} database to identity the client. Next select `openid-connect` in the `Client Protocol` drop down box. Ignore the `Client Template` listbox for now, we'll go over that later in this chapter. @@ -25,7 +25,7 @@ application in the `Root URL` field and click `Save`. This will create the clie tab. .Client Settings -image:../../{{book.images}}/client-settings-oidc.png[] +image:{project_images}/client-settings-oidc.png[] Let's walk through each configuration item on this page. @@ -35,8 +35,8 @@ This specifies an alpha-numeric string that will be used as the client identifie *Name* -This is the display name for the client whenever it is displayed in a {{book.project.name}} UI screen. You can localize -the value of this field by setting up a replacement string value i.e. $\{myapp}. See the link:{{book.developerguide.link}}[{{book.developerguide.name}}] +This is the display name for the client whenever it is displayed in a {project_name} UI screen. You can localize +the value of this field by setting up a replacement string value i.e. $\{myapp}. See the link:{developerguide_link}[{developerguide_name}] for more information. *Description* @@ -51,7 +51,7 @@ If this is turned off, the client will not be allowed to request authentication. If this is on, then users will get a consent page which asks the user if they grant access to that application. It will also display the metadata that the client is interested in so that the user knows exactly what information the client is getting access to. -If you've ever done a social login to Google, you'll often see a similar page. {{book.project.name}} provides the same functionality. +If you've ever done a social login to Google, you'll often see a similar page. {project_name} provides the same functionality. [[_access-type]] *Access Type* @@ -71,7 +71,7 @@ _bearer-only_:: *Root URL* -If {{book.project.name}} uses any configured relative URLs, this value is prepended to them. +If {project_name} uses any configured relative URLs, this value is prepended to them. *Valid Redirect URIs* @@ -80,31 +80,31 @@ Remember that you still have to click the `Save` button! Wildcards (\*) are only allowed at the end of a URI, i.e. $$http://host.com/*$$ You should take extra precautions when registering valid redirect URI patterns. If you make -them too general you are vulnerable to attacks. See <> chapter +them too general you are vulnerable to attacks. See <<_unspecific-redirect-uris, Threat Model Mitigation>> chapter for more information. *Base URL* -If {{book.project.name}} needs to link to the client, this URL is used. +If {project_name} needs to link to the client, this URL is used. *Standard Flow Enabled* -If this is on, clients are allowed to use the OIDC <>. +If this is on, clients are allowed to use the OIDC <<_oidc-auth-flows,Authorization Code Flow>>. *Implicit Flow Enabled* -If this is on, clients are allowed to use the OIDC <>. +If this is on, clients are allowed to use the OIDC <<_oidc-auth-flows,Implicit Flow>>. *Direct Grants Enabled* -If this is on, clients are allowed to use the OIDC <>. +If this is on, clients are allowed to use the OIDC <<_oidc-auth-flows,Direct Grants>>. *Admin URL* -For {{book.project.name}} specific client adapters, this is the callback endpoint for the client. The {{book.project.name}} +For {project_name} specific client adapters, this is the callback endpoint for the client. The {project_name} server will use this URI to make callbacks like pushing revocation policies, performing backchannel logout, and other -administrative operations. For {{book.project.name}} servlet adapters, this can be the root URL of the servlet application. -For more information see link:{{book.adapterguide.link}}[{{book.adapterguide.name}}]. +administrative operations. For {project_name} servlet adapters, this can be the root URL of the servlet application. +For more information see link:{adapterguide_link}[{adapterguide_name}]. *Web Origins* @@ -114,11 +114,11 @@ JavaScript code came from, then the request must use CORS. The server must handle CORS requests in a special way, otherwise the browser will not display or allow the request to be processed. This protocol exists to protect against XSS, CSRF and other JavaScript-based attacks. -{{book.project.name}} has support for validated CORS requests. The way it works is that the domains listed in the +{project_name} has support for validated CORS requests. The way it works is that the domains listed in the `Web Origins` setting for the client are embedded within the access token sent to the client application. The client application can then use this information to decide whether or not to allow a CORS request to be invoked on it. This is -an extension to the OIDC protocol so only {{book.project.name}} client adapters support this feature. -See link:{{book.adapterguide.link}}[{{book.adapterguide.name}}] for more information. +an extension to the OIDC protocol so only {project_name} client adapters support this feature. +See link:{adapterguide_link}[{adapterguide_name}] for more information. To fill in the `Web Origins` data, enter in a base URL and click the + sign to add. Click the - sign next to URLs you want to remove. Remember that you still have to click the `Save` button! diff --git a/server_admin/topics/clients/client-saml.adoc b/server_admin/topics/clients/client-saml.adoc index daab1860182..43452f7821a 100644 --- a/server_admin/topics/clients/client-saml.adoc +++ b/server_admin/topics/clients/client-saml.adoc @@ -1,43 +1,43 @@ === SAML Clients -{{book.project.name}} supports <> for registered applications. +{project_name} supports <<_saml,SAML 2.0>> for registered applications. Both POST and Redirect bindings are supported. You can choose to require client signature validation and can have the server sign and/or encrypt responses as well. To create a SAML client go to the `Clients` left menu item. On this page you'll see a `Create` button on the right. .Clients -image:../../{{book.images}}/clients.png[] +image:{project_images}/clients.png[] This will bring you to the `Add Client` page. .Add Client -image:../../{{book.images}}/add-client-saml.png[] +image:{project_images}/add-client-saml.png[] Enter in the `Client ID` of the client. This is often a URL and will be the expected `issuer` value in SAML requests sent by the application. Next select `saml` in the `Client Protocol` drop down box. Ignore the `Client Template` listbox for now, we'll go over that later in this chapter. Finally enter in the `Client SAML Endpoint` URL. Enter the -URL you want the {{book.project.name}} server to send SAML requests and responses to. Usually applications have only one URL for processing SAML requests. +URL you want the {project_name} server to send SAML requests and responses to. Usually applications have only one URL for processing SAML requests. If your application has different URLs for its bindings, don't worry, you can fix this in the `Settings` tab of the client. Click `Save`. This will create the client and bring you to the client `Settings` tab. .Client Settings -image:../../{{book.images}}/client-settings-saml.png[] +image:{project_images}/client-settings-saml.png[] Client ID:: This value must match the issuer value sent with AuthNRequests. - {{book.project.name}} will pull the issuer from the Authn SAML request and match it to a client by this value. + {project_name} will pull the issuer from the Authn SAML request and match it to a client by this value. Name:: - This is the display name for the client whenever it is displayed in a {{book.project.name}} UI screen. You can localize - the value of this field by setting up a replacement string value i.e. $\{myapp}. See the link:{{book.developerguide.link}}[{{book.developerguide.name}}] + This is the display name for the client whenever it is displayed in a {project_name} UI screen. You can localize + the value of this field by setting up a replacement string value i.e. $\{myapp}. See the link:{developerguide_link}[{developerguide_name}] for more information. Description:: @@ -49,17 +49,17 @@ Enabled:: Consent Required:: If this is on, then users will get a consent page which asks the user if they grant access to that application. It will also display the metadata that the client is interested in so that the user knows exactly what information the client is getting access to. - If you've ever done a social login to Google, you'll often see a similar page. {{book.project.name}} provides the same functionality. + If you've ever done a social login to Google, you'll often see a similar page. {project_name} provides the same functionality. Include AuthnStatement:: SAML login responses may specify the authentication method used (password, etc.) as well as a timestamp of the login. Setting this to on will include that statement in the response document. Sign Documents:: - When turned on, {{book.project.name}} will sign the document using the realm's private key. + When turned on, {project_name} will sign the document using the realm's private key. Optimize REDIRECT signing key lookup:: - When turned on, the SAML protocol messages will include {{book.project.name}} + When turned on, the SAML protocol messages will include {project_name} native extension that contains a hint with signing key ID. When the SP understands this extension, it can use it for signature validation instead of attempting to validate signature with all known keys. This option only applies to @@ -67,7 +67,7 @@ Optimize REDIRECT signing key lookup:: there is no place with this information in the signature information (contrary to POST binding messages where key ID is always included in document signature). Currently this is relevant to situations where both - IDP and SP are provided by {{book.project.name}} server and adapter. This + IDP and SP are provided by {project_name} server and adapter. This option is only relevant when `Sign Documents` is switched on. Sign Assertions:: @@ -79,7 +79,7 @@ Signature Algorithm:: SAML Signature Key Name:: Signed SAML documents sent via POST binding contain identification of signing key in `KeyName` - element. This by default contains {{book.project.name}} key ID. However various vendors might + element. This by default contains {project_name} key ID. However various vendors might expect a different key name or no key name at all. This switch controls whether `KeyName` contains key ID (option `KEY_ID`), subject from certificate corresponding to the realm key (option `CERT_SUBJECT` - expected for instance by Microsoft Active Directory Federation @@ -94,16 +94,16 @@ Encrypt Assertions:: Client Signature Required:: Expect that documents coming from a client are signed. - {{book.project.name}} will validate this signature using the client public key or cert set up in the `SAML Keys` tab. + {project_name} will validate this signature using the client public key or cert set up in the `SAML Keys` tab. Force POST Binding:: - By default, {{book.project.name}} will respond using the initial SAML binding of the original request. - By turning on this switch, you will force {{book.project.name}} to always respond using the SAML POST Binding even if the original request was the Redirect binding. + By default, {project_name} will respond using the initial SAML binding of the original request. + By turning on this switch, you will force {project_name} to always respond using the SAML POST Binding even if the original request was the Redirect binding. Front Channel Logout:: If true, this application requires a browser redirect to be able to perform a logout. For example, the application may require a cookie to be reset which could only be done via a redirect. - If this switch is false, then {{book.project.name}} will invoke a background SAML request to logout the application. + If this switch is false, then {project_name} will invoke a background SAML request to logout the application. Force Name ID Format:: If the request has a name ID policy, ignore it and used the value configured in the admin console under Name ID Format @@ -114,16 +114,16 @@ Name ID Format:: Properties used for each of the respective formats are defined below. Root URL:: - If {{book.project.name}} uses any configured relative URLs, this value is prepended to them. + If {project_name} uses any configured relative URLs, this value is prepended to them. Valid Redirect URIs:: This is an optional field. Enter in a URL pattern and click the + sign to add. Click the - sign next to URLs you want to remove. Remember that you still have to click the `Save` button! Wildcards (\*) are only allowed at the end of of a URI, i.e. $$http://host.com/*$$. This field is used when the exact SAML - endpoints are not registered and {{book.project.name}} is pull the Assertion Consumer URL from the request. + endpoints are not registered and {project_name} is pull the Assertion Consumer URL from the request. Base URL:: - If {{book.project.name}} needs to link to the client, this URL would be used. + If {project_name} needs to link to the client, this URL would be used. Master SAML Processing URL:: This URL will be used for all SAML requests and the response will be directed to the SP. diff --git a/server_admin/topics/clients/client-templates.adoc b/server_admin/topics/clients/client-templates.adoc index 579006b355d..b042779d2d1 100644 --- a/server_admin/topics/clients/client-templates.adoc +++ b/server_admin/topics/clients/client-templates.adoc @@ -2,14 +2,14 @@ === 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 <> for each of these clients. {{book.project.name}} allows you to define shared client configuration in an entity called a _client template_. +to configure the <<_protocol-mappers, protocol mappers>> +and <<_client_scope, scope>> for each of these clients. {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. +A _client template_ will have similar tabs to regular clients. You'll be able to define <<_protocol-mappers, protocol mappers>> +and <<_client_scope, scope>> 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 diff --git a/server_admin/topics/clients/installation.adoc b/server_admin/topics/clients/installation.adoc index aea9f0c5536..b90cbfa1d51 100644 --- a/server_admin/topics/clients/installation.adoc +++ b/server_admin/topics/clients/installation.adoc @@ -1,11 +1,11 @@ === Generating Client Adapter Config -The {{book.project.name}} can pre-generate configuration files that you can use to install a client adapter for in your application's +The {project_name} can pre-generate configuration files that you can use to install a client adapter for in your application's deployment environment. A number of adapter types are supported for both OIDC and SAML. Go to the `Installation` tab of the client you want to generate configuration for. -image:../../{{book.images}}/client-installation.png[] +image:{project_images}/client-installation.png[] -Select the `Format Option` you want configuration generated for. All {{book.project.name}} client adapters for OIDC and SAML +Select the `Format Option` you want configuration generated for. All {project_name} client adapters for OIDC and SAML are supported. The mod-auth-mellon Apache HTTPD adapter for SAML is supported as well as standard SAML entity descriptor files. diff --git a/server_admin/topics/clients/oidc/confidential.adoc b/server_admin/topics/clients/oidc/confidential.adoc index aa49d446e07..cb3e91f6fea 100644 --- a/server_admin/topics/clients/oidc/confidential.adoc +++ b/server_admin/topics/clients/oidc/confidential.adoc @@ -2,12 +2,12 @@ ==== Confidential Client Credentials -If you've set the client's <> to `confidential` in the client's +If you've set the client's <<_access-type, access type>> 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. .Credentials Tab -image:../../../{{book.images}}/client-credentials.png[] +image:{project_images}/client-credentials.png[] The `Client Authenticator` list box specifies the type of credential you are going to use for your confidential client. It defaults to client ID and secret. The secret is automatically generated for you and the `Regenerate Secret` @@ -16,16 +16,16 @@ button allows you to recreate this secret if you want or need to. Alternatively, you can opt to use a signed Json Web Token (JWT) instead of a secret. .Signed JWT -image:../../../{{book.images}}/client-credentials-jwt.png[] +image:{project_images}/client-credentials-jwt.png[] When choosing this credential type you will have to also generate a private key and certificate for the client. The private key will be used to sign the JWT, while the certificate is used by the server to verify the signature. Click on the `Generate new keys and certificate` button to start this process. .Generate Keys -image:../../../{{book.images}}/generate-client-keys.png[] +image:{project_images}/generate-client-keys.png[] -When you generate these keys, {{book.project.name}} will store the certificate, and you'll need to download the private key +When you generate these keys, {project_name} will store the certificate, and you'll need to download the private key and certificate for your client to use. Pick the archive format you want and specify the password for the private key and store. @@ -33,19 +33,19 @@ You can also opt to generate these via an external tool and just import the client's certificate. .Import Certificate -image:../../../{{book.images}}/import-client-cert.png[] +image:{project_images}/import-client-cert.png[] There are multiple formats you can import from, just choose the archive format you have the certificate stored in, select the file, and click the `Import` button. Finally note that you don't even need to import certificate if you choose to `Use JWKS URL` . In that case, you can provide the URL where client publishes it's public key in https://self-issued.info/docs/draft-ietf-jose-json-web-key.html[JWK] format. This is flexible because when -client changes it's keys, {{book.project.name}} will automatically download them without need to re-import anything on {{book.project.name}} side. +client changes it's keys, {project_name} will automatically download them without need to re-import anything on {project_name} side. -If you use client secured by {{book.project.name}} adapter, you can configure the JWKS URL like https://myhost.com/myapp/k_jwks assuming that https://myhost.com/myapp is the -root URL of your client application. See link:{{book.developerguide.link}}[{{book.developerguide.name}}] for additional details. +If you use client secured by {project_name} adapter, you can configure the JWKS URL like https://myhost.com/myapp/k_jwks assuming that https://myhost.com/myapp is the +root URL of your client application. See link:{developerguide_link}[{developerguide_name}] for additional details. -WARNING: For the performance purposes, {{book.project.name}} caches the public keys of the OIDC clients. If you think that private key of your client -was compromised, it is obviously good to update your keys, but it's also good to clear the keys cache. See <> +WARNING: For the performance purposes, {project_name} caches the public keys of the OIDC clients. If you think that private key of your client +was compromised, it is obviously good to update your keys, but it's also good to clear the keys cache. See <<_clear-cache, Clearing the cache>> section for more details. diff --git a/server_admin/topics/clients/oidc/service-accounts.adoc b/server_admin/topics/clients/oidc/service-accounts.adoc index 32a73ac3471..6e49031aeb1 100644 --- a/server_admin/topics/clients/oidc/service-accounts.adoc +++ b/server_admin/topics/clients/oidc/service-accounts.adoc @@ -3,12 +3,12 @@ === Service Accounts 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, +This is covered in the OAuth 2.0 specifiation under <<_client_credentials_grant,Client Credentials Grant>>. +To use this feature you must set the <<_access-type, Access Type>> 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 -configured your <>. +configured your <<_client-credentials, client credentials>>. -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. +To use it you must have registered a valid `confidential` Client and you need to check the switch `Service Accounts Enabled` in {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 the intersection of scopes and the service account roles. diff --git a/server_admin/topics/clients/protocol-mappers.adoc b/server_admin/topics/clients/protocol-mappers.adoc index b0c609567ff..841e0a6d764 100644 --- a/server_admin/topics/clients/protocol-mappers.adoc +++ b/server_admin/topics/clients/protocol-mappers.adoc @@ -3,7 +3,7 @@ === OIDC Token and SAML Assertion Mappings Applications that receive ID Tokens, Access Tokens, or SAML assertions may need or want different user metadata and roles. -{{book.project.name}} allows you to define what exactly is transferred. +{project_name} allows you to define what exactly is transferred. You can hardcode roles, claims and custom attributes. You can pull user metadata into a token or assertion. You can rename roles. @@ -13,7 +13,7 @@ Within the Admin Console, if you go to an application you've registered, you'll an OIDC based client. .Mappers Tab -image:../../{{book.images}}/mappers-oidc.png[] +image:{project_images}/mappers-oidc.png[] Each client has several built-in mappers that are created for it by default. They map things like, for example, email address to a specific claim in the identity and access token. Their function should each be self explanatory from their name. There @@ -24,7 +24,7 @@ Each mapper has common settings as well as additional ones depending on which ty next to one of the mappers in the list to get to the config screen. .Mapper Config -image:../../{{book.images}}/mapper-config.png[] +image:{project_images}/mapper-config.png[] The best way to learn about a config option is to hover over its tooltip. There are a few config options that are common to all mappers: @@ -34,7 +34,7 @@ Consent Required:: Consent Text:: If your client requires consent and the `Consent` switch is on, this is the text that will be displayed by the user. The value for this text is localizable by specifying a substitution variable with `$\{var-name}` strings. The - localized value is then configured within property files in your theme. See the link:{{book.developerguide.link}}[{{book.developerguide.name}}] + localized value is then configured within property files in your theme. See the link:{developerguide_link}[{developerguide_name}] for more information on localization. Most OIDC mappers also allow you to control where the claim gets put. You can opt to include or exclude the claim from both the @@ -43,7 +43,7 @@ _id_ and _access_ tokens by fiddling with the `Add to ID token` and `Add to acce Finally, you can also add other mapper types. If you go back to the `Mappers` tab, click the `Create` button. .Add Mapper -image:../../{{book.images}}/add-mapper.png[] +image:{project_images}/add-mapper.png[] Pick a `Mapper Type` from the list box. If you hover over the tooltip, you'll see a description of what that mapper type does. Different config parameters will appear for different mapper types. diff --git a/server_admin/topics/clients/saml/entity-descriptors.adoc b/server_admin/topics/clients/saml/entity-descriptors.adoc index 91821e5b07d..b81e9170fae 100644 --- a/server_admin/topics/clients/saml/entity-descriptors.adoc +++ b/server_admin/topics/clients/saml/entity-descriptors.adoc @@ -5,7 +5,7 @@ Instead of manually registering a SAML 2.0 client, you can import it via a stand There is an `Import` option on the Add Client page. .Add Client -image:../../../{{book.images}}/add-client-saml.png[] +image:{project_images}/add-client-saml.png[] Click the `Select File` button and load your entity descriptor file. You should review all the information there to make sure everything is set up correctly. diff --git a/server_admin/topics/clients/saml/idp-initiated-login.adoc b/server_admin/topics/clients/saml/idp-initiated-login.adoc index 9e08566ff8f..b0d27eb40c9 100644 --- a/server_admin/topics/clients/saml/idp-initiated-login.adoc +++ b/server_admin/topics/clients/saml/idp-initiated-login.adoc @@ -1,7 +1,7 @@ ==== IDP Initiated Login -IDP Initiated Login is a feature that allows you to set up an endpoint on the {{book.project.name}} server that will log you into a specific application/client. +IDP Initiated Login is a feature that allows you to set up an endpoint on the {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/server_admin/topics/events.adoc b/server_admin/topics/events.adoc index a2f465de0f8..6f0e63dc674 100644 --- a/server_admin/topics/events.adoc +++ b/server_admin/topics/events.adoc @@ -1,7 +1,7 @@ == Auditing and Events -{{book.project.name}} provides a rich set of auditing capabilities. Every single login action can be recorded and stored in +{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 to send an email if an event occurs. diff --git a/server_admin/topics/events/admin.adoc b/server_admin/topics/events/admin.adoc index c0a734c3ab6..e12698174c8 100644 --- a/server_admin/topics/events/admin.adoc +++ b/server_admin/topics/events/admin.adoc @@ -2,18 +2,18 @@ === Admin Events Any action an admin performs within the admin console can be recorded for auditing purposes. -The Admin Console performs administrative functions by invoking on the {{book.project.name}} REST interface. {{book.project.name}} +The Admin Console performs administrative functions by invoking on the {project_name} REST interface. {project_name} audits these REST invocations. The resulting events can then be viewed in the Admin Console. To enable auditing of Admin actions, go to the `Events` left menu item and select the `Config` tab. .Event Configuration -image:../../{{book.images}}/login-events-config.png[] +image:{project_images}/login-events-config.png[] In the `Admin Events Settings` section, turn on the `Save Events` switch. .Admin Event Configuration -image:../../{{book.images}}/admin-events-settings.png[] +image:{project_images}/admin-events-settings.png[] The `Include Representation` switch will include any JSON document that is sent through the admin REST API. This allows you to view exactly what an admin has done, but can lead to a lot of information stored in the database. The `Clear admin events` button allows you to wipe out the current information stored. @@ -21,16 +21,16 @@ database. The `Clear admin events` button allows you to wipe out the current in To view the admin events go to the `Admin Events` tab. .Admin Events -image:../../{{book.images}}/admin-events.png[] +image:{project_images}/admin-events.png[] If the `Details` column has a `Representation` box, you can click on that to view the JSON that was sent with that operation. .Admin Representation -image:../../{{book.images}}/admin-events-representation.png[] +image:{project_images}/admin-events-representation.png[] You can also filter for the events you are interested in by clicking the `Filter` button. .Admin Event Filter -image:../../{{book.images}}/admin-events-filter.png[] +image:{project_images}/admin-events-filter.png[] diff --git a/server_admin/topics/events/login.adoc b/server_admin/topics/events/login.adoc index b71438aa2da..43c2e8bd1b8 100644 --- a/server_admin/topics/events/login.adoc +++ b/server_admin/topics/events/login.adoc @@ -7,12 +7,12 @@ or viewed in the Admin Console. Only error events are logged to the console and persisting you'll need to enable storage. Go to the `Events` left menu item and select the `Config` tab. .Event Configuration -image:../../{{book.images}}/login-events-config.png[] +image:{project_images}/login-events-config.png[] To start storing events you'll need to turn the `Save Events` switch to on under the `Login Events Settings`. .Save Events -image:../../{{book.images}}/login-events-settings.png[] +image:{project_images}/login-events-settings.png[] The `Saved Types` field allows you to specify which event types you want to store in the event store. The `Clear events` button allows you to delete all the events in the database. The `Expiration` field allows you to specify how long you want @@ -22,13 +22,13 @@ the `Save` button on the bottom of this page. To view events, go to the `Login Events` tab. .Login Events -image:../../{{book.images}}/login-events.png[] +image:{project_images}/login-events.png[] As you can see, there's a lot of information stored and, if you are storing every event, there are a lot of events stored for each login action. The `Filter` button on this page allows you to filter which events you are actually interested in. .Login Event Filter -image:../../{{book.images}}/login-events-filter.png[] +image:{project_images}/login-events-filter.png[] In this screenshot, we're filtering only `Login` events. Clicking the `Update` button runs the filter. @@ -61,7 +61,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 -listeners that come with {{book.project.name}}: Logging Event Listener and Email Event Listener. +listeners that come with {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. Here's an example log message: @@ -104,5 +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:{installguide_link}[{installguide_name}] for more details on where the `standalone.xml`, `standalone-ha.xml`, or `domain.xml` file lives. diff --git a/server_admin/topics/export-import.adoc b/server_admin/topics/export-import.adoc old mode 100755 new mode 100644 index b987515a531..2c846f3681b --- a/server_admin/topics/export-import.adoc +++ b/server_admin/topics/export-import.adoc @@ -2,8 +2,8 @@ == Export and Import -{{book.project.name}} has the ability to export and import the entire database. -This can be especially useful if you want to migrate your whole {{book.project.name}} database from one environment to another or migrate to a different database (for example from MySQL to Oracle). Export and import is triggered at server boot time and its parameters are passed in via Java system properties. +{project_name} has the ability to export and import the entire database. +This can be especially useful if you want to migrate your whole {project_name} database from one environment to another or migrate to a different database (for example from MySQL to Oracle). Export and import is triggered at server boot time and its parameters are passed in via Java system properties. It is important to note that because import and export happens at server startup, no other actions should be taken on the server or the database while this happens. You can export/import your database either to: diff --git a/server_admin/topics/groups.adoc b/server_admin/topics/groups.adoc old mode 100755 new mode 100644 index 482ce71f216..dcbf41992e5 --- a/server_admin/topics/groups.adoc +++ b/server_admin/topics/groups.adoc @@ -1,12 +1,12 @@ == Groups -Groups in {{book.project.name}} allow you to manage a common set of attributes and role mappings for a set of users. +Groups in {project_name} allow you to manage a common set of attributes and role mappings for a set of users. Users can be members of zero or more groups. Users inherit the attributes and role mappings assigned to each group. To manage groups go to the `Groups` left menu item. .Groups -image:../{{book.images}}/groups.png[] +image:{project_images}/groups.png[] Groups are hierarchical. A group can have many subgroups, but a group can only have one parent. @@ -18,7 +18,7 @@ parent you want to add a new child to and click `New` button. Select the `Group Entering in a group name in the `Create Group` screen and hitting `Save` will bring you to the individual group management page. .Group -image:../{{book.images}}/group.png[] +image:{project_images}/group.png[] The `Attributes` and `Role Mappings` tab work exactly as the tabs with similar names under a user. Any attributes and role mappings you define will be inherited by the groups and users that are members of this group. @@ -26,13 +26,13 @@ you define will be inherited by the groups and users that are members of this gr To add a user to a group you need to go all the way back to the user detail page and click on the `Groups` tab there. .User Groups -image:../{{book.images}}/user-groups.png[] +image:{project_images}/user-groups.png[] Select a group from the `Available Groups` tree and hit the `join` button to add the user to a group. Vice versa to remove a group. Here we've added the user _Jim_ to the _North America_ sales group. If you go back to the detail page for that group and select the `Membership` tab, _Jim_ is now displayed there. .Group Membership -image:../{{book.images}}/group-membership.png[] +image:{project_images}/group-membership.png[] diff --git a/server_admin/topics/groups/default-groups.adoc b/server_admin/topics/groups/default-groups.adoc index 2c7958a90c1..9dfdd275297 100644 --- a/server_admin/topics/groups/default-groups.adoc +++ b/server_admin/topics/groups/default-groups.adoc @@ -2,11 +2,11 @@ === Default Groups Default groups allow you to automatically assign group membership whenever any new user is created or imported through -<> or <>. +<<_identity_broker, Identity Brokering>>. To specify default groups go to the `Groups` left menu item, and click the `Default Groups` tab. .Default Groups -image:../../{{book.images}}/default-groups.png[] +image:{project_images}/default-groups.png[] diff --git a/server_admin/topics/groups/groups-vs-roles.adoc b/server_admin/topics/groups/groups-vs-roles.adoc index 85edc2d8cd5..d9daf1fae7d 100644 --- a/server_admin/topics/groups/groups-vs-roles.adoc +++ b/server_admin/topics/groups/groups-vs-roles.adoc @@ -3,10 +3,10 @@ === Groups vs. Roles In the IT world the concepts of Group and Role are often blurred and interchangeable. -In {{book.project.name}}, Groups are just a collection of users that you can apply roles and attributes to in one place. +In {project_name}, Groups are just a collection of users that you can apply roles and attributes to in one place. Roles define a type of user and applications assign permission and access control to roles -Aren't <> also similar to Groups? +Aren't <<_composite-roles,Composite Roles>> also similar to Groups? Logically they provide the same exact functionality, but the difference is conceptual. Composite roles should be used to apply the permission model to your set of services and applications. Groups should focus on collections of users and their roles in your organization. diff --git a/server_admin/topics/identity-broker.adoc b/server_admin/topics/identity-broker.adoc old mode 100755 new mode 100644 index 2d1db668f50..9feab16a5ef --- a/server_admin/topics/identity-broker.adoc +++ b/server_admin/topics/identity-broker.adoc @@ -19,7 +19,7 @@ Usually, identity providers are based on the following protocols: * `OpenID Connect v1.0` * `OAuth v2.0` -In the next sections we'll see how to configure and use {{book.project.name}} as an identity broker, covering some important aspects such as: +In the next sections we'll see how to configure and use {project_name} as an identity broker, covering some important aspects such as: * `Social Authentication` * `OpenID Connect v1.0 Brokering` diff --git a/server_admin/topics/identity-broker/configuration.adoc b/server_admin/topics/identity-broker/configuration.adoc index ea54a861304..c6a175b9232 100644 --- a/server_admin/topics/identity-broker/configuration.adoc +++ b/server_admin/topics/identity-broker/configuration.adoc @@ -9,30 +9,30 @@ That means that users from a realm can use any of the registered identity provid In order to create an identity provider click the `Identity Providers` left menu item. .Identity Providers -image:../../{{book.images}}/identity-providers.png[] +image:{project_images}/identity-providers.png[] In the drop down list box, choose the identity provider you want to add. This will bring you to the configuration page for that identity provider type. .Add Identity Provider -image:../../{{book.images}}/add-identity-provider.png[] +image:{project_images}/add-identity-provider.png[] -Above is an example of configuring a Google social login provider. Once you configure an IDP, it will appear on the {{book.project.name}} +Above is an example of configuring a Google social login provider. Once you configure an IDP, it will appear on the {project_name} login page as an option. .IDP login page -image:../../{{book.images}}/identity-provider-login-page.png[] +image:{project_images}/identity-provider-login-page.png[] Social:: Social providers allow you to enable social authentication in your realm. - {{book.project.name}} makes it easy to let users log in to your application using an existing account with a social network. + {project_name} makes it easy to let users log in to your application using an existing account with a social network. Currently Facebook, Google, Twitter, GitHub, LinkedIn, Microsoft, and StackOverflow are supported with more planned for the future. Protocol-based:: Protocol-based providers are those that rely on a specific protocol in order to authenticate and authorize users. They allow you to connect to any identity provider compliant with a specific protocol. - {{book.project.name}} provides support for SAML v2.0 and OpenID Connect v1.0 protocols. + {project_name} provides support for SAML v2.0 and OpenID Connect v1.0 protocols. It makes it easy to configure and broker any identity provider based on these open standards. Although each type of identity provider has its own configuration options, all of them share some very common configuration. @@ -71,10 +71,10 @@ Regardless the identity provider you are creating, you'll see the following conf users that log in from this IDP will not have to go through the email verification process. |GUI order -|The order number that sorts how the available IDPs are listed on the {{book.project.name}} login page. +|The order number that sorts how the available IDPs are listed on the {project_name} login page. |First Login Flow -|This is the authentication flow that will be triggered for users that log into {{book.project.name}} through this IDP +|This is the authentication flow that will be triggered for users that log into {project_name} through this IDP for the first time ever. |Post Login Flow diff --git a/server_admin/topics/identity-broker/default-provider.adoc b/server_admin/topics/identity-broker/default-provider.adoc index e3bfe02e590..0c714a5e49a 100644 --- a/server_admin/topics/identity-broker/default-provider.adoc +++ b/server_admin/topics/identity-broker/default-provider.adoc @@ -6,4 +6,4 @@ It's possible to automatically redirect to a identity provider instead of displa If the configured default identity provider is not found the login form will be displayed instead. -This authenticator is also responsible for dealing with the `kc_idp_hint` query parameter. See <> section for more details. \ No newline at end of file +This authenticator is also responsible for dealing with the `kc_idp_hint` query parameter. See <<_client_suggested_idp, client suggested identity provider>> section for more details. \ No newline at end of file diff --git a/server_admin/topics/identity-broker/first-login-flow.adoc b/server_admin/topics/identity-broker/first-login-flow.adoc index 820ff23eb6b..847a07db728 100644 --- a/server_admin/topics/identity-broker/first-login-flow.adoc +++ b/server_admin/topics/identity-broker/first-login-flow.adoc @@ -3,18 +3,18 @@ === First Login Flow When a user logs in through identity brokering some aspects of the user are imported and linked within the realm's local database. -When {{book.project.name}} successfully authenticates users through an external identity provider +When {project_name} successfully authenticates users through an external identity provider there can be two situations: -* There is already a {{book.project.name}} user account imported and linked with the authenticated identity provider account. - In this case, {{book.project.name}} will just authenticate as the existing user and redirect back to application. -* There is not yet an existing {{book.project.name}} user account imported and linked for this external user. - Usually you just want to register and import the new account into {{book.project.name}} database, but what if there is an existing - {{book.project.name}} account with the same email? Automatically linking the existing local account to the external +* There is already a {project_name} user account imported and linked with the authenticated identity provider account. + In this case, {project_name} will just authenticate as the existing user and redirect back to application. +* There is not yet an existing {project_name} user account imported and linked for this external user. + Usually you just want to register and import the new account into {project_name} database, but what if there is an existing + {project_name} account with the same email? Automatically linking the existing local account to the external identity provider is a potential security hole as you can't always trust the information you get from the external identity provider. Different organizations have different requirements when dealing with some of the conflicts and situations listed above. -For this, there is a `First Login Flow` option in the IDP settings which allows you to choose a <> that will be +For this, there is a `First Login Flow` option in the IDP settings which allows you to choose a <<_authentication-flows, workflow>> that will be used after a user logs in from an external IDP the first time. By default it points to `first broker login` flow, but you can configure and use your own flow and use different flows for different identity providers. @@ -22,10 +22,10 @@ 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 re-configure the existing flow. (For example you can disable some authenticators, mark some of them as `required`, configure some authenticators, etc). -{% if project.community %} +ifeval::[{project_community}==true] You can also create a 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. -{% endif %} +See link:{developerguide_link}[{developerguide_name}] for more details. +endif::[] ==== Default First Login Flow @@ -41,26 +41,26 @@ Review Profile:: by `Confirm Link Existing Account` authenticator) Create User If Unique:: - This authenticator checks if there is already an existing {{book.project.name}} account with same email or username like the account from the identity provider. - If it's not, then the authenticator just creates a new local {{book.project.name}} account and links it with the identity provider and the whole flow is finished. + This authenticator checks if there is already an existing {project_name} account with same email or username like the account from the identity provider. + If it's not, then the authenticator just creates a new local {project_name} account and links it with the identity provider and the whole flow is finished. Otherwise it goes to the next `Handle Existing Account` subflow. If you always want to ensure that there is no duplicated account, you can mark this authenticator as `REQUIRED` . In this case, the user - will see the error page if there is existing {{book.project.name}} account and the user will need to link his identity provider account through Account management. + will see the error page if there is existing {project_name} account and the user will need to link his identity provider account through Account management. Confirm Link Existing Account:: - On the info page, the user will see that there is an existing {{book.project.name}} account with same email. + On the info page, the user will see that there is an existing {project_name} account with same email. He can review his profile again and use different email or username (flow is restarted and goes back to `Review Profile` authenticator). - Or he can confirm that he wants to link the identity provider account with his existing {{book.project.name}} account. + Or he can confirm that he wants to link the identity provider account with his existing {project_name} account. Disable this authenticator if you don't want users to see this confirmation page, but go straight to linking identity provider account by email verification or re-authentication. Verify Existing Account By Email:: This authenticator is `ALTERNATIVE` by default, so it's used only if the realm has SMTP setup configured. - It will send mail to the user, where he can confirm that he wants to link the identity provider with his {{book.project.name}} account. + It will send mail to the user, where he can confirm that he wants to link the identity provider with his {project_name} account. Disable this if you don't want to confirm linking by email, but instead you always want users to reauthenticate with their password (and alternatively OTP). Verify Existing Account By Re-authentication:: This authenticator is used if email authenticator is disabled or non-available (SMTP not configured for realm). It will display a login screen - where the user needs to authenticate with his password to link his {{book.project.name}} account with the Identity provider. - User can also re-authenticate with some different identity provider, which is already linked to his {{book.project.name}} account. + where the user needs to authenticate with his password to link his {project_name} account with the Identity provider. + User can also re-authenticate with some different identity provider, which is already linked to his {project_name} account. You can also force users to use OTP. Otherwise it's optional and used only if OTP is already set for the user account. diff --git a/server_admin/topics/identity-broker/mappers.adoc b/server_admin/topics/identity-broker/mappers.adoc index 594c6c4bd3d..c63e7db7e16 100644 --- a/server_admin/topics/identity-broker/mappers.adoc +++ b/server_admin/topics/identity-broker/mappers.adoc @@ -6,19 +6,19 @@ of the realm. This allows you to extract user profile metadata and other inform applications. Each new user that logs into your realm via an external identity provider will have an entry for it created in the local -{{book.project.name}} database. The act of importing metadata from the SAML or OIDC assertions and claims will create this data +{project_name} database. The act of importing metadata from the SAML or OIDC assertions and claims will create this data with the local realm database. If you click on an identity provider listed in the `Identity Providers` page for your realm, you will be brought to the IDPs `Settings` tab. On this page is also a `Mappers` tab. Click on that tab to start mapping your incoming IDP metadata. -image:../../{{book.images}}/identity-provider-mappers.png[] +image:{project_images}/identity-provider-mappers.png[] There is a `Create` button on this page. Clicking on this create button allows you to create a broker mapper. Broker mappers can import SAML attributes or OIDC ID/Access token claims into user attributes and user role mappings. -image:../../{{book.images}}/identity-provider-mapper.png[] +image:{project_images}/identity-provider-mapper.png[] Select a mapper from the `Mapper Type` list. Hover over the tooltip to see a description of what the mapper does. The tooltips also describe what configuration information you need to enter. Click `Save` and your new mapper will be added. diff --git a/server_admin/topics/identity-broker/oidc.adoc b/server_admin/topics/identity-broker/oidc.adoc index 9b1956170d1..0906c4e6a78 100644 --- a/server_admin/topics/identity-broker/oidc.adoc +++ b/server_admin/topics/identity-broker/oidc.adoc @@ -1,16 +1,16 @@ === OpenID Connect v1.0 Identity Providers -{{book.project.name}} can broker identity providers based on the OpenID Connect protocol. These IDPs must support the <> +{project_name} can broker identity providers based on the OpenID Connect protocol. These IDPs must support the <<_oidc, Authorization Code Flow>> as defined by the specification in order to authenticate the user and authorize access. To begin configuring an OIDC provider, go to the `Identity Providers` left menu item and select `OpenID Connect v1.0` from the `Add provider` drop down list. This will bring you to the `Add identity provider` page. .Add Identity Provider -image:../../{{book.images}}/oidc-add-identity-provider.png[] +image:{project_images}/oidc-add-identity-provider.png[] -The initial configuration options on this page are described in <>. +The initial configuration options on this page are described in <<_general-idp-config, General IDP Configuration>>. You must define the OpenID Connection configuration options as well. They basically describe the OIDC IDP you are communicating with. .OpenID Connect Config @@ -51,33 +51,33 @@ You must define the OpenID Connection configuration options as well. They basic more details |Validate Signatures -|Another optional switch. This is to specify if {{book.project.name}} will verify the signatures on the external ID Token signed by this Identity provider. If this is on, -the {{book.project.name}} will need to know the public key of the external OIDC identity provider. See below for how to setup it. -WARNING: For the performance purposes, {{book.project.name}} caches the public key of the external OIDC identity provider. If you think that private key of your Identity provider +|Another optional switch. This is to specify if {project_name} will verify the signatures on the external ID Token signed by this Identity provider. If this is on, +the {project_name} will need to know the public key of the external OIDC identity provider. See below for how to setup it. +WARNING: For the performance purposes, {project_name} caches the public key of the external OIDC identity provider. If you think that private key of your Identity provider was compromised, it is obviously good to update your keys, but it's also good to clear the keys cache. See -<> section for more details. +<<_clear-cache, Clearing the cache>> section for more details. |Use JWKS URL |Applicable if `Validate Signatures` is on. If the switch is on, then identity provider public keys will be downloaded from given JWKS URL. This allows great flexibility because new keys will be always re-downloaded again when identity provider generates new keypair. If the switch is off, - then public key (or certificate) from the {{book.project.name}} DB is used, so when identity provider keypair changes, you always need to import new key to the {{book.project.name}} DB as well. + then public key (or certificate) from the {project_name} DB is used, so when identity provider keypair changes, you always need to import new key to the {project_name} DB as well. |JWKS URL |URL where identity provider keys in JWK format are stored. See https://self-issued.info/docs/draft-ietf-jose-json-web-key.html[JWK specification] for more details. - If you use external {{book.project.name}} identity provider, then you can use URL like http://broker-keycloak:8180/auth/realms/test/protocol/openid-connect/certs assuming your brokered - {{book.project.name}} is running on http://broker-keycloak:8180 and it's realm is `test` . + If you use external {project_name} identity provider, then you can use URL like http://broker-keycloak:8180/auth/realms/test/protocol/openid-connect/certs assuming your brokered + {project_name} is running on http://broker-keycloak:8180 and it's realm is `test` . |Validating Public Key |Applicable if `Use JWKS URL` is off. Here is the public key in PEM format that must be used to verify external IDP signatures. |Validating Public Key Id |Applicable if `Use JWKS URL` is off. This field specifies ID of the public key in PEM format. This config value is optional. As there is no standard way - for computing key ID from key, various external identity providers might use different algorithm from {{book.project.name}}. If the value of this field + for computing key ID from key, various external identity providers might use different algorithm from {project_name}. If the value of this field is not specified, the validating public key specified above is used for all requests regardless of key ID sent by external IDP. When set, value of this - field serves as key ID used by {{book.project.name}} for validating signatures from such providers and must match the key ID specified by the IDP. + field serves as key ID used by {project_name} for validating signatures from such providers and must match the key ID specified by the IDP. |=== You can also import all this configuration data by providing a URL or file that points to OpenID Provider Metadata (see OIDC Discovery specification). -If you are connecting to a {{book.project.name}} external IDP, you can import the IDP setttings from the url `/auth/realms/\{realm-name}/.well-known/openid-configuration`. +If you are connecting to a {project_name} external IDP, you can import the IDP setttings from the url `/auth/realms/\{realm-name}/.well-known/openid-configuration`. This link is a JSON document describing metadata about the IDP. diff --git a/server_admin/topics/identity-broker/overview.adoc b/server_admin/topics/identity-broker/overview.adoc index 71823b93e0d..2797aa94633 100644 --- a/server_admin/topics/identity-broker/overview.adoc +++ b/server_admin/topics/identity-broker/overview.adoc @@ -2,46 +2,46 @@ === Brokering Overview -When using {{book.project.name}} as an identity broker, users are not forced to provide their credentials in order to authenticate in a specific realm. +When using {project_name} as an identity broker, users are not forced to provide their credentials in order to authenticate in a specific realm. Instead, they are presented with a list of identity providers from which they can authenticate. You can also configure a default broker. In this case the user will not be given a choice, but instead be redirected directly to the parent broker. -The following diagram demonstrates the steps involved when using {{book.project.name}} to broker an external identity provider: +The following diagram demonstrates the steps involved when using {project_name} to broker an external identity provider: .Identity Broker Flow -image:../../images/identity_broker_flow.png[] +image:images/identity_broker_flow.png[] . User is not authenticated and requests a protected resource in a client application. -. The client applications redirects the user to {{book.project.name}} to authenticate. +. The client applications redirects the user to {project_name} to authenticate. . At this point the user is presented with the login page where there is a list of identity providers supported by a realm. . User selects one of the identity providers by clicking on its respective button or link. -. {{book.project.name}} issues an authentication request to the target identity provider asking for authentication and the user +. {project_name} issues an authentication request to the target identity provider asking for authentication and the user is redirected to the login page of the identity provider. The connection properties and other configuration options for the identity provider were previously set by the administrator in the Admin Console. . User provides his credentials or consent in order to authenticate in the identity provider. -. Upon a successful authentication by the identity provider, the user is redirected back to {{book.project.name}} with an authentication response. - Usually this response contains a security token that will be used by {{book.project.name}} to trust the authentication performed by the identity provider +. Upon a successful authentication by the identity provider, the user is redirected back to {project_name} with an authentication response. + Usually this response contains a security token that will be used by {project_name} to trust the authentication performed by the identity provider and retrieve information about the user. -. Now {{book.project.name}} is going to check if the response from the identity provider is valid. +. Now {project_name} is going to check if the response from the identity provider is valid. 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. + If it is a new user, {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 {{book.project.name}} may ask him to link the identity returned from the identity provider with his existing account. + If the user already exists {project_name} may ask him to link the identity returned from the identity provider with his existing account. We call this process _account linking_. - 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. + What exactly is done is configurable and can be specified by setup of <<_identity_broker_first_login,First Login Flow>> . At the end of this step, {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, {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 {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 can request a specific one. -Or you can tell {{book.project.name}} to force the user to provide additional information before federating his identity. +Or you can tell {project_name} to force the user to provide additional information before federating his identity. NOTE: Different protocols may require different authentication flows. - At this moment, all the identity providers supported by {{book.project.name}} use a flow just like described above. + At this moment, all the identity providers supported by {project_name} use a flow just like described above. However, despite the protocol in use, user experience should be pretty much the same. -As you may notice, at the end of the authentication process {{book.project.name}} will always issue its own token to client applications. +As you may notice, at the end of the authentication process {project_name} will always issue its own token to client applications. What this means is that client applications are completely decoupled from external identity providers. They don't need to know which protocol (eg.: SAML, OpenID Connect, OAuth, etc) was used or how the user's identity was validated. -They only need to know about {{book.project.name}}. +They only need to know about {project_name}. diff --git a/server_admin/topics/identity-broker/saml.adoc b/server_admin/topics/identity-broker/saml.adoc index 0c83cecfe57..fbf3a943307 100644 --- a/server_admin/topics/identity-broker/saml.adoc +++ b/server_admin/topics/identity-broker/saml.adoc @@ -1,15 +1,15 @@ === SAML v2.0 Identity Providers -{{book.project.name}} can broker identity providers based on the SAML v2.0 protocol. +{project_name} can broker identity providers based on the SAML v2.0 protocol. To begin configuring an SAML v2.0 provider, go to the `Identity Providers` left menu item and select `SAML v2.0` from the `Add provider` drop down list. This will bring you to the `Add identity provider` page. .Add Identity Provider -image:../../{{book.images}}/saml-add-identity-provider.png[] +image:{project_images}/saml-add-identity-provider.png[] -The initial configuration options on this page are described in <>. +The initial configuration options on this page are described in <<_general-idp-config, General IDP Configuration>>. You must define the SAML configuration options as well. They basically describe the SAML IDP you are communicating with. .SAML Config @@ -44,7 +44,7 @@ You must define the SAML configuration options as well. They basically describe |SAML Signature Key Name |Signed SAML documents sent via POST binding contain identification of signing key in `KeyName` - element. This by default contains {{book.project.name}} key ID. However various external SAML IDPs might + element. This by default contains {project_name} key ID. However various external SAML IDPs might expect a different key name or no key name at all. This switch controls whether `KeyName` contains key ID (option `KEY_ID`), subject from certificate corresponding to the realm key (option `CERT_SUBJECT` - expected for instance by Microsoft Active Directory Federation @@ -62,7 +62,7 @@ You must define the SAML configuration options as well. They basically describe You can also import all this configuration data by providing a URL or file that points to the SAML IDP entity descriptor of the external IDP. -If you are connecting to a {{book.project.name}} external IDP, you can import the IDP setttings from the url `/auth/realms/\{realm-name}/protocol/saml/descriptor`. +If you are connecting to a {project_name} external IDP, you can import the IDP setttings from the url `/auth/realms/\{realm-name}/protocol/saml/descriptor`. This link is an XML document describing metadata about the IDP. diff --git a/server_admin/topics/identity-broker/session-data.adoc b/server_admin/topics/identity-broker/session-data.adoc index c4a7d6b28ad..c742ff2ffb2 100644 --- a/server_admin/topics/identity-broker/session-data.adoc +++ b/server_admin/topics/identity-broker/session-data.adoc @@ -1,15 +1,15 @@ === Available User Session Data -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. +After a user logs in from the external IDP, there's some additional user session note data that {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. identity_provider:: This is the IDP alias of the broker used to perform the login. identity_provider_identity:: - This is the IDP username of the currently authenticated user. This is often same like the {{book.project.name}} username, but doesn't necessarily needs to be. - For example {{book.project.name}} user `john` can be linked to the Facebook user `john123@gmail.com`, so in that case value of user session note will be `john123@gmail.com` . + This is the IDP username of the currently authenticated user. This is often same like the {project_name} username, but doesn't necessarily needs to be. + For example {project_name} user `john` can be linked to the Facebook user `john123@gmail.com`, so in that case value of user session note will be `john123@gmail.com` . -You can use a <> of type `User Session Note` to propagate this information to your clients. +You can use a <<_protocol-mappers, Protocol Mapper>> of type `User Session Note` to propagate this information to your clients. diff --git a/server_admin/topics/identity-broker/social-login.adoc b/server_admin/topics/identity-broker/social-login.adoc index 17abbaaa82e..9c9699b0e84 100644 --- a/server_admin/topics/identity-broker/social-login.adoc +++ b/server_admin/topics/identity-broker/social-login.adoc @@ -4,5 +4,5 @@ For Internet facing applications, it is quite burdensome for users to have to register at your site to obtain access. It requires them to remember yet another username and password combination. Social identity providers allow you to delegate authentication to a semi-trusted and respected entity where the user probably already has an account. -{{book.project.name}} provides built-in support for the most common social networks out there, such as Google, Facebook, Twitter, Github, LinkedIn, Microsoft and StackOverflow. +{project_name} provides built-in support for the most common social networks out there, such as Google, Facebook, Twitter, Github, LinkedIn, Microsoft and StackOverflow. diff --git a/server_admin/topics/identity-broker/social/facebook.adoc b/server_admin/topics/identity-broker/social/facebook.adoc index 355457cf180..25977bbd6f3 100644 --- a/server_admin/topics/identity-broker/social/facebook.adoc +++ b/server_admin/topics/identity-broker/social/facebook.adoc @@ -5,10 +5,10 @@ There are a number of steps you have to complete to be able to login to Facebook and select `Facebook` from the `Add provider` drop down list. This will bring you to the `Add identity provider` page. .Add Identity Provider -image:../../../{{book.images}}/facebook-add-identity-provider.png[] +image:{project_images}/facebook-add-identity-provider.png[] You can't click save yet, as you'll need to obtain a `Client ID` and `Client Secret` from Facebook. One piece of data you'll need from this -page is the `Redirect URI`. You'll have to provide that to Facebook when you register {{book.project.name}} as a client there, so +page is the `Redirect URI`. You'll have to provide that to Facebook when you register {project_name} as a client there, so copy this URI to your clipboard. To enable login with Facebook you first have to create a project and a client in the https://developers.facebook.com/[Facebook Developer Console]. @@ -20,31 +20,31 @@ Once you've logged into the console there is a pull down menu in the top right c menu item. .Add a New App -image:../../../images/facebook-add-new-app.png[] +image:images/facebook-add-new-app.png[] Select the `Website` icon. Click the `Skip and Create App ID` button. .Create a New App ID -image:../../../images/facebook-create-app-id.png[] +image:images/facebook-create-app-id.png[] The email address and app category are required fields. Once you're done with that, you will be brought to the dashboard for the application. Click the `Settings` left menu item. .Create a New App ID -image:../../../images/facebook-app-settings.png[] +image:images/facebook-app-settings.png[] Click on the `+ Add Platform` button at the end of this page and select the `Website` icon. Copy and paste the `Redirect URI` from the -{{book.project.name}} `Add identity provider` page into the `Site URL` of the Facebook `Website` settings block. +{project_name} `Add identity provider` page into the `Site URL` of the Facebook `Website` settings block. .Specify Website -image:../../../images/facebook-app-settings-website.png[] +image:images/facebook-app-settings-website.png[] After this it is necessary to make the Facebook app public. Click `App Review` left menu item and switch button to "Yes". -You will need also to obtain the App ID and App Secret from this page so you can enter them into the {{book.project.name}} `Add identity provider` page. To obtain this click on the `Dashboard` left menu item and click on `Show` under `App Secret`. Go back to {{book.project.name}} and specify those items and finally save your Facebook Identity Provider. +You will need also to obtain the App ID and App Secret from this page so you can enter them into the {project_name} `Add identity provider` page. To obtain this click on the `Dashboard` left menu item and click on `Show` under `App Secret`. Go back to {project_name} and specify those items and finally save your Facebook Identity Provider. One config option to note on the `Add identity provider` page for Facebook is the `Default Scopes` field. This field allows you to manually specify the scopes that users must authorize when authenticating with this provider. -For a complete list of scopes, please take a look at https://developers.facebook.com/docs/graph-api. By default, {{book.project.name}} +For a complete list of scopes, please take a look at https://developers.facebook.com/docs/graph-api. By default, {project_name} uses the following scopes: `email`. diff --git a/server_admin/topics/identity-broker/social/github.adoc b/server_admin/topics/identity-broker/social/github.adoc index a4e065e9914..cde52b3ba82 100644 --- a/server_admin/topics/identity-broker/social/github.adoc +++ b/server_admin/topics/identity-broker/social/github.adoc @@ -5,10 +5,10 @@ There are a number of steps you have to complete to be able to login to Github. and select `Github` from the `Add provider` drop down list. This will bring you to the `Add identity provider` page. .Add Identity Provider -image:../../../{{book.images}}/github-add-identity-provider.png[] +image:{project_images}/github-add-identity-provider.png[] You can't click save yet, as you'll need to obtain a `Client ID` and `Client Secret` from Github. One piece of data you'll need from this -page is the `Redirect URI`. You'll have to provide that to Github when you register {{book.project.name}} as a client there, so +page is the `Redirect URI`. You'll have to provide that to Github when you register {project_name} as a client there, so copy this URI to your clipboard. To enable login with Github you first have to register an application project in @@ -19,19 +19,19 @@ NOTE: Github often changes the look and feel of application registration, so the .Add a New App -image:../../../images/github-developer-applications.png[] +image:images/github-developer-applications.png[] Click the `Register a new application` button. .Register App -image:../../../images/github-register-app.png[] +image:images/github-register-app.png[] -You'll have to copy the `Redirect URI` from the {{book.project.name}} `Add Identity Provider` page and enter it into the +You'll have to copy the `Redirect URI` from the {project_name} `Add Identity Provider` page and enter it into the `Authorization callback URL` field on the Github `Register a new OAuth application` page. Once you've completed this page you will be brought to the application's management page. .Github App Page -image:../../../images/github-app-page.png[] +image:images/github-app-page.png[] -You will need to obtain the client ID and secret from this page so you can enter them into the {{book.project.name}} `Add identity provider` page. -Go back to {{book.project.name}} and specify those items. +You will need to obtain the client ID and secret from this page so you can enter them into the {project_name} `Add identity provider` page. +Go back to {project_name} and specify those items. diff --git a/server_admin/topics/identity-broker/social/google.adoc b/server_admin/topics/identity-broker/social/google.adoc index 7be7563b77d..0cd29a5977a 100644 --- a/server_admin/topics/identity-broker/social/google.adoc +++ b/server_admin/topics/identity-broker/social/google.adoc @@ -4,14 +4,14 @@ There are a number of steps you have to complete to be able to login to Google. and select `Google` from the `Add provider` drop down list. This will bring you to the `Add identity provider` page. .Add Identity Provider -image:../../../{{book.images}}/google-add-identity-provider.png[] +image:{project_images}/google-add-identity-provider.png[] You can't click save yet, as you'll need to obtain a `Client ID` and `Client Secret` from Google. One piece of data you'll need from this -page is the `Redirect URI`. You'll have to provide that to Google when you register {{book.project.name}} as a client there, so +page is the `Redirect URI`. You'll have to provide that to Google when you register {project_name} as a client there, so copy this URI to your clipboard. To enable login with Google you first have to create a project and a client in the https://cloud.google.com/console/project[Google Developer Console]. -Then you need to copy the client id and secret into the {{book.project.name}} Admin Console. +Then you need to copy the client id and secret into the {project_name} Admin Console. NOTE: Google often changes the look and feel of the Google Developer Console, so these directions might not always be up to date and the configuration steps might be slightly different. @@ -21,7 +21,7 @@ Let's see first how to create a project with Google. Log in to the link:https://cloud.google.com/console/project[Google Developer Console]. .Google Developer Console -image:../../../images/google-developer-console.png[] +image:images/google-developer-console.png[] Click the `Create Project` button. @@ -29,19 +29,19 @@ Use any value for `Project name` and `Project ID` you want, then click the `Crea Wait for the project to be created (this may take a while). Once created you will be brought to the project's dashboard. .Dashboard -image:../../../images/google-dashboard.png[] +image:images/google-dashboard.png[] To be able to retrieve the profiles of Google users, you need to turn on the Google+ APIs. Select the `Enable and manage APIs` and click the `Google+ API` link. .APIs -image:../../../images/google-api-list.png[] +image:images/google-api-list.png[] Click the `Enable` button on this page. You will get a message that you must create the credentials of your project. So click the `Go to Credentials` button. .Go To Credentials -image:../../../images/google-go-to-credentials.png[] +image:images/google-go-to-credentials.png[] You will then be brought to the credentials page. @@ -51,32 +51,32 @@ NOTE: If you logout in the middle of this, there is a menu in the top left hand You will then be asked to specify what credentials you need and what type of data you will be accessing. .Add Credentials -image:../../../images/google-add-credentials.png[] +image:images/google-add-credentials.png[] Select `Web server` and `User data` and click the `What credentials do I need?` button. .Create OAuth ID -image:../../../images/google-create-oauth-id.png[] +image:images/google-create-oauth-id.png[] Next you'll need to create an OAuth 2.0 client ID. Specify the name you want for your client. You'll also need to -copy and paste the `Redirect URI` from the {{book.project.name}} `Add Identity Provider` page into the +copy and paste the `Redirect URI` from the {project_name} `Add Identity Provider` page into the `Authorized redirect URIs` field. After you do this, click the `Create client ID` button. -When users log into Google from {{book.project.name}} they will see a consent screen from Google which will ask the user -if {{book.project.name}} is allowed to view information about their user profile. The next Google config screen asks +When users log into Google from {project_name} they will see a consent screen from Google which will ask the user +if {project_name} is allowed to view information about their user profile. The next Google config screen asks you for information about this screen. Once you click `Done` you will be brought to the `Credentials` page. Click on your new OAuth 2.0 Client ID to view the settings of your new Google Client. .Google Client Credentials -image:../../../images/google-client-credentials.png[] +image:images/google-client-credentials.png[] -You will need to obtain the client ID and secret from this page so you can enter them into the {{book.project.name}} `Add identity provider` page. -Go back to {{book.project.name}} and specify those items. +You will need to obtain the client ID and secret from this page so you can enter them into the {project_name} `Add identity provider` page. +Go back to {project_name} and specify those items. One config option to note on the `Add identity provider` page for Google is the `Default Scopes` field. This field allows you to manually specify the scopes that users must authorize when authenticating with this provider. -For a complete list of scopes, please take a look at https://developers.google.com/oauthplayground/ . By default, {{book.project.name}} +For a complete list of scopes, please take a look at https://developers.google.com/oauthplayground/ . By default, {project_name} uses the following scopes: `openid` `profile` `email`. diff --git a/server_admin/topics/identity-broker/social/linked-in.adoc b/server_admin/topics/identity-broker/social/linked-in.adoc index 950a3294a68..438f42f7f94 100644 --- a/server_admin/topics/identity-broker/social/linked-in.adoc +++ b/server_admin/topics/identity-broker/social/linked-in.adoc @@ -5,10 +5,10 @@ There are a number of steps you have to complete to be able to login to LinkedIn and select `LinkedIn` from the `Add provider` drop down list. This will bring you to the `Add identity provider` page. .Add Identity Provider -image:../../../{{book.images}}/linked-in-add-identity-provider.png[] +image:{project_images}/linked-in-add-identity-provider.png[] You can't click save yet, as you'll need to obtain a `Client ID` and `Client Secret` from LinkedIn. One piece of data you'll need from this -page is the `Redirect URI`. You'll have to provide that to LinkedIn when you register {{book.project.name}} as a client there, so +page is the `Redirect URI`. You'll have to provide that to LinkedIn when you register {project_name} as a client there, so copy this URI to your clipboard. To enable login with LinkedIn you first have to create an application in https://www.linkedin.com/secure/developer[LinkedIn Developer Network]. @@ -16,22 +16,22 @@ To enable login with LinkedIn you first have to create an application in https:/ NOTE: LinkedIn may change the look and feel of application registration, so these directions may not always be up to date. .Developer Network -image:../../../images/linked-in-developer-network.png[] +image:images/linked-in-developer-network.png[] Click on the `Create Application` button. This will bring you to the `Create a New Application` Page. .Create App -image:../../../images/linked-in-create-app.png[] +image:images/linked-in-create-app.png[] Fill in the form with the approriate values, then click the `Submit` button. This will bring you to the new application's settings page. .App Settings -image:../../../images/linked-in-app-settings.png[] +image:images/linked-in-app-settings.png[] Select `r_basicprofile` and `r_emailaddress` in the `Default Application Permissions` section. -You'll have to copy the `Redirect URI` from the {{book.project.name}} `Add Identity Provider` page and enter it into the +You'll have to copy the `Redirect URI` from the {project_name} `Add Identity Provider` page and enter it into the `OAuth 2.0` `Authorized Redirect URLs` field on the LinkedIn app settings page. Don't forget to click the `Update` button after you do this! -You will then need to obtain the client ID and secret from this page so you can enter them into the {{book.project.name}} `Add identity provider` page. -Go back to {{book.project.name}} and specify those items. +You will then need to obtain the client ID and secret from this page so you can enter them into the {project_name} `Add identity provider` page. +Go back to {project_name} and specify those items. diff --git a/server_admin/topics/identity-broker/social/microsoft.adoc b/server_admin/topics/identity-broker/social/microsoft.adoc index fa4aa610c7d..94ca566c9b7 100644 --- a/server_admin/topics/identity-broker/social/microsoft.adoc +++ b/server_admin/topics/identity-broker/social/microsoft.adoc @@ -5,10 +5,10 @@ There are a number of steps you have to complete to be able to login to Microsof and select `Microsoft` from the `Add provider` drop down list. This will bring you to the `Add identity provider` page. .Add Identity Provider -image:../../../{{book.images}}/microsoft-add-identity-provider.png[] +image:{project_images}/microsoft-add-identity-provider.png[] You can't click save yet, as you'll need to obtain a `Client ID` and `Client Secret` from Microsoft. One piece of data you'll need from this -page is the `Redirect URI`. You'll have to provide that to Microsoft when you register {{book.project.name}} as a client there, so +page is the `Redirect URI`. You'll have to provide that to Microsoft when you register {project_name} as a client there, so copy this URI to your clipboard. To enable login with Microsoft account you first have to register an OAuth application at Microsoft. @@ -18,17 +18,17 @@ NOTE: Microsoft often changes the look and feel of application registration, so configuration steps might be slightly different. .Register Application -image:../../../images/microsoft-app-register.png[] +image:images/microsoft-app-register.png[] Enter in the application name and click `Create application`. This will bring you to the application settings page of your new application. .Settings -image:../../../images/microsoft-app-settings.png[] +image:images/microsoft-app-settings.png[] -You'll have to copy the `Redirect URI` from the {{book.project.name}} `Add Identity Provider` page and add it to the +You'll have to copy the `Redirect URI` from the {project_name} `Add Identity Provider` page and add it to the `Redirect URIs` field on the Microsoft application page. Be sure to click the `Add Url` button and `Save` your changes. -Finally, you will need to obtain the Application ID and secret from this page so you can enter them back on the {{book.project.name}} `Add identity provider` page. -Go back to {{book.project.name}} and specify those items. +Finally, you will need to obtain the Application ID and secret from this page so you can enter them back on the {project_name} `Add identity provider` page. +Go back to {project_name} and specify those items. diff --git a/server_admin/topics/identity-broker/social/openshift.adoc b/server_admin/topics/identity-broker/social/openshift.adoc index a3de2b9d09b..ad2f48ace4d 100644 --- a/server_admin/topics/identity-broker/social/openshift.adoc +++ b/server_admin/topics/identity-broker/social/openshift.adoc @@ -7,14 +7,14 @@ There are a just a few steps you have to complete to be able to login to OpenShi and select `Openshift` from the `Add provider` drop down list. This will bring you to the `Add identity provider` page. .Add Identity Provider -image:../../../{{book.images}}/openshift-add-identity-provider.png[] +image:{project_images}/openshift-add-identity-provider.png[] .Registering OAuth client You can register your client using `oc` command line tool. ==== -[bash] +[source,bash] ---- $ oc create -f <(echo ' kind: OAuthClient @@ -33,7 +33,7 @@ grantMethod: prompt <4> <4> The `grantMethod` is used to determine what action to take when this client requests tokens and has not yet been granted access by the user. ==== -Use client ID and secret defined by `oc create` command to enter them back on the {{book.project.name}} `Add identity provider` page. -Go back to {{book.project.name}} and specify those items. +Use client ID and secret defined by `oc create` command to enter them back on the {project_name} `Add identity provider` page. +Go back to {project_name} and specify those items. Please refer to https://docs.openshift.org/latest/architecture/additional_concepts/authentication.html#oauth[official Openshift documentation] for more detailed guides. diff --git a/server_admin/topics/identity-broker/social/stack-overflow.adoc b/server_admin/topics/identity-broker/social/stack-overflow.adoc index fd3e5648713..40ae6b8cfdd 100644 --- a/server_admin/topics/identity-broker/social/stack-overflow.adoc +++ b/server_admin/topics/identity-broker/social/stack-overflow.adoc @@ -5,7 +5,7 @@ There are a number of steps you have to complete to be able to login to StackOve and select `StackOverflow` from the `Add provider` drop down list. This will bring you to the `Add identity provider` page. .Add Identity Provider -image:../../../{{book.images}}/stack-overflow-add-identity-provider.png[] +image:{project_images}/stack-overflow-add-identity-provider.png[] To enable login with StackOverflow you first have to register an OAuth application on https://stackapps.com/[StackApps]. Go to http://stackapps.com/apps/oauth/register[registering your application on Stack Apps] url and login. @@ -14,14 +14,14 @@ NOTE: StackOverflow often changes the look and feel of application registration, configuration steps might be slightly different. .Register Application -image:../../../images/stack-overflow-app-register.png[] +image:images/stack-overflow-app-register.png[] Enter in the application name and the OAuth Domain Name of your application and click `Register your Application`. Type in anything you want for the other items. .Settings -image:../../../images/stack-overflow-app-settings.png[] +image:images/stack-overflow-app-settings.png[] -Finally, you will need to obtain the client ID, secret, and key from this page so you can enter them back on the {{book.project.name}} `Add identity provider` page. -Go back to {{book.project.name}} and specify those items. +Finally, you will need to obtain the client ID, secret, and key from this page so you can enter them back on the {project_name} `Add identity provider` page. +Go back to {project_name} and specify those items. diff --git a/server_admin/topics/identity-broker/social/twitter.adoc b/server_admin/topics/identity-broker/social/twitter.adoc index 1d7fdbff52e..8c3dc88294a 100644 --- a/server_admin/topics/identity-broker/social/twitter.adoc +++ b/server_admin/topics/identity-broker/social/twitter.adoc @@ -5,26 +5,26 @@ There are a number of steps you have to complete to be able to login to Twitter. and select `Twitter` from the `Add provider` drop down list. This will bring you to the `Add identity provider` page. .Add Identity Provider -image:../../../{{book.images}}/twitter-add-identity-provider.png[] +image:{project_images}/twitter-add-identity-provider.png[] You can't click save yet, as you'll need to obtain a `Client ID` and `Client Secret` from Twitter. One piece of data you'll need from this -page is the `Redirect URI`. You'll have to provide that to Twitter when you register {{book.project.name}} as a client there, so +page is the `Redirect URI`. You'll have to provide that to Twitter when you register {project_name} as a client there, so copy this URI to your clipboard. To enable login with Twtter you first have to create an application in the https://dev.twitter.com/apps[Twitter Application Management]. .Register Application -image:../../../images/twitter-app-register.png[] +image:images/twitter-app-register.png[] Click on the `Create New App` button. This will bring you to the `Create an Application` page. .Register Application -image:../../../images/twitter-app-create.png[] +image:images/twitter-app-create.png[] Enter in a Name and Description. The Website can be anything, but cannot have a `localhost` address. For the -`Callback URL` you must copy the `Redirect URI` from the {{book.project.name}} `Add Identity Provider` page. +`Callback URL` you must copy the `Redirect URI` from the {project_name} `Add Identity Provider` page. WARNING: You cannot use `localhost` in the `Callback URL`. Instead replace it with `127.0.0.1` if you are trying to testdrive Twitter login on your laptop. @@ -32,13 +32,13 @@ WARNING: You cannot use `localhost` in the `Callback URL`. Instead replace it w After clicking save you will be brought to the `Details` page. .App Details -image:../../../images/twitter-details.png[] +image:images/twitter-details.png[] Next go to the `Keys and Access Tokens` tab. .Keys and Access Tokens -image:../../../images/twitter-keys.png[] +image:images/twitter-keys.png[] -Finally, you will need to obtain the API Key and secret from this page and copy them back into the `Client ID` and `Client Secret` fields on the {{book.project.name}} `Add identity provider` page. +Finally, you will need to obtain the API Key and secret from this page and copy them back into the `Client ID` and `Client Secret` fields on the {project_name} `Add identity provider` page. diff --git a/server_admin/topics/identity-broker/suggested.adoc b/server_admin/topics/identity-broker/suggested.adoc index 2d866aeed70..55fdb3f79e2 100644 --- a/server_admin/topics/identity-broker/suggested.adoc +++ b/server_admin/topics/identity-broker/suggested.adoc @@ -1,12 +1,12 @@ [[_client_suggested_idp]] === Client Suggested Identity Provider -OIDC applications can bypass the {{book.project.name}} login page by specifying a hint on which +OIDC applications can bypass the {project_name} login page by specifying a hint on which identity provider they want to use. This is done by setting the `kc_idp_hint` query parameter in the Authorization Code Flow authorization endpoint. -{{book.project.name}} OIDC client adapters also allow you to specify this query parameter when you access a secured resource +{project_name} OIDC client adapters also allow you to specify this query parameter when you access a secured resource at the application. For example diff --git a/server_admin/topics/identity-broker/tokens.adoc b/server_admin/topics/identity-broker/tokens.adoc index 057ec9471fb..43bb4de1a0f 100644 --- a/server_admin/topics/identity-broker/tokens.adoc +++ b/server_admin/topics/identity-broker/tokens.adoc @@ -1,7 +1,7 @@ === Retrieving External IDP Tokens -{{book.project.name}} allows you to store tokens and responses from the authentication process with the external IDP. +{project_name} allows you to store tokens and responses from the authentication process with the external IDP. For that, you can use the `Store Token` configuration option on the IDP's settings page. Application code can retrieve these tokens and responses to pull in extra user information, or to securely invoke requests on the external IDP. @@ -15,10 +15,10 @@ Host: localhost:8080 Authorization: Bearer {keycloak_access_token} ---- -An application must have authenticated with {{book.project.name}} and have received an access token. This access token +An application must have authenticated with {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 a protected service in {{book.project.name}}, you need to send the access token issued by {{book.project.name}} during the user authentication. +In this case, given that you are accessing a protected service in {project_name}, you need to send the access token issued by {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. These external tokens can be re-established by either logging in again through the provider, or using the client initiated account linking API. diff --git a/server_admin/topics/initialization.adoc b/server_admin/topics/initialization.adoc index 5761257b798..18073ef265e 100644 --- a/server_admin/topics/initialization.adoc +++ b/server_admin/topics/initialization.adoc @@ -1,25 +1,25 @@ == Server Initialization -After performing all the installation and configuration tasks defined in the link:{{book.installguide.link}}[{{book.installguide.name}}], +After performing all the installation and configuration tasks defined in the link:{installguide_link}[{installguide_name}], you will need to create an initial admin account. -{{book.project.name}} does not have any configured admin account out of the box. +{project_name} does not have any configured admin account out of the box. This account will allow you to create an admin that can log into the _master_ realm's administration console so that -you can start creating realms, users and registering applications to be secured by {{book.project.name}}. +you can start creating realms, users and registering applications to be secured by {project_name}. If your server is accessible from `localhost`, you can boot it up and create this admin user by going to the http://localhost:8080/auth URL. .Welcome Page -image:../{{book.images}}/initial-welcome-page.png[] +image:{project_images}/initial-welcome-page.png[] Simply specify the username and password you want for this initial admin. -If you cannot access the server via a `localhost` address, or just want to provision {{book.project.name}} from the command line +If you cannot access the server via a `localhost` address, or just want to provision {project_name} from the command line you can do this with the `.../bin/add-user-keycloak` script. .add-user-keycloak script -image:../{{book.images}}/add-user-script.png[] +image:{project_images}/add-user-script.png[] The parameters are a little different depending if you are using the standalone operation mode or domain operation mode. For standalone mode, here is how you use the script. diff --git a/server_admin/topics/login-settings/forgot-password.adoc b/server_admin/topics/login-settings/forgot-password.adoc index 01fd5360c16..9e69c714f61 100644 --- a/server_admin/topics/login-settings/forgot-password.adoc +++ b/server_admin/topics/login-settings/forgot-password.adoc @@ -5,21 +5,21 @@ If you enable it, users are able to reset their credentials if they forget their Go to the `Realm Settings` left menu item, and click on the `Login` tab. Switch on the `Forgot Password` switch. .Login Tab -image:../../{{book.images}}/login-tab.png[] +image:{project_images}/login-tab.png[] A `forgot password` link will now show up on your login pages. .Forgot Password Link -image:../../{{book.images}}/forgot-password-link.png[] +image:{project_images}/forgot-password-link.png[] Clicking on this link will bring the user to a page where they can enter in their username or email and receive an email with a link to reset their credentials. .Forgot Password Page -image:../../{{book.images}}/forgot-password-page.png[] +image:{project_images}/forgot-password-page.png[] The text sent in the email is completely configurable. You just need to extend or edit the theme associated with it. -See the link:{{book.developerguide.link}}[{{book.developerguide.name}}] for more information. +See the link:{developerguide_link}[{developerguide_name}] for more information. When the user clicks on the email link, they will be asked to update their password, and, if they have an OTP generator set up, they will also be asked to reconfigure this as well. Depending on the security requirements of your organization @@ -27,6 +27,6 @@ you may not want users to be able to reset their OTP generator through email. Y going to the `Authentication` left menu item, clicking on the `Flows` tab, and selecting the `Reset Credentials` flow: .Reset Credentials Flow -image:../../{{book.images}}/reset-credentials-flow.png[] +image:{project_images}/reset-credentials-flow.png[] If you do not want OTP reset, then just chose the `disabled` radio button to the right of `Reset OTP`. diff --git a/server_admin/topics/login-settings/remember-me.adoc b/server_admin/topics/login-settings/remember-me.adoc index 89e442d0282..07a7426d650 100644 --- a/server_admin/topics/login-settings/remember-me.adoc +++ b/server_admin/topics/login-settings/remember-me.adoc @@ -8,12 +8,12 @@ turns the login cookie from a session-only cookie to a persistence cookie. To enable this feature go to `Realm Settings` left menu item and click on the `Login` tab and turn on the `Remember Me` switch: .Login Tab -image:../../{{book.images}}/login-tab.png[] +image:{project_images}/login-tab.png[] Once you save this setting, a `remember me` checkbox will be displayed on the realm's login page. .Remember Me -image:../../{{book.images}}/remember-me.png[] +image:{project_images}/remember-me.png[] diff --git a/server_admin/topics/overview.adoc b/server_admin/topics/overview.adoc index 19925615f7c..ee5b16b35e1 100644 --- a/server_admin/topics/overview.adoc +++ b/server_admin/topics/overview.adoc @@ -1,9 +1,9 @@ == Overview -{{book.project.name}} is a single sign on solution for web apps and RESTful web services. The goal of {{book.project.name}} +{project_name} is a single sign on solution for web apps and RESTful web services. The goal of {project_name} is to make security simple so that it is easy for application developers to secure the apps and services they have deployed in their organization. Security features that developers normally have to write for themselves are provided out of the box -and are easily tailorable to the individual requirements of your organization. {{book.project.name}} provides customizable -user interfaces for login, registration, administration, and account management. You can also use {{book.project.name}} as an +and are easily tailorable to the individual requirements of your organization. {project_name} provides customizable +user interfaces for login, registration, administration, and account management. You can also use {project_name} as an integration platform to hook it into existing LDAP and Active Directory servers. You can also delegate authentication to third party identity providers like Facebook and Google+. diff --git a/server_admin/topics/overview/concepts.adoc b/server_admin/topics/overview/concepts.adoc old mode 100755 new mode 100644 index bad4af56514..2512d1caa45 --- a/server_admin/topics/overview/concepts.adoc +++ b/server_admin/topics/overview/concepts.adoc @@ -1,7 +1,7 @@ === Core Concepts and Terms -There are some key concepts and terms you should be aware of before attempting to use {{book.project.name}} to secure your web applications +There are some key concepts and terms you should be aware of before attempting to use {project_name} to secure your web applications and REST services. users:: @@ -12,7 +12,7 @@ authentication:: authorization:: The process of granting access to a user. credentials:: - Credentials are pieces of data that {{book.project.name}} uses to verify the identity of a user. Some examples are passwords, + Credentials are pieces of data that {project_name} uses to verify the identity of a user. Some examples are passwords, one-time-passwords, digital certificates, or even fingerprints. roles:: Roles identify a type or category of user. `Admin`, `user`, `manager`, and `employee` are all typical roles that may exist @@ -32,19 +32,19 @@ realms:: A realm manages a set of users, credentials, roles, and groups. A user belongs to and logs into a realm. Realms are isolated from one another and can only manage and authenticate the users that they control. clients:: - Clients are entities that can request {{book.project.name}} to authenticate a user. Most often, clients are applications and services that - want to use {{book.project.name}} to secure themselves and provide a single sign-on solution. Clients can also be entities that just want to request - identity information or an access token so that they can securely invoke other services on the network that are secured by {{book.project.name}}. + Clients are entities that can request {project_name} to authenticate a user. Most often, clients are applications and services that + want to use {project_name} to secure themselves and provide a single sign-on solution. Clients can also be entities that just want to request + identity information or an access token so that they can securely invoke other services on the network that are secured by {project_name}. client adapters:: - Client adapters are plugins that you install into your application environment to be able to communicate and be secured by {{book.project.name}}. {{book.project.name}} + Client adapters are plugins that you install into your application environment to be able to communicate and be secured by {project_name}. {project_name} has a number of adapters for different platforms that you can download. There are also third-party adapters you can get for environments that we don't cover. consent:: Consent is when you as an admin want a user to give permission to a client before that client can participate in the authentication process. - After a user provides their credentials, {{book.project.name}} will pop up a screen identifying the client requesting a login and what identity + After a user provides their credentials, {project_name} will pop up a screen identifying the client requesting a login and what identity information is requested of the user. User can decide whether or not to grant the request. client templates:: When a client is registered you need to enter configuration information about that client. It is often useful to store a template - to make create new clients easier. {{book.project.name}} provides the concept of a client template for this. + to make create new clients easier. {project_name} provides the concept of a client template for this. client role:: Clients can define roles that are specific to them. This is basically a role namespace dedicated to the client. identity token:: @@ -66,13 +66,13 @@ session:: When a user logs in, a session is created to manage the login session. A session contains information like when the user logged in and what applications have participated within single-sign on during that session. Both admins and users can view session information. user federation provider:: - {{book.project.name}} can store and manage users. Often, companies already have LDAP or Active Directory services that store user and credential - information. You can point {{book.project.name}} to validate credentials from those external stores and pull in identity information. + {project_name} can store and manage users. Often, companies already have LDAP or Active Directory services that store user and credential + information. You can point {project_name} to validate credentials from those external stores and pull in identity information. identity provider:: - An identity provider (IDP) is a service that can authenticate a user. {{book.project.name}} is an IDP. + An identity provider (IDP) is a service that can authenticate a user. {project_name} is an IDP. identity provider federation:: - {{book.project.name}} can be configured to delegate authentication to one or more IDPs. Social login via - Facebook or Google+ is an example of identity provider federation. You can also hook {{book.project.name}} to delegate + {project_name} can be configured to delegate authentication to one or more IDPs. Social login via + Facebook or Google+ is an example of identity provider federation. You can also hook {project_name} to delegate authentication to any other Open ID Connect or SAML 2.0 IDP. identity provider mappers:: When doing IDP federation you can map incoming tokens and assertions to user and session attributes. This helps you propagate identity information from the external IDP @@ -88,4 +88,4 @@ authentication flows:: events:: Events are audit streams that admins can view and hook into. themes:: - Every screen provided by {{book.project.name}} is backed by a theme. Themes define HTML templates and stylesheets which you can override as needed. + Every screen provided by {project_name} is backed by a theme. Themes define HTML templates and stylesheets which you can override as needed. diff --git a/server_admin/topics/overview/features.adoc b/server_admin/topics/overview/features.adoc index 68b66e2f829..2736567b4fd 100644 --- a/server_admin/topics/overview/features.adoc +++ b/server_admin/topics/overview/features.adoc @@ -18,12 +18,12 @@ * Token mappers - Map user attributes, roles, etc. how you want into tokens and statements. * Not-before revocation policies per realm, application and user. * CORS support - Client adapters have built-in support for CORS. -{% if book.community %} +ifeval::[{project_community}==true] * Service Provider Interfaces (SPI) - A number of SPIs to enable customizing various aspects of the server. Authentication flows, user federation providers, protocol mappers and many more. * Client adapters for JavaScript applications, WildFly, JBoss EAP, Fuse, Tomcat, Jetty, Spring, etc. -{% endif %} -{% if book.product %} +endif::[] +ifeval::[{project_product}==true] * Client adapters for JavaScript applications, JBoss EAP, Fuse, etc. -{% endif %} +endif::[] * Supports any platform/language that has an OpenID Connect Resource Provider library or SAML 2.0 Service Provider library. diff --git a/server_admin/topics/overview/how.adoc b/server_admin/topics/overview/how.adoc old mode 100755 new mode 100644 index 2c4642d0975..7db1b8b3194 --- a/server_admin/topics/overview/how.adoc +++ b/server_admin/topics/overview/how.adoc @@ -1,10 +1,10 @@ === How Does Security Work? -{{book.project.name}} is a separate server that you manage on your network. Applications are configured to point to and -be secured by this server. {{book.project.name}} uses open protocol standards like link:http://openid.net/connect[Open ID Connect] +{project_name} is a separate server that you manage on your network. Applications are configured to point to and +be secured by this server. {project_name} uses open protocol standards like link:http://openid.net/connect[Open ID Connect] or link:http://saml.xml.org/saml-specifications[SAML 2.0] to secure -your applications. Browser applications redirect a user's browser from the application to the {{book.project.name}} authentication +your applications. Browser applications redirect a user's browser from the application to the {project_name} authentication server where they enter their credentials. This is important because users are completely isolated from applications and applications never see a user's credentials. Applications instead are given an identity token or assertion that is cryptographically signed. These tokens can have identity information like username, address, email, and other profile data. They can also diff --git a/server_admin/topics/realms.adoc b/server_admin/topics/realms.adoc index e0f4a93f9fc..b5366f1e1e5 100644 --- a/server_admin/topics/realms.adoc +++ b/server_admin/topics/realms.adoc @@ -2,7 +2,7 @@ == Configuring Realms A realm manages a set of users, credentials, roles, and groups. A user belongs to and logs into a realm. Realms are isolated from one another -and can only manage and authenticate the users that they control. One {{book.project.name}} deployment can define, store, and manage as many realms +and can only manage and authenticate the users that they control. One {project_name} deployment can define, store, and manage as many realms as there is space for in the database. When deciding whether to have one or more realms think about what kind of isolation you want to have for your users and applications. For example, you might define a realm for the employees of your company and have a separate realm for your customers. You employees would log into the employee realm and only be able to visit internal company applications. Customers would log into the customer diff --git a/server_admin/topics/realms/cache.adoc b/server_admin/topics/realms/cache.adoc index d2d9346962f..4c015fb70ba 100644 --- a/server_admin/topics/realms/cache.adoc +++ b/server_admin/topics/realms/cache.adoc @@ -1,13 +1,13 @@ [[_clear-cache]] === Clearing Server Caches -{{book.project.name}} will cache everything it can in memory within the limits of your JVM and/or the limits you've configured -it for. If the {{book.project.name}} database is modified by a third party (i.e. a DBA) outside the scope of the server's REST APIs or Admin Console +{project_name} will cache everything it can in memory within the limits of your JVM and/or the limits you've configured +it for. If the {project_name} database is modified by a third party (i.e. a DBA) outside the scope of the server's REST APIs or Admin Console there's a chance parts of the in-memory cache may be stale. You can clear the realm cache, user cache or cache of external public keys (Public keys of - external clients or Identity providers, which {{book.project.name}} usually uses for verify signatures of particular external entity) from the Admin Console by going + external clients or Identity providers, which {project_name} usually uses for verify signatures of particular external entity) from the Admin Console by going to the `Realm Settings` left menu item and the `Cache` tab. .Cache tab -image:../../{{book.images}}/cache-tab.png[] +image:{project_images}/cache-tab.png[] Just click the `clear` button on the cache you want to evict. diff --git a/server_admin/topics/realms/create.adoc b/server_admin/topics/realms/create.adoc index 871dea8f2eb..04ee348d6d2 100644 --- a/server_admin/topics/realms/create.adoc +++ b/server_admin/topics/realms/create.adoc @@ -8,14 +8,14 @@ this drop down menu lists all the realms created. The last entry of this drop d this to add a realm. .Add Realm Menu -image:../../{{book.images}}/add-realm-menu.png[] +image:{project_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 can import a JSON document that defines your new realm. We'll go over this in more detail in the -<> chapter. +<<_export_import, Export and Import>> chapter. .Create Realm -image:../../{{book.images}}/create-realm.png[] +image:{project_images}/create-realm.png[] After creating the realm you are brought back to the main Admin Console page. The current realm will now be set to the realm you just created. You can switch between managing different realms by doing a mouse over on the diff --git a/server_admin/topics/realms/email.adoc b/server_admin/topics/realms/email.adoc index 9a2c9ac6a95..76eaa71a905 100644 --- a/server_admin/topics/realms/email.adoc +++ b/server_admin/topics/realms/email.adoc @@ -2,14 +2,14 @@ === Email Settings -{{book.project.name}} sends emails to users to verify their email address, when they forget their passwords, or when an admin needs to +{project_name} sends emails to users to verify their email address, when they forget their passwords, or when an admin needs to receive notifications about a server event. -To enable {{book.project.name}} to send emails you need to provide {{book.project.name}} with your SMTP server settings. +To enable {project_name} to send emails you need to provide {project_name} with your SMTP server settings. This is configured per realm. Go to the `Realm Settings` left menu item and click the `Email` tab. .Email Tab -image:../../{{book.images}}/email-tab.png[] +image:{project_images}/email-tab.png[] Host:: `Host` denotes the SMTP server hostname used for sending emails. diff --git a/server_admin/topics/realms/keys.adoc b/server_admin/topics/realms/keys.adoc index 4d444b259bf..028fc156046 100644 --- a/server_admin/topics/realms/keys.adoc +++ b/server_admin/topics/realms/keys.adoc @@ -1,17 +1,17 @@ [[_realm_keys]] === Realm Keys -The authentication protocols that are used by {{book.project.name}} require cryptographic signatures and sometimes -encryption. {{book.project.name}} uses asymmetric key pairs, a private and public key, to accomplish this. +The authentication protocols that are used by {project_name} require cryptographic signatures and sometimes +encryption. {project_name} uses asymmetric key pairs, a private and public key, to accomplish this. -{{book.project.name}} has a single active keypair at a time, but can have several passive keys as well. The active keypair +{project_name} has a single active keypair at a time, but can have several passive keys as well. The active keypair is used to create new signatures, while the passive keypairs can be used to verify previous signatures. This makes it possible to regularly rotate the keys without any downtime or interruption to users. When a realm is created a key pair and a self-signed certificate is automatically generated. To view the active keys for a realm select the realm in the admin console click on `Realm settings` then `Keys`. This -will show the currently active keys for the realm. {{book.project.name}} currently only supports RSA signatures so there +will show the currently active keys for the realm. {project_name} currently only supports RSA signatures so there is only one active keypair. In the future as more signature algorithms are added there will be more active keypairs. To view all available keys select `All`. This will show all active, passive and disabled keys. A keypair can have the @@ -84,12 +84,12 @@ Alternatively, you can delete the provider from the `Providers` table. ==== Compromised keys -{{book.project.name}} has the signing keys stored just locally and they are never shared with the client applications, users or other +{project_name} has the signing keys stored just locally and they are never shared with the client applications, users or other entities. However if you think that your realm signing key was compromised, you should first generate new keypair as described above and then immediatelly remove the compromised keypair. Then to ensure that client applications won't accept the tokens signed by the compromised key, you should update and push not-before policy for the realm, which is doable from the admin console. Pushing new policy will ensure that client applications won't accept the existing -tokens signed by the compromised key, but also the client application will be forced to download new keypair from the {{book.project.name}}, hence +tokens signed by the compromised key, but also the client application will be forced to download new keypair from the {project_name}, hence the tokens signed by the compromised key won't be valid anymore. Note that your REST and confidential clients must have set `Admin URL`, so that -{{book.project.name}} is able to send them the request about pushed not-before policy. +{project_name} is able to send them the request about pushed not-before policy. diff --git a/server_admin/topics/realms/master.adoc b/server_admin/topics/realms/master.adoc index 8c4c57da4fc..d47444f989c 100644 --- a/server_admin/topics/realms/master.adoc +++ b/server_admin/topics/realms/master.adoc @@ -1,7 +1,7 @@ === The Master Realm -When you boot {{book.project.name}} for the first time a pre-defined realm is created for you. This initial realm is called +When you boot {project_name} for the first time a pre-defined realm is created for you. This initial realm is called the _master_ realm and is the king of all realms. Admins in this realm have permissions to view and manage any other realm created on the server instance. When you define your initial admin account, you are creating an account in the _master_ realm. Your initial login to the admin console will also be through the _master_ realm. @@ -11,5 +11,5 @@ as a place for _super_ admins to create and manage the realms in your system. T It is possible to disable the _master_ realm and define admin accounts at each individual new realm you create. Each realm has its own dedicated Admin Console that you can log into with local accounts. This guide talks more about this in the -<> +<<_per_realm_admin_permissions, Dedicated Realm Admin Consoles>> chapter. \ No newline at end of file diff --git a/server_admin/topics/realms/ssl.adoc b/server_admin/topics/realms/ssl.adoc index 17b4ed3a4e3..077f44d6f6a 100644 --- a/server_admin/topics/realms/ssl.adoc +++ b/server_admin/topics/realms/ssl.adoc @@ -6,23 +6,23 @@ Each realm has an SSL Mode associated with it. The SSL Mode defines the SSL/HTT Browsers and applications that interact with the realm must honor the SSL/HTTPS requirements defined by the SSL Mode or they will not be allowed to interact with the server. -WARNING: {{book.project.name}} is not set up by default to handle SSL/HTTPS. - It is highly recommended that you either enable SSL on the {{book.project.name}} server itself or on a reverse proxy in front of the {{book.project.name}} server. +WARNING: {project_name} is not set up by default to handle SSL/HTTPS. + It is highly recommended that you either enable SSL on the {project_name} server itself or on a reverse proxy in front of the {project_name} server. To configure the SSL Mode of your realm, you need to click on the `Realm Settings` left menu item and go to the `Login` tab. .Login Tab -image:../../{{book.images}}/login-tab.png[] +image:{project_images}/login-tab.png[] The `Require SSL` option allows you to pick the SSL Mode you want. Here is an explanation of each mode: external requests:: - Users can interact with {{book.project.name}} so long as they stick to private IP addresses like `localhost`, `127.0.0.1`, `10.0.x.x`, `192.168.x.x`, and `172..16.x.x`. - If you try to access {{book.project.name}} from a non-private IP address you will get an error. + Users can interact with {project_name} so long as they stick to private IP addresses like `localhost`, `127.0.0.1`, `10.0.x.x`, `192.168.x.x`, and `172..16.x.x`. + If you try to access {project_name} from a non-private IP address you will get an error. none:: - {{book.project.name}} does not require SSL. This should really only be used in development when you are playing around with things and don't want to bother + {project_name} does not require SSL. This should really only be used in development when you are playing around with things and don't want to bother configuring SSL on your server. all requests:: - {{book.project.name}} requires SSL for all IP addresses. + {project_name} requires SSL for all IP addresses. diff --git a/server_admin/topics/realms/themes.adoc b/server_admin/topics/realms/themes.adoc index a1cad1662dd..b99f1bf0198 100644 --- a/server_admin/topics/realms/themes.adoc +++ b/server_admin/topics/realms/themes.adoc @@ -1,11 +1,11 @@ [[_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 +Themes allow you to change the look and feel of any UI in {project_name}. Themes are configured per realm. To change a theme go to the `Realm Settings` left menu item and click on the `Themes` tab. .Themes Tab -image:../../{{book.images}}/themes-tab.png[] +image:{project_images}/themes-tab.png[] Pick the theme you want for each UI category and click `Save`. @@ -15,18 +15,18 @@ Login Theme:: Account Theme:: Each user has an User Account Management UI. Admin Console Theme:: - The skin of the {{book.project.name}} Admin Console. + The skin of the {project_name} Admin Console. Email Theme:: - Whenever {{book.project.name}} has to send out an email, it uses templates defined in this theme to craft the email. + Whenever {project_name} has to send out an email, it uses templates defined in this theme to craft the email. -The link:{{book.developerguide.link}}[{{book.developerguide.name}}] goes into how to create a new themes or modify existing ones. +The link:{developerguide_link}[{developerguide_name}] goes into how to create a new themes or modify existing ones. ==== Internationalization -Every UI screen is internationalized in {{book.project.name}}. The default language is English, but if you turn on the +Every UI screen is internationalized in {project_name}. The default language is English, but if you turn on the `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 +User Account Management UI, and Admin Console. The link:{developerguide_link}[{developerguide_name}] explains how you can offer additional languages. diff --git a/server_admin/topics/roles.adoc b/server_admin/topics/roles.adoc old mode 100755 new mode 100644 diff --git a/server_admin/topics/roles/client-scope.adoc b/server_admin/topics/roles/client-scope.adoc index ba80c5f1dcd..424df9e1857 100644 --- a/server_admin/topics/roles/client-scope.adoc +++ b/server_admin/topics/roles/client-scope.adoc @@ -4,7 +4,7 @@ When an OIDC access token or SAML assertion is created, all the user role mappings of the user are, by default, added as claims within the token or assertion. Applications use this information to make access decisions on the resources controlled by that -application. In {{book.project.name}}, access tokens are digitally signed and can actually be re-used by the application +application. In {project_name}, access tokens are digitally signed and can actually be re-used by the application to invoke on other remotely secured REST services. This means that if an application gets compromised or there is a rogue client registered with the realm, attackers can get access tokens that have a broad range of permissions and your whole network is compromised. This is where _client scope_ becomes important. @@ -16,15 +16,15 @@ client access to all of the user's permissions. By default, each client gets al You can view this in the `Scope` tab of each client. .Full Scope -image:../../{{book.images}}/full-client-scope.png[] +image:{project_images}/full-client-scope.png[] You can see from the picture that the effective 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 <<_client_templates, client templates>> to define the scope for a whole set of clients. .Partial Scope -image:../../{{book.images}}/client-scope.png[] +image:{project_images}/client-scope.png[] diff --git a/server_admin/topics/roles/composite.adoc b/server_admin/topics/roles/composite.adoc index c34409c6004..d64b9ea18b4 100644 --- a/server_admin/topics/roles/composite.adoc +++ b/server_admin/topics/roles/composite.adoc @@ -10,7 +10,7 @@ is recursive so any composite of composites also gets inherited. To turn a regular role into a composite role, go to the role detail page and flip the `Composite Role` switch on. .Composite Role -image:../../{{book.images}}/composite-role.png[] +image:{project_images}/composite-role.png[] Once you flip this switch the role selection UI will be displayed lower on the page and you'll be able to associate realm level and client level roles to the composite you are creating. In this example, the `employee` realm-level diff --git a/server_admin/topics/roles/realm-roles.adoc b/server_admin/topics/roles/realm-roles.adoc index 118f8b3d8d2..c5ddbd22da8 100644 --- a/server_admin/topics/roles/realm-roles.adoc +++ b/server_admin/topics/roles/realm-roles.adoc @@ -3,14 +3,14 @@ Realm-level roles are a global namespace to define your roles. You can see the list of built-in and created roles by clicking the `Roles` left menu item. -image:../../{{book.images}}/roles.png[] +image:{project_images}/roles.png[] To create a role, click *Add Role* on this page, enter in the name and description of the role, and click *Save*. .Add Role -image:../../{{book.images}}/role.png[] +image:{project_images}/role.png[] -The value for the `description` field is localizable by specifying a substitution variable with `$\{var-name}` strings. The localized value is then configured within property files in your theme. See the link:{{book.developerguide.link}}[{{book.developerguide.name}}] for more information on localization. If a client requires user _consent_, this description string is displayed on the consent page for the user. +The value for the `description` field is localizable by specifying a substitution variable with `$\{var-name}` strings. The localized value is then configured within property files in your theme. See the link:{developerguide_link}[{developerguide_name}] for more information on localization. If a client requires user _consent_, this description string is displayed on the consent page for the user. If the client has to explicitly request for a realm role, set `Scope Param Required` to true. The role then has to be specified using the `scope` parameter when requesting a token. Multiple realm roles are separated by space: diff --git a/server_admin/topics/roles/user-role-mappings.adoc b/server_admin/topics/roles/user-role-mappings.adoc index 26f8feba26d..510d72b2321 100644 --- a/server_admin/topics/roles/user-role-mappings.adoc +++ b/server_admin/topics/roles/user-role-mappings.adoc @@ -4,13 +4,13 @@ User role mappings can be assigned individually to each user through the `Role Mappings` tab for that single user. .Role Mappings -image:../../{{book.images}}/user-role-mappings.png[] +image:{project_images}/user-role-mappings.png[] -In the above example, we are about to assign the composite role `developer` that was created in the <> +In the above example, we are about to assign the composite role `developer` that was created in the <<_composite-roles, Composite Roles>> chapter. .Effective Role Mappings -image:../../{{book.images}}/effective-role-mappings.png[] +image:{project_images}/effective-role-mappings.png[] Once the `developer` role is assigned, you see that the `employee` role that is associated with the `developer` composite shows up in the `Effective Roles`. `Effective Roles` are all roles that are explicitly assigned to the user as well as any roles that are inherited from composites. diff --git a/server_admin/topics/roles/user-role-mappings/default-roles.adoc b/server_admin/topics/roles/user-role-mappings/default-roles.adoc index 34f004ba0fb..0c4c9e6f071 100644 --- a/server_admin/topics/roles/user-role-mappings/default-roles.adoc +++ b/server_admin/topics/roles/user-role-mappings/default-roles.adoc @@ -2,11 +2,11 @@ ==== Default Roles Default roles allow you to automatically assign user role mappings when any user is newly created or imported through -<> or <>. +<<_identity_broker, Identity Brokering>>. To specify default roles go to the `Roles` left menu item, and click the `Default Roles` tab. .Default Roles -image:../../../{{book.images}}/default-roles.png[] +image:{project_images}/default-roles.png[] As you can see from the screenshot, there are already a number of _default roles_ set up by default. diff --git a/server_admin/topics/sessions.adoc b/server_admin/topics/sessions.adoc index df58388bac6..d387decb2d7 100644 --- a/server_admin/topics/sessions.adoc +++ b/server_admin/topics/sessions.adoc @@ -1,7 +1,7 @@ == User Session Management -When a user logs into a realm, {{book.project.name}} maintains a user session for them and remembers each and every client they +When a user logs into a realm, {project_name} maintains a user session for them and remembers each and every client they have visited within the session. There are a lot of administrative functions that realm admins can perform on these user sessions. They can view login stats for the entire realm and dive down into each client to see who is logged in and where. Admins can logout a user or set of users from the Admin Console. They diff --git a/server_admin/topics/sessions/administering.adoc b/server_admin/topics/sessions/administering.adoc index a0b4efdb117..ef5b3029f1f 100644 --- a/server_admin/topics/sessions/administering.adoc +++ b/server_admin/topics/sessions/administering.adoc @@ -4,7 +4,7 @@ If you go to the `Sessions` left menu item you can see a top level view of the number of sessions that are currently active in the realm. .Sessions -image:../../{{book.images}}/sessions.png[] +image:{project_images}/sessions.png[] A list of clients is given and how many active sessions there currently are for that client. You can also logout all users in the realm by clicking the `Logout all` button on the right side of this list. @@ -12,12 +12,12 @@ users in the realm by clicking the `Logout all` button on the right side of this ==== Logout All Limitations Any SSO cookies set will now be invalid and clients that request authentication in active browser sessions will now have to -re-login. Only certain clients are notified of this logout event, specifically clients that are using the {{book.project.name}} +re-login. Only certain clients are notified of this logout event, specifically clients that are using the {project_name} OIDC client adapter. Other client types (i.e. SAML) will not receive a backchannel logout request. It is important to note that any outstanding access tokens are not revoked by clicking `Logout all`. They have to -expire naturally. You have to push a <> out to -clients, but that also only works with clients using the {{book.project.name}} OIDC client adapter. +expire naturally. You have to push a <<_revocation-policy, revocation policy>> out to +clients, but that also only works with clients using the {project_name} OIDC client adapter. ==== Application Drilldown @@ -25,12 +25,12 @@ On the `Sessions` page, you can also drill down to each client. This will bring Clicking on the `Show Sessions` button there allows you to see which users are logged into that application. .Application Sessions -image:../../{{book.images}}/application-sessions.png[] +image:{project_images}/application-sessions.png[] ==== User Drilldown If you go to the `Sessions` tab of an individual user, you can also view the session information. .User Sessions -image:../../{{book.images}}/user-sessions.png[] +image:{project_images}/user-sessions.png[] diff --git a/server_admin/topics/sessions/offline.adoc b/server_admin/topics/sessions/offline.adoc index a242b64d944..ccc8a1fce60 100644 --- a/server_admin/topics/sessions/offline.adoc +++ b/server_admin/topics/sessions/offline.adoc @@ -8,22 +8,22 @@ The application can save this offline token in a database or on disk and can use This is useful if your application needs to do some "offline" actions on behalf of user even when the user is not online. An example is a periodic backup of some data every night. -Your application is responsible for persisting the offline token in some storage (usually a database) and then using it to manually retrieve new access token from {{book.project.name}} server. +Your application is responsible for persisting the offline token in some storage (usually a database) and then using it to manually retrieve new access token from {project_name} server. The difference between a classic Refresh token and an Offline token is, that an offline token will never expire and is not subject of `SSO Session Idle timeout` . The offline token is valid even after a user logout or server restart. However by default you do need to use the offline token for a refresh token action at least once per 30 days (this value, `Offline Session Idle timeout`, can be changed in the administration console in the `Tokens` tab under `Realm Settings`). Also if you enable the option `Revoke refresh tokens`, then each offline token can be used just once. So after refresh, you always need to store the new offline token from refresh response into your DB instead of the previous one. -Users can view and revoke offline tokens that have been granted by them in the <>. +Users can view and revoke offline tokens that have been granted by them in the <<_account-service, User Account Service>>. The admin user can revoke offline tokens for individual users in admin console in the `Consents` tab of a particular user. The admin can also view all the offline tokens issued in the `Offline Access` tab of each client. -Offline tokens can also be revoked by setting a <>. +Offline tokens can also be revoked by setting a <<_revocation-policy, revocation policy>>. To be able to issue an offline token, users need to have the role mapping for the realm-level role `offline_access`. Clients also need to have that role in their scope. -The client can request an offline token by adding the parameter `scope=offline_access` when sending authorization request to {{book.project.name}}. -The {{book.project.name}} OIDC client adapter automatically adds this parameter when you use it to access secured URL of your application (i.e. +The client can request an offline token by adding the parameter `scope=offline_access` when sending authorization request to {project_name}. +The {project_name} OIDC client adapter automatically adds this parameter when you use it to access secured URL of your application (i.e. $$http://localhost:8080/customer-portal/secured?scope=offline_access$$). The Direct Access Grant and Service Accounts also support offline tokens if you include `scope=offline_access` in the body of the authentication request. diff --git a/server_admin/topics/sessions/revocation.adoc b/server_admin/topics/sessions/revocation.adoc index 4dc8483736a..50523bee9e0 100644 --- a/server_admin/topics/sessions/revocation.adoc +++ b/server_admin/topics/sessions/revocation.adoc @@ -6,9 +6,9 @@ If your system is compromised you will want a way to revoke all sessions and acc You can do this by going to the `Revocation` tab of the `Sessions` screen. .Revocation -image:../../{{book.images}}/revocation.png[] +image:{project_images}/revocation.png[] You can only set a time-based revocation policy. The console allows you to specify a time and date where any session or token issued before that time and date is invalid. The `Set to now` will set the policy to the current time and date. -The `Push` button will push this revocation policy to any registered OIDC client that has the {{book.project.name}} +The `Push` button will push this revocation policy to any registered OIDC client that has the {project_name} OIDC client adapter installed. \ No newline at end of file diff --git a/server_admin/topics/sessions/timeouts.adoc b/server_admin/topics/sessions/timeouts.adoc index 819972cd1ce..28362e7b0f5 100644 --- a/server_admin/topics/sessions/timeouts.adoc +++ b/server_admin/topics/sessions/timeouts.adoc @@ -2,11 +2,11 @@ === Session and Token Timeouts -{{book.project.name}} gives you fine grain control of session, cookie, and token timeouts. This is all done on the +{project_name} gives you fine grain control of session, cookie, and token timeouts. This is all done on the `Tokens` tab in the `Realm Settings` left menu item. .Tokens Tab -image:../../{{book.images}}/tokens-tab.png[] +image:{project_images}/tokens-tab.png[] Let's walk through each of the items on this page. @@ -26,7 +26,7 @@ Let's walk through each of the items on this page. a user session can remain active, regardless of activity. |Offline Session Idle -|For <>, this is the time the session is allowed to remain idle before the offline token is revoked. +|For <<_offline-access, offline access>>, this is the time the session is allowed to remain idle before the offline token is revoked. |Access Token Lifespan |When an OIDC access token is created, this value affects the expiration. diff --git a/server_admin/topics/sso-protocols.adoc b/server_admin/topics/sso-protocols.adoc index 81a6aef9b62..6ab18058802 100644 --- a/server_admin/topics/sso-protocols.adoc +++ b/server_admin/topics/sso-protocols.adoc @@ -1,5 +1,5 @@ == SSO Protocols -The chapter gives a brief overview of the authentication protocols and how the {{book.project.name}} authentication server +The chapter gives a brief overview of the authentication protocols and how the {project_name} authentication server and the applications it secures interact with these protocols. \ No newline at end of file diff --git a/server_admin/topics/sso-protocols/docker.adoc b/server_admin/topics/sso-protocols/docker.adoc index 9f45f799dde..deb29b91031 100644 --- a/server_admin/topics/sso-protocols/docker.adoc +++ b/server_admin/topics/sso-protocols/docker.adoc @@ -2,24 +2,24 @@ === Docker Registry v2 Authentication -NOTE: Docker authentication is disabled by default. To enable see link:{{book.installguide.profile.link}}[{{book.installguide.profile.name}}]. +NOTE: Docker authentication is disabled by default. To enable see link:{installguide_profile_link}[{installguide_profile_name}]. -link:https://docs.docker.com/registry/spec/auth/[Docker Registry V2 Authentciation] is an OIDC-Like protocol used to authenticate users against a Docker registry. {{book.project.name}}'s implementation of this protocol allows for a {{book.project.name}} authentication server to be used by a Docker client to authenticate against a registry. While this protocol uses fairly standard token and signature mechanisms, it has a few wrinkles that prevent it from being treated as a true OIDC implementation. The largest deviations include a very specific JSON format for requests and responses as well as the ability to understand how to map repository names and permissions to the OAuth scope mechanism. +link:https://docs.docker.com/registry/spec/auth/[Docker Registry V2 Authentciation] is an OIDC-Like protocol used to authenticate users against a Docker registry. {project_name}'s implementation of this protocol allows for a {project_name} authentication server to be used by a Docker client to authenticate against a registry. While this protocol uses fairly standard token and signature mechanisms, it has a few wrinkles that prevent it from being treated as a true OIDC implementation. The largest deviations include a very specific JSON format for requests and responses as well as the ability to understand how to map repository names and permissions to the OAuth scope mechanism. -===== Docker Auth Flow -The link:https://docs.docker.com/registry/spec/auth/token/[Docker API documentation] best describes and illustrates this process, however a brief summary will be given below from the perspective of they {{book.project.name}} authentication server. +==== Docker Auth Flow +The link:https://docs.docker.com/registry/spec/auth/token/[Docker API documentation] best describes and illustrates this process, however a brief summary will be given below from the perspective of they {project_name} authentication server. NOTE: This flow assumes that a `docker login` command has already been performed - - The flow begins when the Docker client requests a resource from the Docker registry. If the resource is protected and no auth token is present in the request, the Docker registry server will respond to the client with a 401 + some information on required permissions and where to find the authorization server. - - The Docker client will construct an authentication request based on the 401 response from the Docker registry. The client will then use the locally cached credentials (from a previously run `docker login` command) as part of a link:https://tools.ietf.org/html/rfc2617[HTTP Basic Authentication] request to the {{book.project.name}} authentication server. - - The {{book.project.name}} authentication server will attempt to authenticate the user and return a JSON body containing an OAuth-style Bearer token. - - The Docker client will get the bearer token from the JSON response and use it in the Authorization header to request the protected resource. - - When the Docker registry recieves the new request for the protected resource with the token from the {{book.project.name}} server, the registry validates the token and grants access to the requested resource (if appropriate). + * The flow begins when the Docker client requests a resource from the Docker registry. If the resource is protected and no auth token is present in the request, the Docker registry server will respond to the client with a 401 + some information on required permissions and where to find the authorization server. + * The Docker client will construct an authentication request based on the 401 response from the Docker registry. The client will then use the locally cached credentials (from a previously run `docker login` command) as part of a link:https://tools.ietf.org/html/rfc2617[HTTP Basic Authentication] request to the {project_name} authentication server. + * The {project_name} authentication server will attempt to authenticate the user and return a JSON body containing an OAuth-style Bearer token. + * The Docker client will get the bearer token from the JSON response and use it in the Authorization header to request the protected resource. + * When the Docker registry recieves the new request for the protected resource with the token from the {project_name} server, the registry validates the token and grants access to the requested resource (if appropriate). -==== {{book.project.name}} Docker Registry v2 Authentication Server URI Endpoints +==== {project_name} Docker Registry v2 Authentication Server URI Endpoints -{{book.project.name}} really only has one endpoint for all Docker auth v2 requests. +{project_name} really only has one endpoint for all Docker auth v2 requests. `http(s)://authserver.host/auth/realms/\{realm-name}/protocol/docker-v2` diff --git a/server_admin/topics/sso-protocols/oidc.adoc b/server_admin/topics/sso-protocols/oidc.adoc index 30e653e4b9b..32584199b87 100644 --- a/server_admin/topics/sso-protocols/oidc.adoc +++ b/server_admin/topics/sso-protocols/oidc.adoc @@ -7,14 +7,14 @@ While OAuth 2.0 is only a framework for building authorization protocols and is protocol. OIDC also makes heavy use of the link:https://jwt.io[Json Web Token] (JWT) set of standards. These standards define an identity token JSON format and ways to digitally sign and encrypt that data in a compact and web-friendly way. -There are really two types of use cases when using OIDC. The first is an application that asks the {{book.project.name}} server to authenticate +There are really two types of use cases when using OIDC. The first is an application that asks the {project_name} server to authenticate a user for them. After a successful login, the application will receive an _identity token_ and an _access token_. The _identity token_ contains information about the user such as username, email, and other profile information. The _access token_ is digitally signed by the realm and contains access information (like user role mappings) that the application can use to determine what resources the user is allowed to access on the application. -The second type of use cases is that of a client that wants to gain access to remote services. In this case, the client asks {{book.project.name}} -to obtain an _access token_ it can use to invoke on other remote services on behalf of the user. {{book.project.name}} authenticates the user +The second type of use cases is that of a client that wants to gain access to remote services. In this case, the client asks {project_name} +to obtain an _access token_ it can use to invoke on other remote services on behalf of the user. {project_name} authenticates the user then asks the user for consent to grant access to the client requesting it. The client then receives the _access token_. This _access token_ is digitally signed by the realm. The client can make REST invocations on remote services using this _access token_. The REST service extracts the _access token_, verifies the signature of the token, then decides based on access information within the token whether or not to process @@ -33,13 +33,13 @@ OIDC and OAuth 2.0 specifications so only a brief overview will be provided here This is a browser-based protocol and it is what we recommend you use to authenticate and authorize browser-based applications. It makes heavy use of browser redirects to obtain an _identity_ and _access_ token. Here's a brief summary: -. Browser visits application. The application notices the user is not logged in, so it redirects the browser to {{book.project.name}} +. Browser visits application. The application notices the user is not logged in, so it redirects the browser to {project_name} to be authenticated. The application passes along a callback URL (a redirect URL) as a query parameter in this browser redirect - that {{book.project.name}} will use when it finishes authentication. -. {{book.project.name}} authenticates the user and creates a one-time, very short lived, temporary code. {{book.project.name}} + that {project_name} will use when it finishes authentication. +. {project_name} authenticates the user and creates a one-time, very short lived, temporary code. {project_name} redirects back to the application using the callback URL provided earlier and additionally adds the temporary code as a query parameter in the callback URL. -. The application extracts the temporary code and makes a background out of band REST invocation to {{book.project.name}} +. The application extracts the temporary code and makes a background out of band REST invocation to {project_name} to exchange the code for an _identity_, _access_ and _refresh_ token. Once this temporary code has been used once to obtain the tokens, it can never be used again. This prevents potential replay attacks. @@ -55,7 +55,7 @@ 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 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 <<_clients, Managing Clients>> chapter. ===== Implicit Flow @@ -65,10 +65,10 @@ via redirect URIs (see below). Also, since this flow doesn't provide the client be long-lived or users would have to re-authenticate when they expired. This flow is supported because it is in the OIDC and OAuth 2.0 specification. Here's a brief summary of the protocol: -. Browser visits application. The application notices the user is not logged in, so it redirects the browser to {{book.project.name}} +. Browser visits application. The application notices the user is not logged in, so it redirects the browser to {project_name} to be authenticated. The application passes along a callback URL (a redirect URL) as a query parameter in this browser redirect - that {{book.project.name}} will use when it finishes authentication. -. {{book.project.name}} authenticates the user and creates an _identity_ and _access_ token. {{book.project.name}} + that {project_name} will use when it finishes authentication. +. {project_name} authenticates the user and creates an _identity_ and _access_ token. {project_name} redirects back to the application using the callback URL provided earlier and additionally adding the _identity_ and _access_ tokens as query parameters in the callback URL. . The application extracts the _identity_ and _access_ tokens from the callback URL. @@ -84,11 +84,11 @@ _identity_, _access_, and _refresh_ tokens. This is also used by REST clients, but instead of obtaining a token that works on behalf of an external user, a token is created based on the metadata and permissions of a service account that is associated with the client. -More info together with example is in <> chapter. +More info together with example is in <<_service_accounts,Service Accounts>> chapter. -==== {{book.project.name}} Server OIDC URI Endpoints +==== {project_name} Server OIDC URI Endpoints -Here's a list of OIDC endpoints that the {{book.project.name}} publishes. These URLs are useful if you are using a non-{{book.project.name}} client adapter to +Here's a list of OIDC endpoints that the {project_name} publishes. These URLs are useful if you are using a non-{project_name} client adapter to talk OIDC with the auth server. These are all relative URLs and the root of the URL being the HTTP(S) protocol, hostname, and usually path prefixed with _/auth_: i.e. $$https://localhost:8080/auth$$ diff --git a/server_admin/topics/sso-protocols/saml-vs-oidc.adoc b/server_admin/topics/sso-protocols/saml-vs-oidc.adoc index 77b42230a0a..52ccc83a74a 100644 --- a/server_admin/topics/sso-protocols/saml-vs-oidc.adoc +++ b/server_admin/topics/sso-protocols/saml-vs-oidc.adoc @@ -3,7 +3,7 @@ Choosing between OpenID Connect and SAML is not just a matter of using a newer protocol (OIDC) instead of the older more mature protocol (SAML). -In most cases {{book.project.name}} recommends using OIDC. +In most cases {project_name} recommends using OIDC. SAML tends to be a bit more verbose than OIDC. diff --git a/server_admin/topics/sso-protocols/saml.adoc b/server_admin/topics/sso-protocols/saml.adoc index 4cf79d132da..cb6b9590407 100644 --- a/server_admin/topics/sso-protocols/saml.adoc +++ b/server_admin/topics/sso-protocols/saml.adoc @@ -7,19 +7,19 @@ of WS-* specifications so it tends to be a bit more verbose than OIDC. SAML 2.0 that works by exchanging XML documents between the authentication server and the application. XML signatures and encryption is used to verify requests and responses. -There is really two types of use cases when using SAML. The first is an application that asks the {{book.project.name}} server to authenticate +There is really two types of use cases when using SAML. The first is an application that asks the {project_name} server to authenticate a user for them. After a successful login, the application will receive an XML document that contains something called a SAML assertion that specify various attributes about the user. This XML document is digitally signed by the realm and contains access information (like user role mappings) that the application can use to determine what resources the user is allowed to access on the application. -The second type of use cases is that of a client that wants to gain access to remote services. In this case, the client asks {{book.project.name}} +The second type of use cases is that of a client that wants to gain access to remote services. In this case, the client asks {project_name} to obtain an SAML assertion it can use to invoke on other remote services on behalf of the user. ==== SAML Bindings SAML defines a few different ways to exchange XML documents when executing the authentication protocol. The _Redirect_ and _Post_ bindings -cover browser based applications. The _ECP_ binding covers REST invocations. There are other binding types but {{book.project.name}} only +cover browser based applications. The _ECP_ binding covers REST invocations. There are other binding types but {project_name} only supports those three. ===== Redirect Binding @@ -28,11 +28,11 @@ The _Redirect_ Binding uses a series of browser redirect URIs to exchange inform how it works. . The user visits the application and the application finds the user is not authenticated. It generates an XML authentication - request document and encodes it as a query param in a URI that is used to redirect to the {{book.project.name}} server. + request document and encodes it as a query param in a URI that is used to redirect to the {project_name} server. Depending on your settings, the application may also digitally sign this XML document and also stuff this signature as a query - param in the redirect URI to {{book.project.name}}. This signature is used to validate the client that sent this + param in the redirect URI to {project_name}. This signature is used to validate the client that sent this request. -. The browser is redirected to {{book.project.name}}. The server extracts the XML auth request document and verifies +. The browser is redirected to {project_name}. The server extracts the XML auth request document and verifies the digital signature if required. The user then has to enter in their credentials to be authenticated. . After authentication, the server generates an XML authentication response document. This document contains a SAML assertion that holds metadata about the user like name, address, email, and any role mappings the user @@ -47,7 +47,7 @@ how it works. The SAML _POST_ binding works almost the exact same way as the _Redirect_ binding, but instead of GET requests, XML documents are exchanged by POST requests. The _POST_ Binding uses JavaScript to trick the browser into making a POST request to -the {{book.project.name}} server or application when exchanging documents. Basically HTTP responses contain an HTML document +the {project_name} server or application when exchanging documents. Basically HTTP responses contain an HTML document that contains an HTML form with embedded JavaScript. When the page is loaded, the JavaScript automatically invokes the form. You really don't need to know about this stuff, but it is a pretty clever trick. @@ -56,9 +56,9 @@ You really don't need to know about this stuff, but it is a pretty clever trick. ECP stands for "Enhanced Client or Proxy", a SAML v.2.0 profile which allows for the exchange of SAML attributes outside the context of a web browser. This is used most often for REST or SOAP-based clients. -==== {{book.project.name}} Server SAML URI Endpoints +==== {project_name} Server SAML URI Endpoints -{{book.project.name}} really only has one endpoint for all SAML requests. +{project_name} really only has one endpoint for all SAML requests. `http(s)://authserver.host/auth/realms/\{realm-name}/protocol/saml` diff --git a/server_admin/topics/threat.adoc b/server_admin/topics/threat.adoc old mode 100755 new mode 100644 index c204553f8d2..b7aa0a8b889 --- a/server_admin/topics/threat.adoc +++ b/server_admin/topics/threat.adoc @@ -1,6 +1,6 @@ == Threat Model Mitigation -This chapter discusses possible security vulnerabilities any authentication server could have and how {{book.project.name}} +This chapter discusses possible security vulnerabilities any authentication server could have and how {project_name} mitigates those vulnerabilities. A good list of potential vulnerabilities and what security implementations should do to mitigate them can be found in the http://tools.ietf.org/html/rfc6819[OAuth 2.0 Threat Model] document put out by the IETF. diff --git a/server_admin/topics/threat/brute-force.adoc b/server_admin/topics/threat/brute-force.adoc index e73d0604530..5bc7d6c9b47 100644 --- a/server_admin/topics/threat/brute-force.adoc +++ b/server_admin/topics/threat/brute-force.adoc @@ -2,13 +2,13 @@ === Password guess: brute force attacks A brute force attack happens when an attacker is trying to guess a user's password. -{{book.project.name}} has some limited brute force detection capabilities. +{project_name} has some limited brute force detection capabilities. If turned on, a user account will be temporarily disabled if a threshold of login failures is reached. To enable this feature go to the `Realm Settings` left menu item, click on the `Security Defenses` tab, then additional go to the `Brute Force Detection` sub-tab. .Brute Force Detection -image:../../{{book.images}}/brute-force.png[] +image:{project_images}/brute-force.png[] The way this works is that if there are `Max Login Failures` during a period of `Failure Reset Time`, the account is temporarily disabled for the `Wait Increment` multiplied by the number of failures over the max. After @@ -18,18 +18,18 @@ account that are too quick for a human to initiate the account will be disabled. `Quick Login Check Milli Seconds` value. So, if there are two login failures for the same account within that value, the account will be disabled for `Minimum Quick Login Wait`. -The downside of {{book.project.name}} brute force detection is that the server becomes vulnerable to denial of service attacks. +The downside of {project_name} brute force detection is that the server becomes vulnerable to denial of service attacks. An attacker can simply try to guess passwords for any accounts it knows and these account will be disabled. Eventually we will expand this functionality to take client IP address into account when deciding whether to block a user. -A better option might be a tool like http://www.fail2ban.org[Fail2Ban]. You can point this service at the {{book.project.name}} server's log file. -{{book.project.name}} logs every login failure and client IP address that had the failure. Fail2Ban can be used to modify +A better option might be a tool like http://www.fail2ban.org[Fail2Ban]. You can point this service at the {project_name} server's log file. +{project_name} logs every login failure and client IP address that had the failure. Fail2Ban can be used to modify firewalls after it detects an attack to block connections from specific IP addresses. ==== Password Policies Another thing you should do to prevent password guess is to have a complex enough password policy to ensure that -users pick hard to guess passwords. See the <> chapter for more details. +users pick hard to guess passwords. See the <<_password-policies, Password Policies>> chapter for more details. The best way to prevent password guessing though is to set up the server to use a one-time-password (OTP). diff --git a/server_admin/topics/threat/clickjacking.adoc b/server_admin/topics/threat/clickjacking.adoc index e2da39499c3..ad2f10c742f 100644 --- a/server_admin/topics/threat/clickjacking.adoc +++ b/server_admin/topics/threat/clickjacking.adoc @@ -6,13 +6,13 @@ buttons that are carefully constructed to be placed directly under important but When a user clicks a visible button, they are actually clicking a button (such as a "login" button) on the hidden page. An attacker can steal a user's authentication credentials and access their resources. -By default, every response by {{book.project.name}} sets some specific browser headers that can prevent this from happening. +By default, every response by {project_name} sets some specific browser headers that can prevent this from happening. Specifically, it sets http://tools.ietf.org/html/rfc7034[X-FRAME_OPTIONS] and http://www.w3.org/TR/CSP/[Content-Security-Policy]. You should take a look at the definition of both of these headers as there is a lot of fine-grain browser access you can control. In the admin console you can specify the values these headers will have. Go to the `Realm Settings` left menu item and click the `Security Defenses` tab and make sure you are on the `Headers` sub-tab. -image:../../{{book.images}}/security-headers.png[] +image:{project_images}/security-headers.png[] -By default, {{book.project.name}} only sets up a _same-origin_ policy for iframes. +By default, {project_name} only sets up a _same-origin_ policy for iframes. diff --git a/server_admin/topics/threat/compromised-codes.adoc b/server_admin/topics/threat/compromised-codes.adoc index fedc3940058..756daefc69e 100644 --- a/server_admin/topics/threat/compromised-codes.adoc +++ b/server_admin/topics/threat/compromised-codes.adoc @@ -1,9 +1,9 @@ === Compromised Authorization Code -For the <>, it would be very hard for an attacker to compromise {{book.project.name}} authorization codes. -{{book.project.name}} generates a cryptographically strong random value for its authorization codes so it would be very hard to guess an access token. +For the <<_oidc-auth-flows, OIDC Auth Code Flow>>, it would be very hard for an attacker to compromise {project_name} authorization codes. +{project_name} generates a cryptographically strong random value for its authorization codes so it would be very hard to guess an access token. An authorization code can only be used once to obtain an access token. -In the admin console you can specify how long an authorization code is valid for on the <>. +In the admin console you can specify how long an authorization code is valid for on the <<_timeouts, timeouts page>>. This value should be really short, as short as a few seconds and just long enough for the client to make the request to obtain a token from the code. diff --git a/server_admin/topics/threat/compromised-tokens.adoc b/server_admin/topics/threat/compromised-tokens.adoc index 0c1ea5dd25f..c01beb97037 100644 --- a/server_admin/topics/threat/compromised-tokens.adoc +++ b/server_admin/topics/threat/compromised-tokens.adoc @@ -1,13 +1,13 @@ === Compromised Access and Refresh Tokens -There are a few things you can do to mitigate access tokens and refresh tokens from being stolen. The most important thing is to enforce SSL/HTTPS communication between {{book.project.name}} and its clients and applications. It might seem obvious, but since {{book.project.name}} does not have SSL enabled by default, an administrator might not realize that it is necessary. +There are a few things you can do to mitigate access tokens and refresh tokens from being stolen. The most important thing is to enforce SSL/HTTPS communication between {project_name} and its clients and applications. It might seem obvious, but since {project_name} does not have SSL enabled by default, an administrator might not realize that it is necessary. -Another thing you can do to mitigate leaked access tokens is to shorten their lifespans. You can specify this within the <>. +Another thing you can do to mitigate leaked access tokens is to shorten their lifespans. You can specify this within the <<_timeouts, timeouts page>>. Short lifespans (minutes) for access tokens for clients and applications to refresh their access tokens after a short amount of time. If an admin detects a leak, they can logout all user sessions to invalidate these refresh tokens or set up a revocation policy. Making sure refresh tokens always stay private to the client and are never transmitted ever is very important as well. -If an access token or refresh token is compromised, the first thing you should do is go to the admin console and push a not-before revocation policy to all applications. This will enforce that any tokens issued prior to that date are now invalid. Pushing new not-before policy will also ensure that application will be forced to download new public keys from {{book.project.name}}, hence it is also useful for the case, when you think that realm signing key was compromised. -More info in the <>. +If an access token or refresh token is compromised, the first thing you should do is go to the admin console and push a not-before revocation policy to all applications. This will enforce that any tokens issued prior to that date are now invalid. Pushing new not-before policy will also ensure that application will be forced to download new public keys from {project_name}, hence it is also useful for the case, when you think that realm signing key was compromised. +More info in the <<_realm_keys, keys chapter>>. You can also disable specific applications, clients, and users if you feel that any one of those entities is completely compromised. diff --git a/server_admin/topics/threat/csrf.adoc b/server_admin/topics/threat/csrf.adoc index a33c4bc77bc..8347464ac4c 100644 --- a/server_admin/topics/threat/csrf.adoc +++ b/server_admin/topics/threat/csrf.adoc @@ -6,13 +6,13 @@ web site trusts or has authenticated with(e.g. via HTTP redirects or HTML forms) These attacks are mitigated by matching a state cookie against a posted form or query parameter. The OAuth 2.0 login specification requires that a state cookie be used and matched against a transmitted state parameter. -{{book.project.name}} fully implements this part of the specification so all logins are protected. +{project_name} fully implements this part of the specification so all logins are protected. -The {{book.project.name}} Admin Console is a pure JavaScript/HTML5 application that makes REST calls to the backend {{book.project.name}} admin REST API. +The {project_name} Admin Console is a pure JavaScript/HTML5 application that makes REST calls to the backend {project_name} admin REST API. These calls all require bearer token authentication and are made via JavaScript Ajax calls. CSRF does not apply here. The admin REST API can also be configured to validate the CORS origins as well. -The only part of {{book.project.name}} that really falls into CSRF is the user account management pages. -To mitigate this {{book.project.name}} sets a state cookie and also embeds the value of this state cookie within hidden form fields or query parameters in action links. +The only part of {project_name} that really falls into CSRF is the user account management pages. +To mitigate this {project_name} sets a state cookie and also embeds the value of this state cookie within hidden form fields or query parameters in action links. This query or form parameter is checked against the state cookie to verify that the call was made by the user. diff --git a/server_admin/topics/threat/open-redirect.adoc b/server_admin/topics/threat/open-redirect.adoc index bff3a562fb7..146fd99cc76 100644 --- a/server_admin/topics/threat/open-redirect.adoc +++ b/server_admin/topics/threat/open-redirect.adoc @@ -5,8 +5,8 @@ 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. -{{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. +{project_name} requires that all registered applications and clients register at least one redirection URI pattern. +Any time a client asks {project_name} to perform a redirect (on login or logout for example), {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/server_admin/topics/threat/password-db-compromised.adoc b/server_admin/topics/threat/password-db-compromised.adoc index dd5a0f2cefa..43f1ddc8dd4 100644 --- a/server_admin/topics/threat/password-db-compromised.adoc +++ b/server_admin/topics/threat/password-db-compromised.adoc @@ -1,7 +1,7 @@ === Password database compromised -{{book.project.name}} does not store passwords in raw text. +{project_name} does not store passwords in raw text. It stores a hash of them using the PBKDF2 algorithm. It actually uses a default of 20,000 hashing iterations! This is the security community's recommended number of iterations. This can be a rather large performance hit on your system as PBKDF2, by design, gobbles up a significant amount of CPU. diff --git a/server_admin/topics/threat/redirect.adoc b/server_admin/topics/threat/redirect.adoc index 97e4878f822..0c1eb4c1ace 100644 --- a/server_admin/topics/threat/redirect.adoc +++ b/server_admin/topics/threat/redirect.adoc @@ -2,7 +2,7 @@ [[_unspecific-redirect-uris]] === Unspecific Redirect URIs -For the <>, if you register redirect URIs that +For the <<_oidc-auth-flows,Authorization Code Flow>>, if you register redirect URIs that are too general, then it would be possible for a rogue client to impersonate a different client that has a broader scope of access. This could happen for instance if two clients live under the same domain. So, it's a good idea to make your registered redirect URIs as specific as feasible. diff --git a/server_admin/topics/threat/scope.adoc b/server_admin/topics/threat/scope.adoc index b228c92ec16..74144bd37d1 100644 --- a/server_admin/topics/threat/scope.adoc +++ b/server_admin/topics/threat/scope.adoc @@ -4,5 +4,5 @@ By default, each new client application 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 <<_client_scope, Scope menu>> for each client. diff --git a/server_admin/topics/threat/sql.adoc b/server_admin/topics/threat/sql.adoc index faddd86d42c..518b173170b 100644 --- a/server_admin/topics/threat/sql.adoc +++ b/server_admin/topics/threat/sql.adoc @@ -1,5 +1,5 @@ === SQL Injection Attacks -At this point in time, there is no knowledge of any SQL injection vulnerabilities in {{book.project.name}}. +At this point in time, there is no knowledge of any SQL injection vulnerabilities in {project_name}. diff --git a/server_admin/topics/threat/ssl.adoc b/server_admin/topics/threat/ssl.adoc index 69f5feaa899..bd615202231 100644 --- a/server_admin/topics/threat/ssl.adoc +++ b/server_admin/topics/threat/ssl.adoc @@ -1,17 +1,17 @@ === SSL/HTTPS Requirement -If you do not use SSL/HTTPS for all communication between the {{book.project.name}} auth server and the clients it secures, you will be very vulnerable to man in the middle attacks. +If you do not use SSL/HTTPS for all communication between the {project_name} auth server and the clients it secures, you will be very vulnerable to man in the middle attacks. 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. -{{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 +{project_name} has <<_ssl_modes,three modes for SSL/HTTPS>>. +SSL can be hard to set up, so out of the box, {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. -On the adapter/client side, {{book.project.name}} allows you to turn off the SSL trust manager. +On the adapter/client side, {project_name} allows you to turn off the SSL trust manager. The trust manager ensures identity the client is talking to. It checks the DNS domain name against the server's certificate. In production you should make sure that each of your client adapters is configured to use a truststore. diff --git a/server_admin/topics/user-federation.adoc b/server_admin/topics/user-federation.adoc index aafb8e964cb..ec320e50a42 100644 --- a/server_admin/topics/user-federation.adoc +++ b/server_admin/topics/user-federation.adoc @@ -3,27 +3,27 @@ == User Storage Federation Many companies have existing user databases that hold information about users and their passwords or other credentials. -In may cases, it is just not possible to migrate off of those existing stores to a pure {{book.project.name}} deployment. -{{book.project.name}} can federate existing external user databases. +In may cases, it is just not possible to migrate off of those existing stores to a pure {project_name} deployment. +{project_name} can federate existing external user databases. Out of the box we have support for LDAP and Active Directory. You can also code your own extension for any custom user databases you might have using our User Storage SPI. -The way it works is that when a user logs in, {{book.project.name}} will look into its own internal user store to find the user. +The way it works is that when a user logs in, {project_name} will look into its own internal user store to find the user. If it can't find it there it will iterate -over every User Storage provider you have configured for the realm until it finds a match. Data from the external store is mapped into a common user model that is consumed by the {{book.project.name}} +over every User Storage provider you have configured for the realm until it finds a match. Data from the external store is mapped into a common user model that is consumed by the {project_name} runtime. This common user model can then be mapped to OIDC token claims and SAML assertion attributes. -External user databases rarely have every piece of data need to support all the features that {{book.project.name}} has. -In this case, the User Storage Provider can opt to store some things locally in the {{book.project.name}} user store. +External user databases rarely have every piece of data need to support all the features that {project_name} has. +In this case, the User Storage Provider can opt to store some things locally in the {project_name} user store. Some providers even import the user locally and sync periodically with the external store. All this depends on the capabilities of the provider and how its configured. For example, your -external user store may not support OTP. Depending on the provider, this OTP support can be handled and stored by {{book.project.name}} +external user store may not support OTP. Depending on the provider, this OTP support can be handled and stored by {project_name} === Adding a Provider To add a storage provider go to the `User Federation` left menu item in the Admin Console. .User Federation -image:../{{book.images}}/user-federation.png[] +image:{project_images}/user-federation.png[] On the right side, there is an `Add Provider` list box. Choose the provider type you want to add and you will be brought to the configuration page of that provider. diff --git a/server_admin/topics/user-federation/custom.adoc b/server_admin/topics/user-federation/custom.adoc index d31f0c58f3c..830197c68cf 100644 --- a/server_admin/topics/user-federation/custom.adoc +++ b/server_admin/topics/user-federation/custom.adoc @@ -1,5 +1,5 @@ === Custom Providers -{{book.project.name}} does have an SPI for User Storage Federation that you can use to write your own custom providers. -You can find documentation for this in our link:{{book.developerguide.link}}[{{book.developerguide.name}}]. +{project_name} does have an SPI for User Storage Federation that you can use to write your own custom providers. +You can find documentation for this in our link:{developerguide_link}[{developerguide_name}]. diff --git a/server_admin/topics/user-federation/ldap.adoc b/server_admin/topics/user-federation/ldap.adoc index 395d5ce6eaa..17786b10793 100644 --- a/server_admin/topics/user-federation/ldap.adoc +++ b/server_admin/topics/user-federation/ldap.adoc @@ -2,8 +2,8 @@ === LDAP and Active Directory -{{book.project.name}} comes with a built-in LDAP/AD provider. It is possible to federate multiple different LDAP servers in the same -{{book.project.name}} realm. You can map LDAP user attributes into the {{book.project.name}} common user model. +{project_name} comes with a built-in LDAP/AD provider. It is possible to federate multiple different LDAP servers in the same +{project_name} realm. You can map LDAP user attributes into the {project_name} common user model. By default, it maps username, email, first name, and last name, but you are free to configure additional <<_ldap_mappers,mappings>>. The LDAP provider also supports password validation via LDAP/AD protocols and different storage, edit, and synchronization modes. @@ -15,41 +15,41 @@ Selecting _ldap_ will bring you to the ldap configuration page. ==== Storage Mode -By default, {{book.project.name}} will import users from LDAP into the local {{book.project.name}} user database. This copy of the user +By default, {project_name} will import users from LDAP into the local {project_name} user database. This copy of the user is either synchronized on demand, or through a periodic background task. The one exception to this is passwords. Passwords are not imported and password validation is -delegated to the LDAP server. The benefits to this approach is that all {{book.project.name}} features will work as any extra +delegated to the LDAP server. The benefits to this approach is that all {project_name} features will work as any extra per-user data that is needed can be stored locally. This approach also reduces load on the LDAP server as uncached users are loaded -from the {{book.project.name}} database the 2nd time they are accessed. The only load your LDAP server will have is password validation. -The downside to this approach is that when a user is first queried, this will require a {{book.project.name}} database insert. The import will +from the {project_name} database the 2nd time they are accessed. The only load your LDAP server will have is password validation. +The downside to this approach is that when a user is first queried, this will require a {project_name} database insert. The import will also have to be synchronized with your LDAP server as needed. -Alternatively, you can choose not to import users into the {{book.project.name}} user database. In this case, the common user model -that the {{book.project.name}} runtime uses is backed only by the LDAP server. This means that if LDAP doesn't support -a piece of data that a {{book.project.name}} feature needs that feature will not work. +Alternatively, you can choose not to import users into the {project_name} user database. In this case, the common user model +that the {project_name} runtime uses is backed only by the LDAP server. This means that if LDAP doesn't support +a piece of data that a {project_name} feature needs that feature will not work. The benefit to this approach is that you do not have the overhead of importing and synchronizing a copy of the LDAP user into the -{{book.project.name}} user database. +{project_name} user database. This storage mode is controled by the `Import Enabled` switch. Set to `On` to import users. ==== Edit Mode -Users, through the <>, and admins through the Admin Console +Users, through the <<_account-service, User Account Service>>, and admins through the Admin Console have the ability to modify user metadata. Depending on your setup you may or may not have LDAP update privileges. The `Edit Mode` configuration option defines the edit policy you have with your LDAP store. 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. + {project_name} will show an error anytime anybody tries to update these fields. 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. UNSYNCED:: - Any changes to username, email, first name, last name, and passwords will be stored in {{book.project.name}} local storage. - It is up to you to figure out how to synchronize back to LDAP. This allows {{book.project.name}} deployments to support - updates of user metadata on a read-only LDAP server. This option only applies when you are importing users from LDAP into the local {{book.project.name}} user database. + Any changes to username, email, first name, last name, and passwords will be stored in {project_name} local storage. + It is up to you to figure out how to synchronize back to LDAP. This allows {project_name} deployments to support + updates of user metadata on a read-only LDAP server. This option only applies when you are importing users from LDAP into the local {project_name} user database. ==== Other config options @@ -60,12 +60,12 @@ Priority:: The priority of this provider when looking up users or for adding registrations. Sync Registrations:: - Does your LDAP support adding new users? Click this switch if you want new users created by {{book.project.name}} in the admin console or the registration page + Does your LDAP support adding new users? Click this switch if you want new users created by {project_name} in the admin console or the registration page to be added to LDAP. Allow Kerberos authentication:: Enable Kerberos/SPNEGO authentication in realm with users data provisioned from LDAP. - More info in <>. + More info in <<_kerberos,Kerberos section>>. Other options:: The rest of the configuration options should be self explanatory. @@ -74,10 +74,10 @@ Other options:: ==== Connect to LDAP over SSL When you configure a secured connection URL to your LDAP store(for example `ldaps://myhost.com:636` ), -{{book.project.name}} will use SSL for the communication with LDAP server. -The important thing is to properly configure a truststore on the {{book.project.name}} server side, otherwise {{book.project.name}} can't trust the SSL connection to LDAP. +{project_name} will use SSL for the communication with LDAP server. +The important thing is to properly configure a truststore on the {project_name} server side, otherwise {project_name} can't trust the SSL connection to LDAP. -The global truststore for the {{book.project.name}} can be configured with the Truststore SPI. Please check out the link:{{book.installguide.link}}[{{book.installguide.name}}] for more detail. +The global truststore for the {project_name} can be configured with the Truststore SPI. Please check out the link:{installguide_link}[{installguide_name}] for more detail. If you don't configure the 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 the JDK if the system property is not set). @@ -85,20 +85,20 @@ There is a configuration property `Use Truststore SPI` in the LDAP federation pr By default, the value is `Only for ldaps`, which is fine for most deployments. The Truststore SPI will only be used if the connection to LDAP starts with `ldaps`. -==== Sync of LDAP users to {{book.project.name}} +==== Sync of LDAP users to {project_name} -If you have import enabled, the LDAP Provider will automatically take care of synchronization (import) of needed LDAP users into the {{book.project.name}} local database. +If you have import enabled, the LDAP Provider will automatically take care of synchronization (import) of needed LDAP users into the {project_name} local database. As users log in, the LDAP provider will import the LDAP user -into the {{book.project.name}} database and then authenticate against the LDAP password. This is the only time users will be imported. +into the {project_name} database and then authenticate against the LDAP password. This is the only time users will be imported. If you go to the `Users` left menu item in the Admin Console and click the `View all users` button, you will only see those LDAP users that -have been authenticated at least once by {{book.project.name}}. It is implemented this way so that admins don't accidentally try to import a huge LDAP DB of users. +have been authenticated at least once by {project_name}. It is implemented this way so that admins don't accidentally try to import a huge LDAP DB of users. -If you want to sync all LDAP users into the {{book.project.name}} database, you may configure and enable the `Sync Settings` of the LDAP provider you configured. +If you want to sync all LDAP users into the {project_name} database, you may configure and enable the `Sync Settings` of the LDAP provider you configured. There are 2 types of synchronization: Periodic Full sync:: - This will synchronize all LDAP users into {{book.project.name}} DB. - Those LDAP users, which already exist in {{book.project.name}} and were changed in LDAP directly will be updated in {{book.project.name}} DB + This will synchronize all LDAP users into {project_name} DB. + Those LDAP users, which already exist in {project_name} and were changed in LDAP directly will be updated in {project_name} DB (For example if user `Mary Kelly` was changed in LDAP to `Mary Smith`). Periodic Changed users sync:: @@ -112,21 +112,21 @@ then set up a periodic sync of changed users. The configuration page for your L ==== LDAP Mappers LDAP mappers are `listeners`, which are triggered by the LDAP 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 built-in `mappers` for this provider. +They are triggered when a user logs in via LDAP and needs to be imported, during {project_name} initiated registration, or when a user is queried from the Admin Console. +When you create an LDAP Federation provider, {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. - So, for example, you can configure that LDAP attribute `mail` to the attribute `email` in the {{book.project.name}} database. - For this mapper implementation, there is always a one-to-one mapping (one LDAP attribute is mapped to one {{book.project.name}} attribute) + This allows you to specify which LDAP attribute is mapped to which attribute of {project_name} user. + So, for example, you can configure that LDAP attribute `mail` to the attribute `email` in the {project_name} database. + For this mapper implementation, there is always a one-to-one mapping (one LDAP attribute is mapped to one {project_name} attribute) 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. + 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 {project_name} database. 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. + This allows you to configure role mappings from LDAP into {project_name} role mappings. One Role mapper can be used to map LDAP roles (usually groups from a particular branch of LDAP tree) into roles corresponding to either realm roles or client roles of a specified client. It's not a problem to configure more Role mappers for the same LDAP provider. So for example you can specify that role mappings from groups under @@ -134,21 +134,21 @@ Role Mapper:: `ou=finance,dc=example,dc=org` will be mapped to client role mappings of client `finance` . Hardcoded Role Mapper:: - This mapper will grant a specified {{book.project.name}} role to each {{book.project.name}} user linked with LDAP. + This mapper will grant a specified {project_name} role to each {project_name} user linked with LDAP. Group Mapper:: - This allows you to configure group mappings from LDAP into {{book.project.name}} group mappings. - Group mapper can be used to map LDAP groups from a particular branch of an LDAP tree into groups in {{book.project.name}}. - It will also propagate user-group mappings from LDAP into user-group mappings in {{book.project.name}}. + This allows you to configure group mappings from LDAP into {project_name} group mappings. + Group mapper can be used to map LDAP groups from a particular branch of an LDAP tree into groups in {project_name}. + It will also propagate user-group mappings from LDAP into user-group mappings in {project_name}. MSAD User Account Mapper:: This mapper is specific to Microsoft Active Directory (MSAD). It's able to tightly integrate the MSAD user account state - into the {{book.project.name}} account state (account enabled, password is expired etc). + into the {project_name} account state (account enabled, password is expired etc). It's using the `userAccountControl` and `pwdLastSet` LDAP attributes. (both are specific to MSAD and are not LDAP standard). - For example if `pwdLastSet` is `0`, the {{book.project.name}} user is required to update their password + For example if `pwdLastSet` is `0`, the {project_name} user is required to update their password and there will be an UPDATE_PASSWORD required action added to the user. If `userAccountControl` is - `514` (disabled account) the {{book.project.name}} user is disabled as well. + `514` (disabled account) the {project_name} user is disabled as well. -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. +By default, there is set of User Attribute mappers that map basic {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. diff --git a/server_admin/topics/user-federation/sssd.adoc b/server_admin/topics/user-federation/sssd.adoc index 85a011be152..c14ad9b2c37 100644 --- a/server_admin/topics/user-federation/sssd.adoc +++ b/server_admin/topics/user-federation/sssd.adoc @@ -2,16 +2,16 @@ === SSSD and FreeIPA Identity Management Integration -{{book.project.name}} also comes with a built-in https://fedorahosted.org/sssd/wiki[SSSD] (System Security Services Daemon) plugin. SSSD is part of the latest Fedora or Red Hat Enterprise Linux and provides access to multiple identity and authentication providers. It provides benefits such as failover and offline support. To see configuration options and for more information see https://access.redhat.com/documentation/en-US/Red_Hat_Enterprise_Linux/7/html/System-Level_Authentication_Guide/SSSD.html[the Red Hat Enterprise Linux Identity Management documentation]. +{project_name} also comes with a built-in https://fedorahosted.org/sssd/wiki[SSSD] (System Security Services Daemon) plugin. SSSD is part of the latest Fedora or Red Hat Enterprise Linux and provides access to multiple identity and authentication providers. It provides benefits such as failover and offline support. To see configuration options and for more information see https://access.redhat.com/documentation/en-US/Red_Hat_Enterprise_Linux/7/html/System-Level_Authentication_Guide/SSSD.html[the Red Hat Enterprise Linux Identity Management documentation]. -SSSD also integrates with the http://www.freeipa.org/page/Main_Page[FreeIPA identity management (IdM)] server, providing authentication and access control. For {book_project_name}, we benefit from this integration authenticating against http://tldp.org/HOWTO/User-Authentication-HOWTO/x115.html[PAM] services and retrieving user data from SSSD. For more information about using Red Hat Identity Management in Linux environments, see https://access.redhat.com/documentation/en-US/Red_Hat_Enterprise_Linux/7/html/Linux_Domain_Identity_Authentication_and_Policy_Guide/index.html[the Red Hat Enterprise Linux Identity Management documentation]. +SSSD also integrates with the http://www.freeipa.org/page/Main_Page[FreeIPA identity management (IdM)] server, providing authentication and access control. For {project_name}, we benefit from this integration authenticating against http://tldp.org/HOWTO/User-Authentication-HOWTO/x115.html[PAM] services and retrieving user data from SSSD. For more information about using Red Hat Identity Management in Linux environments, see https://access.redhat.com/documentation/en-US/Red_Hat_Enterprise_Linux/7/html/Linux_Domain_Identity_Authentication_and_Policy_Guide/index.html[the Red Hat Enterprise Linux Identity Management documentation]. -image:../../{{book.images}}/keycloak-sssd-freeipa-integration-overview.png[] +image:{project_images}/keycloak-sssd-freeipa-integration-overview.png[] -Most of the communication between {{book.project.name}} and SSSD occurs through read-only D-Bus interfaces. For this reason, the only way to provision and update users is to use the FreeIPA/IdM administration interface. By default, like the LDAP federation provider, it is set up only to import username, email, first name, and last name. +Most of the communication between {project_name} and SSSD occurs through read-only D-Bus interfaces. For this reason, the only way to provision and update users is to use the FreeIPA/IdM administration interface. By default, like the LDAP federation provider, it is set up only to import username, email, first name, and last name. [NOTE] -Groups and roles are automatically registered, but not synchronized, so any changes made by the {{book.project.name}} administrator directly in {{book.project.name}} is not synchronized with SSSD. +Groups and roles are automatically registered, but not synchronized, so any changes made by the {project_name} administrator directly in {project_name} is not synchronized with SSSD. Information on how to configure the FreeIPA/IdM server follows. @@ -34,7 +34,7 @@ After the container starts, change `/etc/hosts` to: If you do not make this change, you must set up a DNS server. -So that the SSSD federation provider is started and running on {{book.project.name}} you must enroll your Linux machine in the IPA domain: +So that the SSSD federation provider is started and running on {project_name} you must enroll your Linux machine in the IPA domain: ipa-client-install --mkhomedir -p admin -w password @@ -54,15 +54,15 @@ First, you have to install the sssd-dbus RPM, which allows information from SSSD $ sudo yum install sssd-dbus -{% if book.community %} +ifeval::[{project_community}==true] You must run the provisioning script available from the Keycloak distribution: $ bin/federation-sssd-setup.sh -{% endif %} +endif::[] -{% if book.product %} +ifeval::[{project_product}==true] You must run this provisioning script: @@ -71,7 +71,7 @@ You must run this provisioning script: $ .../bin/federation-sssd-setup.sh ---- -{% endif %} +endif::[] This script makes the necessary changes to `/etc/sssd/sssd.conf`: @@ -95,20 +95,20 @@ Ensure everything is working as expected by running `dbus-send`: sudo dbus-send --print-reply --system --dest=org.freedesktop.sssd.infopipe /org/freedesktop/sssd/infopipe org.freedesktop.sssd.infopipe.GetUserGroups string:john -You should be able to see the user's group. If this command returns a timeout or an error, it means that the federation provider will also not be able to retrieve anything on {{book.project.name}}. +You should be able to see the user's group. If this command returns a timeout or an error, it means that the federation provider will also not be able to retrieve anything on {project_name}. Most of the time this occurs because the machine was not enrolled in the FreeIPA IdM server or you do not have permission to access the SSSD service. -If you do not have permission, ensure that the user running {{book.project.name}} is included in the `/etc/sssd/sssd.conf` file in the following section: +If you do not have permission, ensure that the user running {project_name} is included in the `/etc/sssd/sssd.conf` file in the following section: [ifp] allowed_uids = root, your_username ==== Enabling the SSSD Federation Provider -{{book.project.name}} uses DBus-Java to communicate at a low level with D-Bus, which depends on the http://www.matthew.ath.cx/projects/java/[Unix Sockets Library]. +{project_name} uses DBus-Java to communicate at a low level with D-Bus, which depends on the http://www.matthew.ath.cx/projects/java/[Unix Sockets Library]. -{% if book.community %} +ifeval::[{project_community}==true] An RPM for this library can be found in https://github.com/keycloak/libunix-dbus-java/releases[this repository]. Before installing it, be sure to check the RPM signature: @@ -120,17 +120,17 @@ An RPM for this library can be found in https://github.com/keycloak/libunix-dbus MD5 digest: OK (770c2e68d052cb4a4473e1e9fd8818cf) $ sudo yum install libunix-dbus-java-0.8.0-1.fc24.x86_64.rpm -{% endif %} +endif::[] -{% if book.product %} +ifeval::[{project_product}==true] Before enabling the SSSD Federation provider, you must install the RPM for this library: $ sudo yum install rh-sso7-libunix-dbus-java -{% endif %} +endif::[] -For authentication with PAM {{book.project.name}} uses JNA. Be sure you have this package installed: +For authentication with PAM {project_name} uses JNA. Be sure you have this package installed: $ sudo yum install jna @@ -145,5 +145,5 @@ To configure a federated SSSD store, complete the following steps: . From the *Add Provider* dropdown list, select *sssd.* The sssd configuration page opens. . Click *Save*. -Now you can authenticate against {{book.project.name}} using FreeIPA/IdM credentials. +Now you can authenticate against {project_name} using FreeIPA/IdM credentials. diff --git a/server_admin/topics/users/attributes.adoc b/server_admin/topics/users/attributes.adoc index 95ffe39530c..e0ce4568f1f 100644 --- a/server_admin/topics/users/attributes.adoc +++ b/server_admin/topics/users/attributes.adoc @@ -5,7 +5,7 @@ Beyond basic user metadata like name and email, you can store arbitrary user att then click on the `Attributes` tab. .Users -image:../../{{book.images}}/user-attributes.png[] +image:{project_images}/user-attributes.png[] Enter in the attribute name and value in the empty fields and click the `Add` button next to it to add a new field. Note that any edits you make on this page will not be stored until you hit the `Save` button. diff --git a/server_admin/topics/users/create-user.adoc b/server_admin/topics/users/create-user.adoc old mode 100755 new mode 100644 index 22d302ec86d..b9619272782 --- a/server_admin/topics/users/create-user.adoc +++ b/server_admin/topics/users/create-user.adoc @@ -5,13 +5,13 @@ To create a user click on `Users` in the left menu bar. .Users -image:../../{{book.images}}/users.png[] +image:{project_images}/users.png[] This menu option brings you to the user list page. On the right side of the empty user list, you should see an `Add User` button. Click that to start creating your new user. .Add User -image:../../{{book.images}}/add-user.png[] +image:{project_images}/add-user.png[] The only required field is `Username`. Click save. This will bring you to the management page for your new user. diff --git a/server_admin/topics/users/credentials.adoc b/server_admin/topics/users/credentials.adoc index 7569aeb2b81..e9ebe8a34af 100644 --- a/server_admin/topics/users/credentials.adoc +++ b/server_admin/topics/users/credentials.adoc @@ -5,7 +5,7 @@ When viewing a user if you go to the `Credentials` tab you can manage a user's credentials. .Credential Management -image:../../{{book.images}}/user-credentials.png[] +image:{project_images}/user-credentials.png[] ==== Changing Passwords @@ -13,7 +13,7 @@ To change a user's password, type in a new one. A `Reset Password` button will If the `Temporary` switch is on, this new password can only be used once and the user will be asked to change their password after they have logged in. -Alternatively, if you have <> set up, you can send an email to the user that asks +Alternatively, if you have <<_email, email>> 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 `Send Email`. You can optionally set the validity of the e-mail link which defaults to the one preset in `Tokens` tab in the realm settings. The sent email contains a link that will bring the user to the update password screen. diff --git a/server_admin/topics/users/impersonation.adoc b/server_admin/topics/users/impersonation.adoc index 8cde415e0d1..0b671256f13 100644 --- a/server_admin/topics/users/impersonation.adoc +++ b/server_admin/topics/users/impersonation.adoc @@ -6,7 +6,7 @@ an admin may want to impersonate the user to see if they can duplicate the probl can impersonate a user. There are two locations an admin can initiate impersonation. The first is on the `Users` list tab. .Users -image:../../{{book.images}}/user-search.png[] +image:{project_images}/user-search.png[] You can see here that the admin has searched for `jim`. Next to Jim's account you can see an impersonate button. Click that to impersonate the user. @@ -14,7 +14,7 @@ to impersonate the user. Also, you can impersonate the user from the user `Details` tab. .User Details -image:../../{{book.images}}/user-details.png[] +image:{project_images}/user-details.png[] Near the bottom of the page you can see the `Impersonate` button. Click that to impersonate the user. @@ -23,5 +23,5 @@ in as the user being impersonated. If the admin and user are not in the same re be logged in as the user in that user's realm. In both cases, the browser will be redirected to the impersonated user's User Account Management page. -Any user with the realm's `impersonation` role can impersonate a user. Please see the <> chapter +Any user with the realm's `impersonation` role can impersonate a user. Please see the <<_admin_permissions,Admin Console Access Control>> chapter for more details on assigning administration permissions. diff --git a/server_admin/topics/users/recaptcha.adoc b/server_admin/topics/users/recaptcha.adoc old mode 100755 new mode 100644 index 68ad7cad661..b979f465bbe --- a/server_admin/topics/users/recaptcha.adoc +++ b/server_admin/topics/users/recaptcha.adoc @@ -2,17 +2,17 @@ ==== reCAPTCHA Support -To safeguard registration against bots, {{book.project.name}} has integration with Google reCAPTCHA. +To safeguard registration against bots, {project_name} has integration with Google reCAPTCHA. To enable this you need to first go to link:https://developers.google.com/recaptcha/[Google Recaptcha Website] and create an API key so that you can get your reCAPTCHA site key and secret. (FYI, localhost works by default so you don't have to specify a domain). -Next, there are a few steps you need to perform in the {{book.project.name}} Admin Console. +Next, there are a few steps you need to perform in the {project_name} Admin Console. Click the `Authentication` left menu item and go to the `Flows` tab. Select the `Registration` flow from the drop down list on this page. .Registration Flow -image:../../{{book.images}}/registration-flow.png[] +image:{project_images}/registration-flow.png[] Set the 'reCAPTCHA' requirement to `Required` by clicking the appropriate radio button. This will enable @@ -20,18 +20,18 @@ reCAPTCHA on the screen. Next, you have to enter in the reCAPTCHA site key and Click on the 'Actions' button that is to the right of the reCAPTCHA flow entry, then "Config" link, and enter in the reCAPTCHA site key and secret on this config page. .Recaptcha Config Page -image:../../{{book.images}}/recaptcha-config.png[] +image:{project_images}/recaptcha-config.png[] -The final step you have to do is to change some default HTTP response headers that {{book.project.name}} sets. {{book.project.name}} +The final step you have to do is to change some default HTTP response headers that {project_name} sets. {project_name} will prevent a website from including any login page within an iframe. This is to prevent clickjacking attacks. You need to authorize Google to use the registration page within an iframe. Go to the `Realm Settings` left menu item and then go to the `Security Defenses` tab. You will need to add `https://www.google.com` to the values of both the `X-Frame-Options` and `Content-Security-Policy` headers. .Authorizing Iframes -image:../../{{book.images}}/security-headers.png[] +image:{project_images}/security-headers.png[] Once you do this, reCAPTCHA should show up on your registration page. You may want to edit _register.ftl_ in your login -theme to muck around with the placement and styling of the reCAPTCHA button. See the link:{{book.developerguide.link}}[{{book.developerguide.name}}] +theme to muck around with the placement and styling of the reCAPTCHA button. See the link:{developerguide_link}[{developerguide_name}] for more information on extending and creating themes. diff --git a/server_admin/topics/users/required-actions.adoc b/server_admin/topics/users/required-actions.adoc index 8bc9e7cae31..70270f33b13 100644 --- a/server_admin/topics/users/required-actions.adoc +++ b/server_admin/topics/users/required-actions.adoc @@ -18,7 +18,7 @@ Update Profile:: Admins can add required actions for each individual user within the user's `Details` tab in the Admin Console. .Setting Required Action -image:../../{{book.images}}/user-required-action.png[] +image:{project_images}/user-required-action.png[] In the `Required User Actions` list box, select all the actions you want to add to the account. If you want to remove one, click the `X` next to the action name. Also remember to click the `Save` button after you've decided what actions to add. @@ -26,18 +26,18 @@ action name. Also remember to click the `Save` button after you've decided what ==== Default Required Actions You can also specify required actions that will be added to an account whenever a new user is created, i.e. through the `Add User` button the user -list screen, or via the <> link on the login page. To specify +list screen, or via the <<_user-registration, user registration>> link on the login page. To specify the default required actions go to the `Authentication` left menu item and click on the `Required Actions` tab. .Default Required Actions -image:../../{{book.images}}/default-required-actions.png[] +image:{project_images}/default-required-actions.png[] Simply click the checkbox in the `Default Action` column of the required actions that you want to be executed when a brand new user logs in. ==== Terms and Conditions Many organizations have a requirement that when a new user logs in for the first time, they need to agree to the terms and conditions -of the website. {{book.project.name}} has this functionality implemented as a required action, but it requires some configuration. For one, you +of the website. {project_name} has this functionality implemented as a required action, but it requires some configuration. For one, you have to go to the `Required Actions` tab described earlier and enable the `Terms and Conditions` action. You must also edit the -_terms.ftl_ file in the _base_ login theme. See the link:{{book.developerguide.link}}[{{book.developerguide.name}}] for more information on extending and +_terms.ftl_ file in the _base_ login theme. See the link:{developerguide_link}[{developerguide_name}] for more information on extending and creating themes. diff --git a/server_admin/topics/users/user-registration.adoc b/server_admin/topics/users/user-registration.adoc index 2a0f2b636c6..2a014bc1c2e 100644 --- a/server_admin/topics/users/user-registration.adoc +++ b/server_admin/topics/users/user-registration.adoc @@ -2,26 +2,26 @@ === User Registration -You can enable {{book.project.name}} to allow user self registration. When enabled, the login page has a registration +You can enable {project_name} to allow user self registration. When enabled, the login page has a registration link the user can click on to create their new account. Enabling registration is pretty simple. Go to the `Realm Settings` left menu and click it. Then go to the `Login` tab. There is a `User Registration` switch on this tab. Turn it on, then click the `Save` button. .Login Tab -image:../../{{book.images}}/login-tab.png[] +image:{project_images}/login-tab.png[] After you enable this setting, a `Register` link should show up on the login page. .Registration Link -image:../../{{book.images}}/registration-link.png[] +image:{project_images}/registration-link.png[] Clicking on this link will bring the user to the registration page where they have to enter in some user profile information and a new password. .Registration Form -image:../../{{book.images}}/registration-form.png[] +image:{project_images}/registration-form.png[] You can change the look and feel of the registration form as well as removing or adding additional fields that must be entered. -See the link:{{book.developerguide.link}}[{{book.developerguide.name}}] for more information. +See the link:{developerguide_link}[{developerguide_name}] for more information. diff --git a/server_admin/topics/users/viewing.adoc b/server_admin/topics/users/viewing.adoc index 311d97cbb18..de91639f1bd 100644 --- a/server_admin/topics/users/viewing.adoc +++ b/server_admin/topics/users/viewing.adoc @@ -4,16 +4,16 @@ If you need to manage a specific user, click on `Users` in the left menu bar. .Users -image:../../{{book.images}}/users.png[] +image:{project_images}/users.png[] This menu option brings you to the user list page. In the search box you can type in a full name, last name, or email address you want to search for in the user database. The query will bring up all users that match your criteria. The `View all users` button -will list every user in the system. This will search just local {{book.project.name}} database and not the federated database (ie. LDAP) -because some backends like LDAP don't have a way to page through users. So if you want the users from federated backend to be synced into {{book.project.name}} +will list every user in the system. This will search just local {project_name} database and not the federated database (ie. LDAP) +because some backends like LDAP don't have a way to page through users. So if you want the users from federated backend to be synced into {project_name} database you need to either: -* Adjust search criteria. That will sync just the backend users matching the criteria into {{book.project.name}} database. +* Adjust search criteria. That will sync just the backend users matching the criteria into {project_name} database. * Go to `User Federation` tab and click `Sync all users` or `Sync changed users` in the page with your federation provider. -See <> for more details. +See <<_user-storage-federation,User Federation>> for more details. diff --git a/server_development/README.adoc b/server_development/README.adoc deleted file mode 100755 index 36725b2eb59..00000000000 --- a/server_development/README.adoc +++ /dev/null @@ -1,9 +0,0 @@ - -= Server Developer - -image:images/keycloak_logo.png[alt="Keycloak"] - -{{book.project.name}} {{book.project.version}} - -http://www.keycloak.org - diff --git a/server_development/SUMMARY.adoc b/server_development/SUMMARY.adoc deleted file mode 100755 index 947d75bf29a..00000000000 --- a/server_development/SUMMARY.adoc +++ /dev/null @@ -1,30 +0,0 @@ -= Server Developer Guide - - .. link:server_development/topics/preface.adoc[Preface] - .. link:server_development/topics/admin-rest-api.adoc[Admin REST API] - .. link:server_development/topics/themes.adoc[Themes] - .. link:server_development/topics/custom-attributes.adoc[Custom User Attributes] - .. link:server_development/topics/identity-brokering.adoc[Identity Brokering APIs] - ... link:server_development/topics/identity-brokering/tokens.adoc[Retrieving External IDP Tokens] - ... link:server_development/topics/identity-brokering/account-linking.adoc[Client Initiated Account Linking] -{% if book.community %} - .. link:server_development/topics/providers.adoc[Service Provider Interfaces (SPI)] - .. link:server_development/topics/extensions.adoc[Extending Server] - .. link:server_development/topics/auth-spi.adoc[Authentication SPI] - .. link:server_development/topics/action-token-spi.adoc[Action Token SPI] - .. link:server_development/topics/events.adoc[Event Listener SPI] -{% endif %} - .. link:server_development/topics/user-storage.adoc[User Storage SPI] - ... link:server_development/topics/user-storage/provider-interfaces.adoc[Provider Interfaces] - ... link:server_development/topics/user-storage/provider-capability-interfaces.adoc[Provider Capability Interfaces] - ... link:server_development/topics/user-storage/model-interfaces.adoc[Model Interfaces] - ... link:server_development/topics/user-storage/packaging.adoc[Packaging and Deployment] - ... link:server_development/topics/user-storage/simple-example.adoc[Simple Read-Only, Lookup Example] - ... link:server_development/topics/user-storage/configuration.adoc[Configuration Techniques] - ... link:server_development/topics/user-storage/registration-query.adoc[Add/Remove User and Query Capability interfaces] - ... link:server_development/topics/user-storage/augmenting.adoc[Augmenting External Storage] - ... link:server_development/topics/user-storage/import.adoc[Import Implementation Strategy] - ... link:server_development/topics/user-storage/cache.adoc[User Caches] - ... link:server_development/topics/user-storage/javaee.adoc[Leveraging Java EE] - ... link:server_development/topics/user-storage/rest.adoc[REST Management API] - ... link:server_development/topics/user-storage/migration.adoc[Migrating from an Earlier User Federation SPI] diff --git a/server_development/book-product.json b/server_development/book-product.json deleted file mode 100755 index 0d30cdbae2a..00000000000 --- a/server_development/book-product.json +++ /dev/null @@ -1,48 +0,0 @@ -{ - "gitbook": "2.x.x", - "structure": { - "readme": "README.adoc" - }, - "plugins": [ - "toggle-chapters", - "ungrey", - "splitter" - ], - "variables": { - "title": "Server Developer Guide", - "project": { - "name": "Red Hat Single Sign-On", - "version": "7.1.0", - "doc_base_url": "https://access.redhat.com/documentation/en/red-hat-single-sign-on/", - "doc_info_version_url": "7.1" - }, - "community": false, - "product": true, - "images": "rhsso-images", - "adminguide": { - "name": "Server Administration Guide", - "link": "https://access.redhat.com/documentation/en/red-hat-single-sign-on/7.1/html-single/server-administration-guide/" - }, - "clientguide": { - "name": "Securing Applications and Services Guide", - "link": "https://access.redhat.com/documentation/en/red-hat-single-sign-on/7.1/html-single/securing-applications-and-services-guide/" - - }, - "installguide": { - "name": "Server Installation and Configuration Guide", - "link": "https://access.redhat.com/documentation/en/red-hat-single-sign-on/7.1/html-single/server-installation-and-configuration-guide/" - }, - "apidocs": { - "name": "API Documentation", - "link": "https://access.redhat.com/documentation/en/red-hat-single-sign-on/7.1/html-single/api-documentation/" - }, - "adapterguide": { - "name": "JavaScript OpenID Connect Adapter", - "link": "https://access.redhat.com/documentation/en/red-hat-single-sign-on/7.1/html-single/securing-applications-and-services-guide#javascript_adapter" - }, - - "subsystem": { - "undertow": "urn:jboss:domain:undertow:3.1" - } - } -} diff --git a/server_development/book.json b/server_development/book.json deleted file mode 100755 index bcb46beb592..00000000000 --- a/server_development/book.json +++ /dev/null @@ -1,35 +0,0 @@ -{ - "gitbook": "2.x.x", - "structure": { - "readme": "README.adoc" - }, - "plugins": [ - "toggle-chapters", - "ungrey", - "splitter" - ], - "variables": { - "title": "Server Developer Guide", - "project": { - "name": "Keycloak", - "version": "SNAPSHOT" - }, - "community": true, - "product": false, - "images": "keycloak-images", - - "clientguide": { - "name": "Securing Applications and Services Guide", - "link": "https://keycloak.gitbooks.io/securing-client-applications-guide/content/" - - }, - "installguide": { - "name": "Server Installation and Configuration Guide", - "link": "https://keycloak.gitbooks.io/server-installation-and-configuration/content/" - }, - "apidocs": { - "name": "API Documentation", - "link": "http://keycloak.org/docs" - } - } -} diff --git a/server_development/buildGuide.sh b/server_development/buildGuide.sh deleted file mode 100755 index b37f0c97dd0..00000000000 --- a/server_development/buildGuide.sh +++ /dev/null @@ -1,80 +0,0 @@ -# Build the guide - -# Find the directory name and full path -CURRENT_GUIDE=${PWD##*/} -CURRENT_DIRECTORY=$(pwd) - -usage(){ - cat <&2 - usage - exit 1;; - esac -done - -echo "" -echo "********************************************" -echo " Building $CURRENT_GUIDE " -echo "********************************************" -if [ ! -d target ]; then - echo "You must run 'python gitlab-conversion.py' to convert the content before you run this script." - exit -fi - -# Remove the guide directory path from the master.adoc file as it is not needed -echo "" -echo "***************************************************************************************" -echo "Removing the guide directory path from the master.adoc file as it is not needed." -echo "NOTE: The guide directory path should probably be removed from the SUMMARY.adoc file," -echo "but since we do not know if it will break the upstream build, we are doing this here. " -echo "If it can not be removed from the SUMMARY.adoc file, this should really be done in the " -echo "Python script because otherwise you must run this script before porting content!" -echo "***************************************************************************************" -echo "" -find . -name 'master.adoc' -print | xargs sed -i "s/include::$CURRENT_GUIDE\//include::/g" - -# Remove the html and build directories and then recreate the html/images/ directory -if [ -d target/html ]; then - rm -r target/html/ -fi -if [ -d target/html ]; then - rm -r target/html/ -fi - -mkdir -p html -cp -r target/images/ target/html/ - -echo "Building an asciidoctor version of the guide" -asciidoctor -t -dbook -a toc -o target/html/$CURRENT_GUIDE.html target/master.adoc - -echo "" -echo "Building a ccutil version of the guide" -ccutil compile --lang en_US --format html-single --main-file target/master.adoc - -cd .. - -echo "View the asciidoctor build here: " file://$CURRENT_DIRECTORY/target/html/$CURRENT_GUIDE.html - -if [ -d $CURRENT_DIRECTORY/build/tmp/en-US/html-single/ ]; then - echo "View the ccutil build here: " file://$CURRENT_DIRECTORY/build/tmp/en-US/html-single/index.html - exit 0 -else - echo -e "${RED}Build using ccutil failed!" - echo -e "${BLACK}See the log above for details." - exit 1 -fi diff --git a/server_development/gitlab-conversion.py b/server_development/gitlab-conversion.py deleted file mode 100755 index f2e87906cc9..00000000000 --- a/server_development/gitlab-conversion.py +++ /dev/null @@ -1,113 +0,0 @@ -import sys, os, re, json, shutil, errno - -def transform(root, f, targetdir): - full = os.path.join(root, f) - input = open(full, 'r').read() - dir = os.path.join(targetdir, root) - if not os.path.exists(dir): - os.makedirs(dir) - output = open(os.path.join(dir, f), 'w') - input = applyTransformation(input) - output.write(input) - - -def applyTransformation(input): - for variable in re.findall(r"\{\{(.*?)\}\}", input): - tmp = variable.replace('.', '_') - input = input.replace(variable, tmp) - input = input.replace('{{', '{').replace('}}', '}') - input = re.sub(r"<}==true]\g<2>endif::[]", input) - input = re.sub(r"image:(\.\./)*", "image:", input) - input = re.sub(r"image::(\.\./)*", "image::", input) - return input - - -indir = 'topics' -targetdir = 'target' -if len(sys.argv) > 1: - targetdir = sys.argv[1] - -if os.path.exists(targetdir): - shutil.rmtree(targetdir) - -if os.path.isdir('images'): - shutil.copytree('images',os.path.join(targetdir, 'images')) -if os.path.isdir('keycloak-images'): - shutil.copytree('keycloak-images',os.path.join(targetdir, 'keycloak-images')) -if os.path.isdir('rhsso-images'): - shutil.copytree('rhsso-images',os.path.join(targetdir, 'rhsso-images')) - -shutil.copyfile('metadata.ini', os.path.join(targetdir, 'metadata.ini')); -shutil.copyfile('master-docinfo.xml', os.path.join(targetdir, 'master-docinfo.xml')); - -tmp = os.path.join(targetdir, 'topics') -if not os.path.exists(tmp): - os.makedirs(tmp) - -# transform files -for root, dirs, filenames in os.walk(indir): - for f in filenames: - transform(root,f,targetdir) - -# Create master.doc includes -input = open('SUMMARY.adoc', 'r').read() -output = open(os.path.join(targetdir, 'master.adoc'), 'w') - -output.write(""" -:toc: -:toclevels: 3 -:numbered: - -include::document-attributes.adoc[] -""") - -input = re.sub(r"[ ]*\.+\s*link:[^/]+/(.*)\[(.*)\]", "include::\g<1>[]", input) -input = applyTransformation(input) -output.write(input) - -# parse book-product.json file and create document attributes -with open('book-product.json') as data_file: - data = json.load(data_file) - -variables = data['variables'] - -def makeAttributes(variables, variable, list): - for i in variables.keys(): - if variable is None: - tmp = i - else: - tmp = variable + '_' + i - if isinstance(variables[i],dict): - makeAttributes(variables[i], tmp, list) - elif isinstance(variables[i],bool): - boolval = 'false' - if variables[i]: - boolval = 'true' - list.append({tmp: boolval}) - else: - list.append({tmp: str(variables[i])}) - - -attributeList = [] -makeAttributes(variables, None, attributeList) - -output = open(os.path.join(targetdir, 'document-attributes.adoc'), 'w') -for attribute in attributeList: - for k in attribute.keys(): - output.write(':book_' + k + ": " + attribute[k] + "\n") - -print "Transformation complete!" - - - - - - - - - diff --git a/server_development/index.adoc b/server_development/index.adoc new file mode 100644 index 00000000000..7e6c6cf73db --- /dev/null +++ b/server_development/index.adoc @@ -0,0 +1,6 @@ +:toc: +:toclevels: 3 +:numbered: + +include::../document-attributes-community.adoc[] +include::topics.adoc[] \ No newline at end of file diff --git a/server_development/master-docinfo.xml b/server_development/master-docinfo.xml old mode 100755 new mode 100644 index b8b06f3ddd8..d97e3a207d2 --- a/server_development/master-docinfo.xml +++ b/server_development/master-docinfo.xml @@ -1,10 +1,10 @@ -{book_project_name} -{book_project_doc_info_version_url} -For Use with {book_project_name} {book_project_doc_info_version_url} -{book_title} -{book_project_doc_info_version_url} +{project_name} +{project_doc_info_version_url} +For Use with {project_name} {project_doc_info_version_url} +{title} +{project_doc_info_version_url} - This guides consist of information for developers to customize {book_project_name} {book_project_doc_info_version_url} + This guides consist of information for developers to customize {project_name} {project_doc_info_version_url} Red Hat Customer Content Services diff --git a/server_development/master.adoc b/server_development/master.adoc new file mode 100644 index 00000000000..cc0fdffa8d3 --- /dev/null +++ b/server_development/master.adoc @@ -0,0 +1,6 @@ +:toc: +:toclevels: 3 +:numbered: + +include::../document-attributes-product.adoc[] +include::topics.adoc[] \ No newline at end of file diff --git a/server_development/pom.xml b/server_development/pom.xml new file mode 100644 index 00000000000..aced76bf0a7 --- /dev/null +++ b/server_development/pom.xml @@ -0,0 +1,29 @@ + + + 4.0.0 + + + org.keycloak.documentation + documentation-parent + 1.0.0-SNAPSHOT + ../ + + + Server Developer + server-development + pom + + + + + org.asciidoctor + asciidoctor-maven-plugin + + + asciidoc-to-html + + + + + + diff --git a/server_development/topics.adoc b/server_development/topics.adoc new file mode 100644 index 00000000000..6cc2e310499 --- /dev/null +++ b/server_development/topics.adoc @@ -0,0 +1,28 @@ +include::topics/preface.adoc[] +include::topics/admin-rest-api.adoc[] +include::topics/themes.adoc[] +include::topics/custom-attributes.adoc[] +include::topics/identity-brokering.adoc[] +include::topics/identity-brokering/tokens.adoc[] +include::topics/identity-brokering/account-linking.adoc[] +ifeval::[{project_community}==true] +include::topics/providers.adoc[] +include::topics/extensions.adoc[] +include::topics/auth-spi.adoc[] +include::topics/action-token-spi.adoc[] +include::topics/events.adoc[] +endif::[] +include::topics/user-storage.adoc[] +include::topics/user-storage/provider-interfaces.adoc[] +include::topics/user-storage/provider-capability-interfaces.adoc[] +include::topics/user-storage/model-interfaces.adoc[] +include::topics/user-storage/packaging.adoc[] +include::topics/user-storage/simple-example.adoc[] +include::topics/user-storage/configuration.adoc[] +include::topics/user-storage/registration-query.adoc[] +include::topics/user-storage/augmenting.adoc[] +include::topics/user-storage/import.adoc[] +include::topics/user-storage/cache.adoc[] +include::topics/user-storage/javaee.adoc[] +include::topics/user-storage/rest.adoc[] +include::topics/user-storage/migration.adoc[] diff --git a/server_development/topics/action-token-spi.adoc b/server_development/topics/action-token-spi.adoc index 75822b46966..f501990c53e 100644 --- a/server_development/topics/action-token-spi.adoc +++ b/server_development/topics/action-token-spi.adoc @@ -5,7 +5,7 @@ An action token is a special instance of Json Web Token (JWT) that permits its b reset a password or validate e-mail address. They are usually sent to users in form of a link that points to an endpoint processing action tokens for a particular realm. -{{book.project.name}} offers four basic token types allowing the bearer to: +{project_name} offers four basic token types allowing the bearer to: * Reset credentials * Confirm e-mail address @@ -33,7 +33,7 @@ In addition, an action token can contain any number of custom fields serializabl === Action Token Processing -When an action token is passed to a {{book.project.name}} endpoint +When an action token is passed to a {project_name} endpoint `_KEYCLOAK_ROOT_/auth/realms/master/login-actions/action-token` via `key` parameter, it is validated and a proper action token handler is executed. The processing always takes place in a context of an authentication session, either a fresh one or the action token service joins an existing authentication session (details are described below). The action token diff --git a/server_development/topics/admin-rest-api.adoc b/server_development/topics/admin-rest-api.adoc index dfb5e0ab390..36b66d19ea6 100644 --- a/server_development/topics/admin-rest-api.adoc +++ b/server_development/topics/admin-rest-api.adoc @@ -1,14 +1,14 @@ == Admin REST API -{{book.project.name}} comes with a fully functional Admin REST API with all features provided by the Admin Console. +{project_name} comes with a fully functional Admin REST API with all features provided by the Admin Console. To invoke the API you need to obtain an access token with the appropriate permissions. The required permissions are described in -{{book.adminguide.link}}[{{book.adminguide.name}}]. +{adminguide_link}[{adminguide_name}]. -A token can be obtained by enabling authenticating to your application with {{book.project.name}}; see the -{{book.adapterguide.link}}[{{book.adapterguide.name}}]. You can also use direct access grant to obtain an access token. +A token can be obtained by enabling authenticating to your application with {project_name}; see the +{adapterguide_link}[{adapterguide_name}]. You can also use direct access grant to obtain an access token. -For complete documentation see {{book.apidocs.link}}[{{book.apidocs.name}}]. +For complete documentation see {apidocs_link}[{apidocs_name}]. === Example using CURL @@ -37,7 +37,7 @@ curl \ "http://localhost:8080/auth/admin/realms/master" ---- -{% if book.community %} +ifeval::[{project_community}==true] === Example using Java There's a Java client library for the Admin REST API that makes it easy to use from Java. To use it from your application add a dependency on the @@ -60,5 +60,5 @@ Keycloak keycloak = Keycloak.getInstance( RealmRepresentation realm = keycloak.realm("master").toRepresentation(); ---- -Complete Javadoc for the admin client is available at {{book.apidocs.link}}[{{book.apidocs.name}}]. -{% endif %} \ No newline at end of file +Complete Javadoc for the admin client is available at {apidocs_link}[{apidocs_name}]. +endif::[] \ No newline at end of file diff --git a/server_development/topics/auth-spi.adoc b/server_development/topics/auth-spi.adoc old mode 100755 new mode 100644 index e5f8596e8a9..0d2fbe777a5 --- a/server_development/topics/auth-spi.adoc +++ b/server_development/topics/auth-spi.adoc @@ -373,7 +373,7 @@ getReferenceCategory() is just a category the Authenticator belongs to. ==== Adding Authenticator Form -Keycloak comes with a Freemarker <>. +Keycloak comes with a Freemarker <<_themes,theme and template engine>>. The createForm() method you called within authenticate() of your Authenticator class, builds an HTML page from a file within your login theme: secret-question.ftl. This file should be placed in the login theme with all the other .ftl files you see for login. @@ -754,19 +754,19 @@ In other words, add your custom authenticator after the "Send Reset Email" authe === Modifying First Broker Login Flow First Broker Login flow is used during first login with some identity provider. -Term `First Login` means that there is not yet existing {{book.project.name}} account linked with the particular authenticated identity provider account. -For more details about this flow see the `Identity Brokering` chapter in link:{{book.adminguide.link}}[{{book.adminguide.name}}] . +Term `First Login` means that there is not yet existing {project_name} account linked with the particular authenticated identity provider account. +For more details about this flow see the `Identity Brokering` chapter in link:{adminguide_link}[{adminguide_name}] . [[_client_authentication]] === Authentication of clients -{{book.project.name}} actually supports pluggable authentication for http://openid.net/specs/openid-connect-core-1_0.html[OpenID Connect] client applications. -Authentication of client (application) is used under the hood by the {{book.project.name}} adapter during sending any backchannel requests -to the {{book.project.name}} server (like the request for exchange code to access token after successful authentication or request to refresh token). +{project_name} actually supports pluggable authentication for http://openid.net/specs/openid-connect-core-1_0.html[OpenID Connect] client applications. +Authentication of client (application) is used under the hood by the {project_name} adapter during sending any backchannel requests +to the {project_name} server (like the request for exchange code to access token after successful authentication or request to refresh token). But the client authentication can be also used directly by you during `Direct Access grants` (represented by OAuth2 `Resource Owner Password Credentials Flow`) or during `Service account` authentication (represented by OAuth2 `Client Credentials Flow`). -For more details about {{book.project.name}} adapter and OAuth2 flows see link:{{book.adapterguide.link}}[{{book.adapterguide.name}}]. +For more details about {project_name} adapter and OAuth2 flows see link:{adapterguide_link}[{adapterguide_name}]. ==== Default implementations diff --git a/server_development/topics/custom-attributes.adoc b/server_development/topics/custom-attributes.adoc old mode 100755 new mode 100644 index 1a2a74f5f02..68072cbf6b6 --- a/server_development/topics/custom-attributes.adoc +++ b/server_development/topics/custom-attributes.adoc @@ -1,7 +1,7 @@ == Custom User Attributes You can add custom user attributes to the registration page and account management console with a custom theme. This chapter describes how to add attributes -to a custom theme, but you should refer to the <> chapter on how to create a custom theme. +to a custom theme, but you should refer to the <<_themes,Themes>> chapter on how to create a custom theme. === Registration Page diff --git a/server_development/topics/events.adoc b/server_development/topics/events.adoc old mode 100755 new mode 100644 diff --git a/server_development/topics/extensions.adoc b/server_development/topics/extensions.adoc index 5292dd4eeca..5767b4d08f7 100644 --- a/server_development/topics/extensions.adoc +++ b/server_development/topics/extensions.adoc @@ -2,18 +2,18 @@ == Extending the Server -The {{book.project.name}} SPI framework offers the possibility to implement or override particular built-in providers. However {{book.project.name}} +The {project_name} SPI framework offers the possibility to implement or override particular built-in providers. However {project_name} also provides capabilities to extend it's core functionalities and domain. This includes possibilities to: -* Add custom REST endpoints to the {{book.project.name}} server +* Add custom REST endpoints to the {project_name} server * Add your own custom SPI -* Add custom JPA entities to the {{book.project.name}} data model +* Add custom JPA entities to the {project_name} data model [[_extensions_rest]] === Add custom REST endpoints -This is a very powerful extension, which allows you to deploy your own REST endpoints to the {{book.project.name}} server. It enables all kinds of extensions, for example -the possibility to trigger functionality on the {{book.project.name}} server, which is not available through the default set of built-in {{book.project.name}} REST endpoints. +This is a very powerful extension, which allows you to deploy your own REST endpoints to the {project_name} server. It enables all kinds of extensions, for example +the possibility to trigger functionality on the {project_name} server, which is not available through the default set of built-in {project_name} REST endpoints. To add a custom REST endpoint, you need to implement the `RealmResourceProviderFactory` and `RealmResourceProvider` interfaces. `RealmResourceProvider` has one important method: @@ -86,11 +86,11 @@ Finally you need to implement your providers in the same manner as described in For more details, take a look at the example distribution at `providers/domain-extension`, which shows an Example SPI similar to the one above. [[_extensions_jpa]] -=== Add custom JPA entities to the {{book.project.name}} data model +=== Add custom JPA entities to the {project_name} data model -If the {{book.project.name}} data model does not exactly match your desired solution, or if you want to add some core functionality to {{book.project.name}}, -or when you have your own REST endpoint, you might want to extend the {{book.project.name}} data model. We enable you to add your -own JPA entities to the {{book.project.name}} JPA `EntityManager` . +If the {project_name} data model does not exactly match your desired solution, or if you want to add some core functionality to {project_name}, +or when you have your own REST endpoint, you might want to extend the {project_name} data model. We enable you to add your +own JPA entities to the {project_name} JPA `EntityManager` . To add your own JPA entities, you need to implement `JpaEntityProviderFactory` and `JpaEntityProvider`. The `JpaEntityProvider` allows you to return a list of your custom JPA entities and provide the location and id of the liquibase changelog. An example implementation can look like this: @@ -133,10 +133,10 @@ Company myCompany = em.find(Company.class, "123"); ---- The methods `getChangelogLocation` and `getFactoryId` are important to support automatic updating of your entities by Liquibase. http://www.liquibase.org/[Liquibase] -is a framework for updating the database schema, which {{book.project.name}} internally uses to create the DB schema and update the DB schema among versions. You may need to use +is a framework for updating the database schema, which {project_name} internally uses to create the DB schema and update the DB schema among versions. You may need to use it as well and create a changelog for your entities. Note that versioning of your own liquibase changelog is independent -of {{book.project.name}} versions. In other words, when you update to a new {{book.project.name}} version, you are not forced to update your -schema at the same time. And vice versa, you can update your schema even without updating the {{book.project.name}} version. The Liquibase update +of {project_name} versions. In other words, when you update to a new {project_name} version, you are not forced to update your +schema at the same time. And vice versa, you can update your schema even without updating the {project_name} version. The Liquibase update is always done at the server startup, so to trigger a DB update of your schema, you just need to add the new changeset to your liquibase changelog file (in the example above it's the file `META-INF/example-changelog.xml` (which must be packed in same JAR as the JPA entities and `ExampleJpaEntityProvider`) and then restart server. The DB schema will be automatically updated at startup. diff --git a/server_development/topics/identity-brokering.adoc b/server_development/topics/identity-brokering.adoc index 85cabfd6113..1779682289a 100644 --- a/server_development/topics/identity-brokering.adoc +++ b/server_development/topics/identity-brokering.adoc @@ -1,8 +1,8 @@ == Identity Brokering APIs -{{book.project.name}} can delegate authentication to a parent IDP for login. A typical example of this is the case -where you want users to be able to login through a social provider like Facebook or Google. {{book.project.name}} +{project_name} can delegate authentication to a parent IDP for login. A typical example of this is the case +where you want users to be able to login through a social provider like Facebook or Google. {project_name} also allows you to link existing accounts to a brokered IDP. This section talks about some APIs that your applications can use as it pertains to identity brokering. diff --git a/server_development/topics/identity-brokering/account-linking.adoc b/server_development/topics/identity-brokering/account-linking.adoc index c4d6f1ab2fe..cd0de883fe4 100644 --- a/server_development/topics/identity-brokering/account-linking.adoc +++ b/server_development/topics/identity-brokering/account-linking.adoc @@ -2,10 +2,10 @@ === Client Initiated Account Linking Some applications want to integrate with social providers like Facebook, but do not want to provide an option to login via -these social providers. {{book.project.name}} offers a browser-based API that applications can use to link an existing +these social providers. {project_name} offers a browser-based API that applications can use to link an existing user account to a specific external IDP. This is called client initiated account linking. -The way it works is that the application forward's the user's browser to a URL on the {{book.project.name}} server requesting +The way it works is that the application forward's the user's browser to a URL on the {project_name} server requesting that it wants to link the user's account to a specific external provider (i.e. Facebook). The server initiates a login with the external provider. The browser logs in at the external provider and is redirected back to the auth server. The auth server establishes the link and redirects back to the application with a confirmation. diff --git a/server_development/topics/identity-brokering/tokens.adoc b/server_development/topics/identity-brokering/tokens.adoc index 057ec9471fb..43bb4de1a0f 100644 --- a/server_development/topics/identity-brokering/tokens.adoc +++ b/server_development/topics/identity-brokering/tokens.adoc @@ -1,7 +1,7 @@ === Retrieving External IDP Tokens -{{book.project.name}} allows you to store tokens and responses from the authentication process with the external IDP. +{project_name} allows you to store tokens and responses from the authentication process with the external IDP. For that, you can use the `Store Token` configuration option on the IDP's settings page. Application code can retrieve these tokens and responses to pull in extra user information, or to securely invoke requests on the external IDP. @@ -15,10 +15,10 @@ Host: localhost:8080 Authorization: Bearer {keycloak_access_token} ---- -An application must have authenticated with {{book.project.name}} and have received an access token. This access token +An application must have authenticated with {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 a protected service in {{book.project.name}}, you need to send the access token issued by {{book.project.name}} during the user authentication. +In this case, given that you are accessing a protected service in {project_name}, you need to send the access token issued by {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. These external tokens can be re-established by either logging in again through the provider, or using the client initiated account linking API. diff --git a/server_development/topics/providers.adoc b/server_development/topics/providers.adoc index 2b4997ebc98..ab6467017c8 100644 --- a/server_development/topics/providers.adoc +++ b/server_development/topics/providers.adoc @@ -88,7 +88,7 @@ org.acme.provider.MyEventListenerProviderFactory ---- You can configure your provider through `standalone.xml`, `standalone-ha.xml`, or `domain.xml`. -See the link:{{book.installguide.link}}[{{book.installguide.name}}] for more details on +See the link:{installguide_link}[{installguide_name}] for more details on where the `standalone.xml`, `standalone-ha.xml`, or `domain.xml` file lives. For example by adding the following to `standalone.xml`: @@ -342,7 +342,7 @@ public class EjbExampleUserStorageProviderFactory === Available SPIs Here's a list of the most important available SPIs and a brief description. For more details on each SPI refer to individual sections. -If you want to see list of all available SPIs at runtime, you can check `Server Info` page in admin console as described in <> section. +If you want to see list of all available SPIs at runtime, you can check `Server Info` page in admin console as described in <<_providers_admin_console,Admin Console>> section. |=== diff --git a/server_development/topics/themes.adoc b/server_development/topics/themes.adoc index 31a4a51456a..229c1b8f124 100644 --- a/server_development/topics/themes.adoc +++ b/server_development/topics/themes.adoc @@ -1,14 +1,14 @@ [[_themes]] == Themes -{{book.project.name}} provides theme support for web pages and emails. This allows customizing the look and feel of end-user facing pages so they can be +{project_name} provides theme support for web pages and emails. This allows customizing the look and feel of end-user facing pages so they can be integrated with your applications. -image::../images/login-sunrise.png[caption="",title="Login page with sunrise example theme"] +image::images/login-sunrise.png[caption="",title="Login page with sunrise example theme"] === Theme Types -A theme can provide one or more types to customize different aspects of {{book.project.name}}. The types available are: +A theme can provide one or more types to customize different aspects of {project_name}. The types available are: * Account - Account management * Admin - Admin console @@ -25,7 +25,7 @@ NOTE: To set the theme for the `master` admin console you need to set the admin refresh the page. To change the welcome theme you need to edit `standalone.xml`, `standalone-ha.xml`, or `domain.xml`. -For more information on where the `standalone.xml`, `standalone-ha.xml`, or `domain.xml` file resides see the link:{{book.installguide.link}}[{{book.installguide.name}}]. +For more information on where the `standalone.xml`, `standalone-ha.xml`, or `domain.xml` file resides see the link:{installguide_link}[{installguide_name}]. Add `welcomeTheme` to the theme element, for example: @@ -42,7 +42,7 @@ If the server is running you need to restart the server for the changes to the w === Default Themes -{{book.project.name}} comes bundled with default themes in the server's root `themes` directory. To simplify upgrading you should not edit the bundled themes +{project_name} comes bundled with default themes in the server's root `themes` directory. To simplify upgrading you should not edit the bundled themes directly. Instead create your own theme that extends one of the bundle themes. === Creating a Theme @@ -56,15 +56,15 @@ A theme consists of: * Scripts * Theme properties -Unless you plan to replace every single page you should extend another theme. Most likely you will want to extend the {{book.project.name}} theme, but you could also +Unless you plan to replace every single page you should extend another theme. Most likely you will want to extend the {project_name} theme, but you could also consider extending the base theme if you are significantly changing the look and feel of the pages. The base theme primarily consists of HTML templates and -message bundles, while the {{book.project.name}} theme primarily contains images and stylesheets. +message bundles, while the {project_name} theme primarily contains images and stylesheets. When extending a theme you can override individual resources (templates, stylesheets, etc.). If you decide to override HTML templates bear in mind that you may need to update your custom template when upgrading to a new release. While creating a theme it's a good idea to disable caching as this makes it possible to edit theme resources directly from the `themes` directory without -restarting {{book.project.name}}. To do this edit `standalone.xml`. For `theme` set `staticMaxAge` to `-1` and both +restarting {project_name}. To do this edit `standalone.xml`. For `theme` set `staticMaxAge` to `-1` and both `cacheTemplates` and `cacheThemes` to `false`: [source,xml] @@ -208,7 +208,7 @@ of the realm. ==== Internationalization -{{book.project.name}} supports internationalization. To enable internationalization for a realm see {{book.adminguide.link}}[{{book.adminguide.name}}]. This +{project_name} supports internationalization. To enable internationalization for a realm see {adminguide_link}[{adminguide_name}]. This section describes how you can add your own language. To add a new language create the file `/messages/messages_` in the directory of your theme. Then add it to the `locales` property in @@ -255,11 +255,11 @@ usernameOrEmail=.... ==== HTML Templates -{{book.project.name}} uses http://freemarker.org[Freemarker Templates] in order to generate HTML. You can override individual templates in your own theme by +{project_name} uses http://freemarker.org[Freemarker Templates] in order to generate HTML. You can override individual templates in your own theme by creating `/