threat

SUMMARY.adoc

@@ -89,7 +89,18 @@
  .. link:topics/events/admin.adoc[Admin Events]
  . link:topics/export-import.adoc[Export and Import]
  . link:topics/account.adoc[User Account Service]
- . link:topics/security-vulnerabilities.adoc[Security Vulnerabilities]
+ . link:topics/threat.adoc[Threat Model Mitigation]
+ .. link:topics/threat/brute-force.adoc[Password Guess, Brute Force Attacks]
+ .. link:topics/threat/clickjacking.adoc[Clickjacking]
+ .. link:topics/threat/ssl.adoc[SSL/HTTPS Requirement]
+ .. link:topics/threat/csrf.adoc[CSRF]
+ .. link:topics/threat/redirect.adoc[Unspecific Redirect URIs]
+ .. link:topics/threat/compromised-tokens.adoc[Compromised Access and Refresh tokens]
+ .. link:topics/threat/compromised-codes.adoc[Compromised Access Codes]
+ .. link:topics/threat/open-redirect.adoc[Open Redirectors]
+ .. link:topics/threat/password-db-compromised.adoc[Password database compromised]
+ .. link:topics/threat/scope.adoc[Limiting Scope]
+ .. link:topics/threat/sql.adoc[SQL Injection Attacks]
  . link:topics/MigrationFromOlderVersions.adoc[Migration from older versions]
  . link:topics/cors.adoc[CORS]
 

topics/authentication/password-policies.adoc

@@ -1,3 +1,4 @@
+[[_password-policies]]
 
 === Password Policies
 

topics/clients/client-oidc.adoc

@@ -85,7 +85,7 @@ Remember that you still have to click the `Save` button!
 Only wildcards, * ,are allowed at the end of of a URI, i.e. http://host.com/*
 
 You should take extra precautions when registering valid redirect URI patterns as if you make
-them too general you are vulnerable to attacks.  See <<fake/../../security-vulnerabilities.adoc#_unspecific-redirect-uris, Security Vulnerabilities>> chapter
+them too general you are vulnerable to attacks.  See <<fake/../../threat/redirect.adoc#_unspecific-redirect-uris, Security Vulnerabilities>> chapter
 for more information.
 
 *Base URL*

topics/events/login.adoc

@@ -101,7 +101,7 @@ You can exclude one or more events by editing the `keycloak-server.json` that co
 }
 ----
 
-See the link:{{book.installguide.link}}[book.installguide.name}}] for more details on where the `keycloak-server.json` file lives.
+See the link:{{book.installguide.link}}[{{book.installguide.name}}] for more details on where the `keycloak-server.json` file lives.
 
 
 

topics/realms/ssl.adoc

@@ -1,3 +1,4 @@
+[[_ssl-mode]]
 
 === SSL Mode
 

topics/security-vulnerabilities.adoc

@@ -1,138 +0,0 @@
-== Security Vulnerabilities
-
-This chapter discusses possible security vulnerabilities Keycloak could have, how Keycloak mitigates those vulnerabilities, and what steps you need to do to configure Keycloak to mitigate some 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.
-Many of those vulnerabilities are discussed here. 
-
-=== SSL/HTTPS Requirement
-
-If you do not use SSL/HTTPS for all communication between the Keycloak 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. 
-
-Keycloak has <<_ssl_modes,three modes for SSL/HTTPS>>.
-SSL can be hard to set up, so out of the box, Keycloak 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, Keycloak 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.
-Otherwise you are vulnerable to DNS man in the middle attacks. 
-
-=== CSRF Attacks
-
-Cross-site request forgery (CSRF) is a web-based attack whereby HTTP requests are transmitted from a user that the web site trusts or has authenticated (e.g., via HTTP redirects or HTML forms).  Any site that uses cookie based authentication is vulnerable for these types of attacks.
-These attacks are mitigated by matching a state cookie against a posted form or query parameter. 
-
-OAuth 2.0 login specification requires that a state cookie be used and matched against a transmitted state parameter.
-Keycloak fully implements this part of the specification so all logins are protected. 
-
-The Keycloak adminstration console is a pure Javascript/HTML5 application that makes REST calls to the backend Keycloak admin 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 CORS origins as well. 
-
-The only part of Keycloak that really falls into CSRF is the user account management pages.
-To mitigate this Keycloak 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. 
-
-=== Clickjacking
-
-With clickjacking, a malicious site loads the target site in a transparent iFrame overlaid on top of a set of dummy buttons that are carefully constructed to be placed directly under important buttons on the target site.
-When a user clicks a visible button, they are actually clicking a button (such as an "Authorize" button) on the hidden page.
-An attacker can steal a user's authentication credentials and access their resources. 
-
-By default, every response by Keycloak sets some specific browser headers that can prevent this from happening specifically 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 both of these headers.
-In the admin console you can specify the values these headers will have.
-By default, Keycloak only sets up a same-origin policy for iframes.
-
-[[_unspecific-redirect-uris]]
-=== Unspecific Redirect URIs
-
-For the <<fake/../sso-protocols/oidc.adoc#_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, its a good idea to make your
-registered redirect URIs as specific as feasible.
-
-=== Compromised Access Codes
-
-It would be very hard for an attacker to compromise Keycloak access codes.
-Keycloak generates a cryptographically strong random value for its access codes so it would be very hard to guess an access token.
-An access code can only be turned into an access token once so it can't be replayed.
-In the admin console you can specify how long an access token is valid for.
-This value should be really short.
-Like a seconds.
-Just long enough for the client to make the request to turn the code into an token. 
-
-=== Compromised access and refresh tokens
-
-There's a few things you can do to mitigate access tokens and refresh tokens from being stolen.
-Most importantly is to enforce SSL/HTTPS communication between Keycloak and its clients and applications.
-Short lifespans (minutes) for access tokens allows Keycloak to check the validity of a refresh token.
-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.
-You can also disable specific applications, clients, and users if you feel that any one of those entities is completely compromised. 
-
-=== Open redirectors
-
-An attacker could use the end-user authorization endpoint and the redirect URI parameter to abuse the authorization server as an open redirector.
-An open redirector is an endpoint using a parameter to automatically redirect a user agent to the location specified by the parameter value without any validation.
-An attacker could utilize a user's trust in an authorization server to launch a phishing attack. 
-
-Keycloak requires that all registered applications and clients register at least one redirection uri pattern.
-Any time a client asks Keycloak to perform a redirect (on login or logout for example), Keycloak 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. 
-
-== Password guess: brute force attacks
-
-A brute force attack happens when an attacker is trying to guess a user's password.
-Keycloak 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.
-The downside of this is that this makes Keycloak vulnerable to denial of service attacks.
-Eventually we will expand this functionality to take client IP address into account when deciding whether to block a user. 
-
-Another thing you can do to prevent password guessing is to point a tool like http://fail2ban.org[Fail2Ban] to the Keycloak server's log file.
-Keycloak logs every login failure and client IP address that had the failure. 
-
-In the admin console, per realm, you can set up a password policy to enforce that users pick hard to guess passwords.
-A password has to match all policies.
-The password policies that can be configured are hash iterations, length, digits, lowercase, uppercase, special characters, not username, regex patterns, password history and force expired password update.
-Force expired password update policy forces or requires password updates after specified span of time.
-Password history policy  restricts a user from resetting his password to N old expired passwords.
-Multiple regex patterns can be specified.
-If there's more than one regex added, password has to match all fully.
-Increasing number of Hash Iterations (n) does not worsen anything (and certainly not the cipher) and it greatly increases the  resistance to dictionary attacks.
-However the drawback to increasing n is that it has some cost (CPU usage, energy, delay) for  the legitimate parties.
-Increasing n also slightly increases the odds that a random password gives the same result as the right  password due to hash collisions, and is thus a false but accepted password; however that remains very unlikely, in the order of  n*[1/(2^256)] for practical values of n, and can be entirely ignored in practice.
-Keycloak also uses PBKDF2 internally to  cryptographically derive passwords to refine and improve the ratio of cost between attacker and legitimate parties.
-Good practice is to pay attention to the time complexity of hash_password and hash; then increase n as much as tolerable in  the situation(s) at hand and and revise parameters such as n every few years to account for time complexity trade off. 
-
-Finally, the best way to mitigate against brute force attacks is to require user to set up a one-time-password (OTP). 
-
-== Password database compromised
-
-Keycloak does not store passwords in raw text.
-It stores a hash of them.
-Because of performance reasons, Keycloak only hashes passwords once.
-While a human could probably never crack a hashed password, it is very possible that a computer could.
-The security community suggests around 20,000 (yes thousand!) hashing iterations to be done to each password.
-This number grows every year due to increasing computing power (It was 1000 12 years ago). The problem with this is that password hashing is a huge performance hit as each login would require the entered password to be hashed that many times and compared to the stored hash.
-So, its up to the admin to configure the password hash iterations.
-This can be done in the admin console password policy configuration.
-Again, the default value is 1 as we thought it might be more important for Keycloak to scale out of the box.
-There's a lot of other measures admins can do to protect their password databases. 
-
-== SQL Injection attacks
-
-At this point in time, there is no knowledge of any SQL injection vulnerabilities in Keycloak 
-
-== Limiting Scope
-
-Using the `Scope` menu in the admin console for clients, you can control exactly which role mappings will be included within the token sent back to the client application.
-This allows you to limit the scope of permissions given to the client which is great if the client isn't very trusted and is known to not being very careful with its tokens. 

topics/threat.adoc

@@ -0,0 +1,8 @@
+== Threat Model Mitigation
+
+This chapter discusses possible security vulnerabilities any authentication server could have and how {{book.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.
+Many of those vulnerabilities are discussed here. 
+

topics/threat/brute-force.adoc

@@ -0,0 +1,35 @@
+
+=== 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.
+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[]
+
+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
+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.
+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.
+
+A better option might be a tool like http://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
+firewalls after it detects an attack to block connections from specific IP addresses.
+
+==== Password Policies
+
+Another things 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 <<fake/../../authentication/password-policies.adoc#_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).
+

topics/threat/clickjacking.adoc

@@ -0,0 +1,19 @@
+
+=== Clickjacking
+
+With clickjacking, a malicious site loads the target site in a transparent iFrame overlaid on top of a set of dummy
+buttons that are carefully constructed to be placed directly under important buttons on the target site.
+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
+specifically 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
+with these headers.
+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[]
+
+By default, {{book.project.name}} only sets up a _same-origin_ policy for iframes.
+

topics/threat/compromised-codes.adoc

@@ -0,0 +1,9 @@
+
+=== Compromised Access Codes
+
+For the <<fake/../../sso-protocols/oidc.adoc#_oidc-auth-flows, OIDC Auth Code Flow>>, t would be very hard for an attacker to compromise {{book.project.name}} access codes.
+{{book.project.name}} generates a cryptographically strong random value for its access codes so it would be very hard to guess an access token.
+An access code can only be used once to obtain an access token.
+In the admin console you can specify how long an access token is valid for on the <<fake/../../sessions/timeouts.adoc#_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.
+

topics/threat/compromised-tokens.adoc

@@ -0,0 +1,18 @@
+
+=== Compromised Access and Refresh tokens
+
+There's 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.
+This might seem like a no-brainer, but since {{book.project.name}} does not have SSL enabled by default, many naive admins
+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 <<fake/../../sessions/timeouts.adoc#_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 referesh 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.
+You can also disable specific applications, clients, and users if you feel that any one of those entities is completely compromised.
+

topics/threat/csrf.adoc

@@ -0,0 +1,18 @@
+
+=== CSRF Attacks
+
+Cross-site request forgery (CSRF) is a web-based attack whereby HTTP requests are transmitted from a user that the
+web site trusts or has authenticated with(e.g., via HTTP redirects or HTML forms).  Any site that uses cookie based authentication is vulnerable for these types of attacks.
+These attacks are mitigated by matching a state cookie against a posted form or query parameter.
+
+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.
+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.
+This query or form parameter is checked against the state cookie to verify that the call was made by the user.

topics/threat/open-redirect.adoc

@@ -0,0 +1,12 @@
+
+=== Open redirectors
+
+An attacker could use the end-user authorization endpoint and the redirect URI parameter to abuse the authorization server as an open redirector.
+An open redirector is an endpoint using a parameter to automatically redirect a user agent to the location specified by the parameter value without any validation.
+An attacker could utilize a user's trust in an authorization server to launch a phishing attack.
+
+Keycloak requires that all registered applications and clients register at least one redirection uri pattern.
+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.
+

topics/threat/password-db-compromised.adoc

@@ -0,0 +1,9 @@
+
+=== Password database compromised
+
+{{book.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 hasing 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.
+It is up to you to decide how serious you want to be to protect your password database.
+

topics/threat/redirect.adoc

@@ -0,0 +1,9 @@
+
+[[_unspecific-redirect-uris]]
+=== Unspecific Redirect URIs
+
+For the <<fake/../sso-protocols/oidc.adoc#_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, its a good idea to make your
+registered redirect URIs as specific as feasible.
+

topics/threat/scope.adoc

@@ -0,0 +1,8 @@
+
+=== Limiting Scope
+
+By default, each new client applications has an unlimited scope.  This means that every access token that is created
+for that client will contain all the permissions the user has.  If the client gets compromised and the access token
+is leaked, then each system that the user has permission to access is now also compromised.  It is highly suggested
+that you limit the roles an access token is assigned by using the <<fake/../../roles/client-scope.adoc#_client-scope, Scope menu>> for each client.
+

topics/threat/sql.adoc

@@ -0,0 +1,5 @@
+
+=== SQL Injection Attacks
+
+At this point in time, there is no knowledge of any SQL injection vulnerabilities in {{book.project.name}}.
+

topics/threat/ssl.adoc

@@ -0,0 +1,19 @@
+
+=== 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.
+OAuth 2.0/OpenID Connect uses access tokens for security.
+Without SSL/HTTPS, attackers can sniff your network and obtain an access token.
+Once they have an access token they can do any operation that the token has been given permission for.
+
+Keycloak has <<fake/../../realms/ssl.adoc#_ssl_modes,three modes for SSL/HTTPS>>.
+SSL can be hard to set up, so out of the box, {{book.project.name}} allows non-HTTPS communication over private IP addresses like
+localhost, 192.168.x.x, and other private IP addresses.
+In production, you should make sure SSL is enabled and required across the board.
+
+On the adapter/client side, {{book.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.
+Otherwise you are vulnerable to DNS man in the middle attacks.
+