diff --git a/gitlab-conversion.py b/gitlab-conversion.py index b961736d64..630665f150 100755 --- a/gitlab-conversion.py +++ b/gitlab-conversion.py @@ -23,6 +23,7 @@ def applyTransformation(input): exp = re.compile("[ ]*{% if (.*?) %}(.*?)[ ]*{% endif %}", re.DOTALL) input = re.sub(exp, "ifeval::[{\g<1>}==true]\g<2>endif::[]", input) input = re.sub(r"image:(\.\./)*", "image:", input) + input = re.sub(r"image::(\.\./)*", "image::", input) return input @@ -33,9 +34,13 @@ if len(sys.argv) > 1: if os.path.exists(targetdir): shutil.rmtree(targetdir) -shutil.copytree('images',os.path.join(targetdir, 'images')) -shutil.copytree('keycloak-images',os.path.join(targetdir, 'keycloak-images')) -shutil.copytree('rhsso-images',os.path.join(targetdir, 'rhsso-images')) + +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')) tmp = os.path.join(targetdir, 'topics') if not os.path.exists(tmp): diff --git a/topics/MigrationFromOlderVersions.adoc b/topics/MigrationFromOlderVersions.adoc index 956b7d8aa9..2105b9151c 100755 --- a/topics/MigrationFromOlderVersions.adoc +++ b/topics/MigrationFromOlderVersions.adoc @@ -68,10 +68,10 @@ We've moved the themes and providers directories from `standalone/configuration/ If you have added custom themes and providers you need to move them to the new location. You also need to update `keycloak-server.json` as it's changed due to this. -===== Adapter Subsystems only bring in dependencies if keycloak is on +===== Adapter Subsystems only bring in dependencies if Keycloak is on -Previously, if you had installed our saml or oidc keycloak subsystem adapters into Wildfly or JBoss EAP, we would automatically include Keycloak client jars into EVERY application irregardless if you were using Keycloak or not. -These libraries are now only added to your deployment if you have keycloak authentication turned on for that adapter (via the subsystem, or auth-method in web.xml +Previously, if you had installed our SAML or OIDC Keycloak subsystem adapters into Wildfly or JBoss EAP, we would automatically include Keycloak client jars into EVERY application irregardless if you were using Keycloak or not. +These libraries are now only added to your deployment if you have Keycloak authentication turned on for that adapter (via the subsystem, or auth-method in web.xml ===== Client Registration service endpoints moved @@ -95,11 +95,11 @@ Feedback in template.ftl has been moved and format has changed slightly. Most of our modules and source code have been consolidated into two maven modules: keycloak-server-spi and keycloak-services. SPI interfaces are in server-spi, implementations are in keycloak-services. All JPA dependent modules have been consolidated under keycloak-model-jpa. -Same goes with mongo and infinispan under modules keycloak-model-mongo and keycloak-model-infinispan. +Same goes with mongo and Infinispan under modules keycloak-model-mongo and keycloak-model-infinispan. ===== For adapters, session id changed after login -To plug a security attack vector, for platforms that support it (Tomcat 8, Undertow/Wildfly, Jetty 9), the keycloak oidc and saml adapters will change the session id after login. +To plug a security attack vector, for platforms that support it (Tomcat 8, Undertow/Wildfly, Jetty 9), the Keycloak OIDC and SAML adapters will change the session id after login. You can turn off this behavior check adapter config switches. ===== SAML SP Client Adapter Changes @@ -156,7 +156,7 @@ See documentation for more details if you want to catch and handle adapter error ===== IdentityProviderMapper changes There is no change in the interface itself or method signatures. -However there is some change in behaviour. +However there is some change in behavior. We added `First Broker Login` flow in this release and the method `IdentityProviderMapper.importNewUser` is now called after `First Broker Login` flow is finished. So if you want to have any attribute available in `Review Profile` page, you would need to use the method `preprocessFederatedIdentity` instead of `importNewUser` . You can set any attribute by invoke `BrokeredIdentityContext.setUserAttribute` and that will be available on `Review profile` page. @@ -242,7 +242,7 @@ Changes are really minor, but were needed to improve performance of federation. ===== WildFly 9.0.0.Final Following on from the distribution changes that was done in the last release the standalone download of Keycloak is now based on WildFly 9.0.0.Final. -This als affects the overlay which can only be deployed to WildFly 9.0.0.Final or JBoss EAP 6.4.0.GA. +This also affects the overlay which can only be deployed to WildFly 9.0.0.Final or JBoss EAP 6.4.0.GA. WildFly 8.2.0.Final is no longer supported for the server. ===== WildFly, JBoss EAP and JBoss AS7 adapters @@ -396,8 +396,8 @@ Facebook admin console). * DB Schema has changed. We have added export of the database to Beta 1, but not the ability to import the database from older versions. This will be supported in future releases. -* For all clients except bearer-only applications, you must specify at least one redirect uri. Keycloak - will not allow you to log in unless you have specified a valid redirect uri for that application. +* For all clients except bearer-only applications, you must specify at least one redirect URI. Keycloak + will not allow you to log in unless you have specified a valid redirect URI for that application. * Direct Grant API +`ON` diff --git a/topics/authentication/kerberos.adoc b/topics/authentication/kerberos.adoc index 2d7d5a2b4f..f538009e75 100755 --- a/topics/authentication/kerberos.adoc +++ b/topics/authentication/kerberos.adoc @@ -88,7 +88,7 @@ and enable `Kerberos`. .browser flow image:../../{{book.images}}/browser-flow.png[] -Switch the `Kerbros` requirement from _disabled_ to either _alternative_ or _required_. _Alternative_ basically means that Kerberos is optional. If +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 to _required_ then all users must have Kerberos enabled for their browser. @@ -153,7 +153,7 @@ To have this claim inserted into the token or assertion, each application will n This is enabled in the `Mappers` tab of the application's client page. See <> chapter for more details. -Applications will ned 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 {{book.project.name}} before it can use it to make GSS calls against other services. 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. You can also check the example sources directly https://github.com/keycloak/keycloak/blob/master/examples/kerberos[here] . diff --git a/topics/authentication/password-policies.adoc b/topics/authentication/password-policies.adoc index 36deaeda26..8d9c405991 100644 --- a/topics/authentication/password-policies.adoc +++ b/topics/authentication/password-policies.adoc @@ -35,7 +35,7 @@ HashAlgorithm:: 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. HashIterations:: - This value specifies the number of times a password will be hashed before it is stored or verified. The default value is 1. + 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 the database they can reverse engineer user passwords. The industry recommended value for this parameter changes every year as CPU power improves. The current recommended value diff --git a/topics/clients/client-oidc.adoc b/topics/clients/client-oidc.adoc index 3b33bc8b1a..537014b349 100644 --- a/topics/clients/client-oidc.adoc +++ b/topics/clients/client-oidc.adoc @@ -2,7 +2,7 @@ === OIDC Clients <> is the preferred protocol to secure applications. It was designed from the ground up to be web friendly -and works best with HTML5/Javascript applications. +and works best with HTML5/JavaScript applications. To create a OIDC client go to the `Clients` left menu item. On this page you'll see a `create` button on the right. @@ -61,7 +61,7 @@ _confidential_:: Confidential access type is for clients that need to perform a browser login and that you want to require a client secret when they turn an access code into an access token, (see http://tools.ietf.org/html/rfc6749#section-4.1.3[Access Token Request] in the OAuth 2.0 spec for more details). The advantages of this is that it is a little extra security. Since {{book.project.name}} requires you to register valid redirect-uris, we're not exactly sure what this little extra security is though. - :) The disadvantages of this access type is that confidential access type is pointless for pure Javascript clients as anybody could easily figure out your client's secret! + :) The disadvantages of this access type is that confidential access type is pointless for pure JavaScript clients as anybody could easily figure out your client's secret! _public_:: Public access type is for clients that need to perform a browser login and that you feel that the added extra security of confidential access type is not needed. @@ -114,10 +114,10 @@ See link:{{book.adapterguide.link}}[{{book.adapterguide.name}}] for more informa *Web Origins* This option centers around link:http://www.w3.org/TR/cors/[CORS] which stands for Cross-Origin Resource Sharing. -If executing browser Javascript tries to make an AJAX HTTP request to a server whose domain is different than the one the -Javascript code came from, then the request uses the CORS. +If executing browser JavaScript tries to make an AJAX HTTP request to a server whose domain is different than the one the +JavaScript code came from, then the request uses the 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. +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 `Web Origins` setting for the client are embedded within the access token sent to the client application. The client diff --git a/topics/identity-broker.adoc b/topics/identity-broker.adoc index 83ce9afe59..e60ae3f4b5 100755 --- a/topics/identity-broker.adoc +++ b/topics/identity-broker.adoc @@ -17,7 +17,7 @@ Usually, identity providers are based on the following protocols: * `SAML v2.0` * `OpenID Connect v1.0` -* `oAuth v2.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: diff --git a/topics/identity-broker/configuration.adoc b/topics/identity-broker/configuration.adoc index a6fcdd35f6..aa324d00b4 100644 --- a/topics/identity-broker/configuration.adoc +++ b/topics/identity-broker/configuration.adoc @@ -45,8 +45,8 @@ Regardless the identity provider you are creating, you'll see the following conf |Alias |The alias is an unique identifier for an identity provider. It is used to reference internally an identity provider. - Some protocols require a redirect uri or callback url in order to communicate with an identity provider. For instance, OpenID Connect. - In this case, the alias is used to build the redirect uri. + Some protocols require a redirect URI or callback url in order to communicate with an identity provider. For instance, OpenID Connect. + In this case, the alias is used to build the redirect URI. Every single identity provider must have an alias. For example, facebook, google, idp.acme.com, etc. |Enabled diff --git a/topics/identity-broker/overview.adoc b/topics/identity-broker/overview.adoc index b96be784a1..57c645e152 100644 --- a/topics/identity-broker/overview.adoc +++ b/topics/identity-broker/overview.adoc @@ -42,5 +42,5 @@ NOTE: Different protocols may require different authentication flows. As you may notice, at the end of the authentication process {{book.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 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}} ! diff --git a/topics/overview.adoc b/topics/overview.adoc index 17d56e1b2d..dbb11c47b3 100755 --- a/topics/overview.adoc +++ b/topics/overview.adoc @@ -4,8 +4,6 @@ is 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, adminstration, and account management. You can also use {{book.project.name}} as an +user interfaces for login, registration, administration, and account management. You can also use {{book.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+. {{book.project.name}} has tons of SPIs that you can use to customize every -aspect of the server. - +party identity providers like Facebook and Google+. diff --git a/topics/overview/features.adoc b/topics/overview/features.adoc index 028405b4d2..237addb647 100644 --- a/topics/overview/features.adoc +++ b/topics/overview/features.adoc @@ -1,37 +1,29 @@ === Features -* SSO and Single Log Out for browser applications -* Social Login. Enable Google, GitHub, Facebook, Twitter, and other social providers with no code required. -* LDAP and Active Directory support. -* Optional User Registration -* Password and TOTP support (via Google Authenticator). Client cert auth coming soon. -* Forgot password support. User can have an email sent to them -* Reset password/totp. Admin can force a password reset, or set up a temporary password. -* Not-before revocation policies per realm, application, or user. -* User session management. Admin can view user sessions and what applications/clients have an access token. Sessions can be invalidated - per realm or per user. -* Pluggable theme and style support for user facing screens. Login, grant pages, account mgmt, and admin console all - can be styled, branded, and tailored to your application and organizational needs. -* Integrated Browser App to REST Service token propagation -* OAuth Bearer token auth for REST Services -* OAuth 2.0 Grant requests -* OpenID Connect Support. -* SAML Support. -* CORS Support -* CORS Web Origin management and validation -* Completely centrally managed user and role mapping metadata. Minimal configuration at the application side -* Admin Console for managing users, roles, role mappings, clients, user sessions and allowed CORS web origins. -* Account Management console that allows users to manage their own account, view their open sessions, reset passwords, etc. -* Deployable as a WAR, appliance, or on Openshift. Completely clusterable. -* Multitenancy support. You can host and manage multiple realms for multiple organizations. In the same auth server - and even within the same deployed application. -* Identity brokering/chaining. You can make the {{book.project.name}} server a child IDP to another SAML 2.0 or OpenID Connect IDP. -* Token claim, assertion, and attribute mappings. You can map user attributes, roles, and role names however you want - into a OIDC ID Token, Access Token, SAML attribute statements, etc. This feature allows you to basically - tailor how you want auth responses to look. -* Can support any platform that has an Open ID Connect or SAML 2.0 client adapter. {{book.project.name}} does provide - client adapters for Pure HTML5/Javascript apps, JBoss AS7, JBoss EAP 6.x, JBoss EAP 7, Wildfly, Tomcat 7, - Tomcat 8, Jetty 9.1.x, Jetty 9.2.x, and Jetty 8.1.x. -* Tons of SPIs for customizing every aspect of the server. - +* Single-Sign On and Single-Sign Out for browser applications +* OpenID Connect support. +* OAuth 2.0 support. +* SAML support. +* Identity Brokering - Authenticate with external OpenID Connect or SAML Identity Providers. +* Social Login - Enable login with Google, GitHub, Facebook, Twitter, and other social networks. +* User Federation - Sync users from LDAP and Active Directory servers. +* Kerberos bridge - Automatically authenticate users that are logged-in to a Kerberos server. +* Admin Console for central management of users, roles, role mappings, clients and configuration. +* Account Management console that allows users to centrally manage their account. +* Theme support - Customize all user facing pages to integrate with your applications and branding. +* 2nd Factory Authentication - Support for TOTP/HOTP via Google Authenticator or FreeOTP +* Login flows - optional user self-registration, recover password, verify email, require password update, etc. +* Session management - Admins and users themselves can view and manage user sessions. +* 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 %} +* 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 %} +* Client adapters for JavaScript applications, JBoss EAP, Fuse, etc. +{% endif %} +* Supports any platform/language that has an OpenID Connect Resource Provider library or SAML 2.0 Service Provider library diff --git a/topics/realms/keys.adoc b/topics/realms/keys.adoc index 460c46f568..a8c88ea0f7 100644 --- a/topics/realms/keys.adoc +++ b/topics/realms/keys.adoc @@ -2,7 +2,7 @@ === Realm Key Pairs The authentication protocols that are used by {{book.project.name}} require cryptographic signatures and sometimes even -encryption. {{book.project.name}} uses a asymetric keypair, a private and public key to accomplish this. When a realm +encryption. {{book.project.name}} uses a asymmetric key pair, a private and public key to accomplish this. When a realm is created a key pair is automatically generated. It is recommended that you cycle this key pair occasionally. How often you do this is dependent on your organizational needs and security requirements as you have to make sure every application that needs the public or certificate of your realm get this updated. This can be a lot of work! diff --git a/topics/realms/ssl.adoc b/topics/realms/ssl.adoc index c3fcf97249..6e1c00eb0e 100644 --- a/topics/realms/ssl.adoc +++ b/topics/realms/ssl.adoc @@ -18,7 +18,7 @@ The `Require SSL` option allows you to pick the SSL Mode you want. Here is an e 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 adress you will get an error. + If you try to access {{book.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 diff --git a/topics/sso-protocols/oidc.adoc b/topics/sso-protocols/oidc.adoc index aface00786..75e0848f75 100644 --- a/topics/sso-protocols/oidc.adoc +++ b/topics/sso-protocols/oidc.adoc @@ -5,17 +5,17 @@ link:http://openid.net/connect/[Open ID Connect] (OIDC) is an authentication protocol that is an extension of link:https://tools.ietf.org/html/rfc6749[OAuth 2.0]. While OAuth 2.0 is only a framework for building authorization protocols and is mainly incomplete, OIDC is a full-fledged authentication and authorization protocol. OIDC also makes heavy use of the link:https://jwt.io[Json Web Token] (JWT) set of standards. These standards define a -identity token JSON format and ways to digitially sign and encrypt that data in a compact and web-friendly way. +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 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 digitially signed by +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 -then asks the user for consent to grant access to the client requesting it. The clien then receives the _access token_. This _access token_ +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 the request. @@ -31,7 +31,7 @@ OIDC and OAuth 2.0 specifications so only a brief overview will be provided here ===== Authorization Code Flow This is a browser-based protocol and what we recommend you use to authenticate and authorize browser-based applications. It makes -heavy use of browser redirects to obtain an _identiy_ and _access_ token. Here's a brief summary +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}} to be authenticated. The application passes along a callback URL (a redirect URL) as a query parameter in this browser redirect @@ -53,16 +53,16 @@ has revoked access. This makes things more secure and more scalable. Another important aspect of this flow is the concept of a _public_ vs. a _confidential_ client. _Confidential_ clients are required to provide a client secret when they exchange the temporary codes for tokens. _Public_ clients are not required to provide this client secret. _Public_ clients are perfectly fine so long as HTTPS is strictly enforced and you are very strict about what redirect URIs are registered for the -client. HTML5/Javascript clients actually always have to be _public_ clients because there is no way to transmit the client secret to them in a secure +client. HTML5/JavaScript clients actually always have to be _public_ clients because there is no way to transmit the client secret to them in a secure manner. Again, this is ok so long as you use HTTPS and strictly enforce redirect URI registration. This guide goes more detail -into this in the +into this in the // DOCS REMARK: Please update the cross-reference as it does not resolve correctly. <> chapter. ===== Implicit Flow This is a browser-based protocol that is similar to Authorization Code Flow except there are fewer requests and no refresh tokens involved. -We do not recommend this flow as there remains the possiblity of _access_ tokens being leaked in the browser history as tokens are transmitted +We do not recommend this flow as there remains the possibility of _access_ tokens being leaked in the browser history as tokens are transmitted via redirect URIs (see below). Also, since this flow doesn't provide the client with a refresh token, access tokens would either have to be long-lived or users would have to re-authenticate when they expired. This flow is supported because its in the OIDC and OAuth 2.0 specification. Here's a brief summary of the protocol: @@ -71,7 +71,7 @@ Here's a brief summary of the protocol: 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}} - redirects back to the appliciation using the callback URL provided earlier and additionally adding the _identity_ and + 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 the _identity_ and _access_ tokens from the callback URL. diff --git a/topics/sso-protocols/saml-vs-oidc.adoc b/topics/sso-protocols/saml-vs-oidc.adoc index 34ee8c648c..53e1681b7f 100644 --- a/topics/sso-protocols/saml-vs-oidc.adoc +++ b/topics/sso-protocols/saml-vs-oidc.adoc @@ -7,12 +7,12 @@ SAML tends to be a bit more verbose than OIDC. Beyond verbosity of exchanged data, if you compare the specifications you'll find that OIDC was designed to work with the web while SAML was retrofitted to work on top of the web. For example, -OIDC is also much better suited for HTML5/Javascript applications because it is +OIDC is also much better suited for HTML5/JavaScript applications because it is much much simpler to implement on the client side than SAML. Since tokens are in the JSON format, -they can be directly consumed by Javascript. Also, you'll find many nice little switches and features that +they can be directly consumed by JavaScript. Also, you'll find many nice little switches and features that make implementing security in your web applications easier. For example, check out the iframe trick that the specification uses to easily determine if a user is still logged in or not. SAML has its uses though. As you see the OIDC specifications evolve you see they implement more and more features that SAML has had for years. What we often see is that people pick SAML over OIDC because of the perception that it is more mature -and also because they already have existing applications that are secured by it. \ No newline at end of file +and also because they already have existing applications that are secured by it. diff --git a/topics/sso-protocols/saml.adoc b/topics/sso-protocols/saml.adoc index 685ba0a5ca..8a5b4aa009 100644 --- a/topics/sso-protocols/saml.adoc +++ b/topics/sso-protocols/saml.adoc @@ -11,7 +11,7 @@ In {{book.project.name}} SAML serves two types of use cases: browser application 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 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 digitially signed by +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. @@ -31,14 +31,14 @@ 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. - Depending on your settings, the application may also digitially sign this XML document and also stuffs this signature as a query + Depending on your settings, the application may also digitally sign this XML document and also stuffs this signature as a query param in the redirect URI to {{book.project.name}}. This is 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 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 also an role mappings the user - might have. This document is almost always digitially signed and using XML signatures, and may also be encrypted. + might have. This document is almost always digitally signed and using XML signatures, and may also be encrypted. . The XML auth response document is then encoded as a query param in a redirect URI that brings the browser back to the application. The digital signature is also included as a query param. . The application receives the redirect URI and extracts the XML document and verifies the realm's signature to make @@ -48,9 +48,9 @@ how it works. ===== POST Binding 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. Bascially 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. +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 +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. ===== ECP diff --git a/topics/threat/brute-force.adoc b/topics/threat/brute-force.adoc index 18f88a75e9..eda6750a77 100644 --- a/topics/threat/brute-force.adoc +++ b/topics/threat/brute-force.adoc @@ -13,12 +13,12 @@ image:../../{{book.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 `Failure Reset Time` is reached all failures are wiped clean. The `Max Wait` is the maximum amount of time -an account can be disabled for. Another preventitive measure is that if there is subsequent login failures for one +an account can be disabled for. Another preventive measure is that if there is subsequent login failures for one account that are too quick for a human to initiate the account will be disabled then. This is controlled by the `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 vulnerble to denial of service attacks. +The downside of {{book.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 as many accounts it knows and these account will be disabled. Eventually Eventually we will expand this functionality to take client IP address into account when deciding whether to block a user. diff --git a/topics/threat/compromised-tokens.adoc b/topics/threat/compromised-tokens.adoc index 51e23688c0..3df91849db 100644 --- a/topics/threat/compromised-tokens.adoc +++ b/topics/threat/compromised-tokens.adoc @@ -9,7 +9,7 @@ might not realize they have to do this. Another thing you can do to mitigate leaked access tokens is to shorten their lifespans. You can specify this within the <>. 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 referesh tokens or set up a revocation policy. +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. diff --git a/topics/threat/csrf.adoc b/topics/threat/csrf.adoc index 22adb1835b..99fd212039 100644 --- a/topics/threat/csrf.adoc +++ b/topics/threat/csrf.adoc @@ -8,8 +8,8 @@ These attacks are mitigated by matching a state cookie against a posted form or 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. -The {{book.project.name}} Adin Consnole is a pure Javascript/HTML5 application that makes REST calls to the backend {{book.project.name}} admin REST API. -These calls all require bearer token authentication and are made via Javascript Ajax calls. +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. +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. diff --git a/topics/threat/open-redirect.adoc b/topics/threat/open-redirect.adoc index b9925578f6..bff3a562fb 100644 --- a/topics/threat/open-redirect.adoc +++ b/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. -the list of valid registered uri patterns. +{{book.project.name}} requires that all registered applications and clients register at least one redirection URI pattern. +Any time a client asks {{book.project.name}} to perform a redirect (on login or logout for example), {{book.project.name}} will check the redirect URI vs. +the list of valid registered URI patterns. It is important that clients and applications register as specific a URI pattern as possible to mitigate open redirector attacks. diff --git a/topics/user-federation/ldap.adoc b/topics/user-federation/ldap.adoc index 9201162055..636f626780 100755 --- a/topics/user-federation/ldap.adoc +++ b/topics/user-federation/ldap.adoc @@ -70,11 +70,11 @@ if the connection to LDAP starts with `ldaps`. LDAP Federation Provider will automatically take care of synchronization (import) of needed LDAP users into the {{book.project.name}} local database. As users log in, the LDAP Federation provider will import the LDAP user into then {{book.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 Consoel and click the `View all users` button, you will only see those LDAP users that +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 and 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. -There are 2 types of sychronization: +There are 2 types of synchronization: Periodic Full sync:: This will synchronize all LDAP users into {{book.project.name}} DB. @@ -82,9 +82,9 @@ Periodic Full sync:: (For example if user `Mary Kelly` was changed in LDAP to `Mary Smith`). Periodic Changed users sync:: - When synching occurs, only those users that were created or updated after the last sync will be updated and/or imported. + When syncing occurs, only those users that were created or updated after the last sync will be updated and/or imported. -The best way to handle synching is to click the `Synchronize all users` button when you first create the LDAP provider, +The best way to handle syncing is to click the `Synchronize all users` button when you first create the LDAP provider, then set up a periodic sync of changed users. The configuration page for your LDAP Provider has a bunch of options to support you here. [[_ldap_mappers]] @@ -101,7 +101,7 @@ User Attribute Mapper:: For this mapper implementation, there is always one-to-one mapping (one LDAP attribute is mapped to one {{book.project.name}} attribute) FullName Mapper:: - This allows to specify that the fullname of user, which is saved in some LDAP attribute (usualy `cn` ) will be mapped to `firstName` and `lastname` attributes in the {{book.project.name}} database. + This allows to specify that the full name of user, which is saved in some LDAP attribute (usually `cn` ) will be mapped to `firstName` and `lastname` attributes in the {{book.project.name}} database. Having `cn` to contain full name of user is common case for some LDAP deployments. Role Mapper::