KEYCLOAK-15790 Security Threats rewrite (#57)

* KEYCLOAK-15790 Security Threats rewrite

* KEYCLOAK-15790 Post feedback changes

server_admin/topics/threat.adoc

@@ -1,8 +1,4 @@
-== Threat Model Mitigation
 
-This chapter discusses possible security vulnerabilities any authentication server could have and how {project_name}
+== Mitigating Security threats
-mitigates those vulnerabilities.
-A good list of potential vulnerabilities and what security implementations should do to mitigate them can be found in
-the https://datatracker.ietf.org/doc/html/rfc6819[OAuth 2.0 Threat Model] document and its most recent extension https://datatracker.ietf.org/doc/html/draft-ietf-oauth-security-topics-15[OAuth 2.0 Security Best Current Practice] put out by the IETF.
-Many of those vulnerabilities are discussed here. 
 
+Security vulnerabilities exist in any authentication server. See the Internet Engineering Task Force's (IETF) https://tools.ietf.org/html/rfc6819[OAuth 2.0 Threat Model] and the https://tools.ietf.org/html/draft-ietf-oauth-security-topics-15[OAuth 2.0 Security Best Current Practice] for more information.

server_admin/topics/threat/admin.adoc

@@ -1,26 +1,17 @@
 
 === Admin Endpoints and Console
 
-The {project_name} administrative REST API and the web console are exposed by default on the same port as non-admin
+{project_name} exposes the administrative REST API and the web console on the same port as non-administrative usage by default. Do not expose administrative endpoints externally if external access is not necessary. If you need to expose administrative endpoints externally, you can expose them directly in {project_name} or use a proxy.
-usage. If access to the admin console is not needed externally, we recommend not exposing the admin endpoints on the
-Internet.
 
-This can be achieved either directly in {project_name} or with a proxy such as Apache or nginx.
+To expose endpoints by using a proxy, consult the documentation for the proxy. You need to control access to requests to the `/auth/admin` endpoint.
 
-For the proxy option please follow the documentation for the proxy. You need to control access to any requests
+Two options are available in {project_name} to expose endpoints directly, IP restriction and separate ports.
-to `/auth/admin`.
 
-To achieve this directly in {project_name} there are a few options. This document covers two options, IP restriction
+When the Admin Console becomes inaccessible on the frontend URL of {project_name}, configure a fixed admin URL in the default hostname provider.
-and separate ports.
-
-Once the admin console is no longer accessible on the frontend URL of Keycloak, you need to configure a fixed admin
-URL in the default hostname provider.
 
 ==== IP Restriction
 
-It is possible to restrict access to `/auth/admin` to only specific IP addresses.
+You can restrict access to `/auth/admin` to only specific IP addresses. For example, restrict access to `/auth/admin` to IP addresses in the range `10.0.0.1` to `10.0.0.255`.
-
-The following example restricts access to `/auth/admin` to IP addresses in the range `10.0.0.1` to `10.0.0.255`.
 
 [source,xml,subs="attributes+"]
 ----
@@ -40,7 +31,7 @@ The following example restricts access to `/auth/admin` to IP addresses in the r
 </subsystem>
 ----
 
-Equivalent configuration using CLI commands:
+You can also restrict access to specific IP addresses by using these CLI commands.:
 
 [source,bash]
 ----
@@ -48,14 +39,14 @@ Equivalent configuration using CLI commands:
 /subsystem=undertow/server=default-server/host=default-host/filter-ref=ipAccess:add()
 ----
 
-NOTE: For IP restriction if you are using a proxy it is important to configure it correctly to make sure {project_name}
+[NOTE]
-receives the client IP address and not the proxy IP address
+====
+For IP restriction using a proxy, configure the proxy to ensure {project_name} receives the client IP address and not the proxy IP address.
+====
 
 ==== Port Restriction
 
-It is possible to expose `/auth/admin` to a different port that is not exposed on the Internet.
+You can expose `/auth/admin` to a different unexposed port. For example, expose `/auth/admin` on port `8444` and prevent access to the default port `8443`.
-
-The following example exposes `/auth/admin` on port `8444` while not permitting access with the default port `8443`.
 
 [source,xml,subs="attributes+"]
 ----
@@ -86,7 +77,7 @@ The following example exposes `/auth/admin` on port `8444` while not permitting
 </socket-binding-group>
 ----
 
-Equivalent configuration using CLI commands:
+You can expose `/auth/admin` on port `8444` and prevent access to the default port `8443` by using CLI commands:
 
 [source,bash]
 ----

server_admin/topics/threat/audience-limit.adoc

@@ -1,6 +1,4 @@
 
 === Limit Token Audience
 
-In environments where the level of trust among services is low, it is a good practice to limit the audiences on the token. The
+In environments with low levels of trust among services, limit the audiences on the token. See the https://tools.ietf.org/html/rfc6819#section-5.1.5.5[OAuth2 Threat Model] and the xref:con-audience_{context}[Audience Support] section for more information.
-motivation behind this is described in the https://datatracker.ietf.org/doc/html/rfc6819#section-5.1.5.5[OAuth2 Threat Model] document and
-more details are in the <<_audience, Audience Support section>>.

server_admin/topics/threat/brute-force.adoc

@@ -1,44 +1,51 @@
 
-=== Password guess: brute force attacks
+=== Brute Force Attacks
 
-A brute force attack happens when an attacker is trying to guess a user's password.
+A brute force attack attempts to guess a user's password by trying to log in multiple times. {project_name} has brute force detection capabilities and can temporarily disable a user account if the number of login failures exceeds a specified threshold.
-{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.
 
-NOTE: Brute Force Detection is disabled by default. Enabling this feature is highly recommended to protect against this type of attack.
+[NOTE]
+====
+{project_name} disables brute force detection by default. Enable this feature to protect against brute force attacks.
+====
 
+.Procedure
+
+To enable this protection:
+
+. Click the *Realm Settings* menu
+. Click the *Security Defenses* tab.
+. Click the *Brute Force Detection* tab.
++
 .Brute Force Detection
 image:{project_images}/brute-force.png[]
 
-There are 2 different configurations for brute force detection; permanent lockout and temporary lockout. Permanent lockout will disable a user's account after an attack is detected; the account will be disabled until an administrator renables it. Temporary lockout will disable a user's account for a time period after an attack is detected; the time period for which the account is disabled increases the longer the attack continues.
+{project_name} can deploy permanent lockout and temporary lockout actions when it detects an attack. Permanent lockout disables a user account until an administrator re-enables it. Temporary lockout disables a user account for a specific period of time. The time period that the account is disabled increases as the attack continues.
 
-NOTE: When user is temporarily locked and attempt to login, the default error message `Invalid username or password` is shown.
+[NOTE]
-This is the same error message as the message displayed when invalid username or invalid password is provided. This is by design as
+====
-we do not want to reveal to the attacker that user is temporarily disabled.
+When a user is temporarily locked and attempts to log in, {project_name} displays the default `Invalid username or password` error message. This message is the same error message as the message displayed for an invalid username or invalid password to ensure the attacker is unaware the account is disabled.
+====
 
 *Common Parameters*
-====
-Max Login Failures::
-  Maximum number of login failures permitted. Default value is 30.
-Quick Login Check Milli Seconds::
-  Minimum time required between login attempts. Default is 1000.
-Minimum Quick Login Wait::
-  Minimum amount of time the user will be temporarily disabled if logins attempts are quicker than _Quick Login Check Milli Seconds_. Default is 1 minute.
-====
 
-*Temporary Lockout Parameters*
+|===
-====
+|Name |Description |Default
-Wait Increment::
-  Amount of time added to the time a user is temporarily disabled after each time _Max Login Failures_ is reached. Default is 1 minute.
-Max Wait::
-  The maximum amount of time for which a user will be temporarily disabled. Default is 15 minutes.
-Failure Reset Time::
-  Time after which the failure count will be reset; timer runs from the last failed login. Default is 12 hours.
-====
 
-*Permanent Lockout Algorithm*
+|Max Login Failures
+|The maximum number of login failures.
+|30 failures.
+
+|Quick Login Check Milliseconds
+|The minimum time between login attempts.
+|1000 milliseconds.
+
+|Minimum Quick Login Wait
+|The minimum time the user is disabled when login attempts are quicker than _Quick Login Check Milliseconds_.
+|1 minute.
+
+|===
+
+*Permanent Lockout Flow*
 ====
 . On successful login
 .. Reset `count`
@@ -46,39 +53,50 @@ Failure Reset Time::
 .. Increment `count`
 .. If `count` greater than _Max Login Failures_
 ... Permanently disable user
-.. Else if time between this failure and the last failure is less than _Quick Login Check Milli Seconds_
+.. Else if the time between this failure and the last failure is less than _Quick Login Check Milliseconds_
 ... Temporarily disable user for _Minimum Quick Login Wait_
 
-When a user is disabled they can not login until an administrator enables the user; enabling an account resets `count`.
+When {project_name} disables a user, the user cannot log in until an administrator enables the user. Enabling an account resets the `count`.
 ====
 
+*Temporary Lockout Parameters*
+
+|===
+|Name |Description |Default
+
+|Wait Increment
+|The time added to the time a user is temporarily disabled when the user's login attempts exceed _Max Login Failures_.
+|1 minute.
+
+|Max Wait
+|The maximum time a user is temporarily disabled.
+|15 minutes.
+
+|Failure Reset Time
+|The time when the failure count resets. The timer runs from the last failed login.
+|12 hours.
+
+|===
+
 *Temporary Lockout Algorithm*
 ====
 . On successful login
 .. Reset `count`
 . On failed login
-.. If time between this failure and the last failure is greater than _Failure Reset Time_
+.. If the time between this failure and the last failure is greater than _Failure Reset Time_
 ... Reset `count`
 .. Increment `count`
-.. Calculate `wait` using _Wait Increment_ * (`count` / _Max Login Failures_). The division is an integer division so will always be rounded down to a whole number
+.. Calculate `wait` using _Wait Increment_ * (`count` / _Max Login Failures_). The division is an integer division rounded down to a whole number
-.. If `wait` equals 0 and time between this failure and the last failure is less than _Quick Login Check Milli Seconds_ then set `wait` to _Minimum Quick Login Wait_ instead
+.. If `wait` equals 0 and the time between this failure and the last failure is less than _Quick Login Check Milliseconds_, set `wait` to _Minimum Quick Login Wait_.
 ... Temporarily disable the user for the smaller of `wait` and _Max Wait_ seconds
 
-Login failures when a user is temporarily disabled do not increment `count`.
+'count` does not increment when a temporarily disabled account commits a login failure.
 ====
 
-The downside of {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. When implementing a denial of service attack, an attacker can attempt to log in by guessing passwords for any accounts it knows and eventually causing {project_name} to disable the accounts.
-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/wiki/index.php/Main_Page[Fail2Ban].  You can point this service at the {project_name} server's log file.
+Consider using intrusion prevention software (IPS). {project_name} logs every login failure and client IP address failure. You can point the IPS to the {project_name} server's log file, and the IPS can modify firewalls to block connections from these IP addresses.
-{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
+Ensure you have a complex password policy to force users to choose complex passwords. See the <<_password-policies, Password Policies>> chapter for more information. Prevent password guessing by setting up the {project_name} server to use one-time-passwords.
-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).
-

server_admin/topics/threat/clickjacking.adoc

@@ -1,18 +1,25 @@
 
 === Clickjacking
 
-With clickjacking, a malicious site loads the target site in a transparent iFrame overlaid on top of a set of dummy
+Clickjacking is a technique of tricking users into clicking on a user interface element different from what users perceive. A malicious site loads the target site in a transparent iFrame, overlaid on top of a set of dummy buttons placed directly under important buttons on the target site. When a user clicks a visible button, they are clicking a button on the hidden page. An attacker can steal a user's authentication credentials and access their resources by using this method.
-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.
 
+<<<<<<< HEAD
 By default, every response by {project_name} sets some specific browser headers that can prevent this from happening.
 Specifically, it sets https://datatracker.ietf.org/doc/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.
+=======
+By default, every response by {project_name} sets the https://tools.ietf.org/html/rfc7034[X-FRAME_OPTIONS] and http://www.w3.org/TR/CSP/[Content-Security-Policy] browser headers to prevent clickjacking. See the documentation for these headers for details on fine-grain browser access. 
+>>>>>>> 88fa9a3a... KEYCLOAK-15790 Security Threats rewrite (#57)
 
-image:{project_images}/security-headers.png[]
+.Procedure
+In the Admin Console, you can specify the values of the X-FRAME_OPTIONS and Content-Security-Policy headers. 
+
+. Click the *Realm Settings* menu item.
+. Click the *Security Defenses* tab.
++
+.Security Defenses
+image:{project_images}/security-headers.png[Security Defences]
 
 By default, {project_name} only sets up a _same-origin_ policy for iframes.
-

server_admin/topics/threat/compromised-codes.adoc

@@ -1,10 +1,8 @@
 
 === Compromised Authorization Code
 
-For the xref:con-oidc-auth-flows_{context}[OIDC Auth Code Flow], it would be very hard for an attacker to compromise {project_name} authorization codes.
+For the xref:con-oidc-auth-flows_{context}[OIDC Auth Code Flow], {project_name} generates a cryptographically strong random value for its authorization codes. An authorization code is used only once to obtain an access token.
-{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 <<_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.
 
-You can also mitigate against leaked autorization codes by applying PKCE to clients. See <<_proof-key-for-code-exchange, Proof Key for Code Exchange (PKCE)>> to learn how.
+On the <<_timeouts, timeouts page>> in the Admin Console, you can specify the length of time an authorization code is valid. Ensure that the length of time is less than 10 seconds, which is long enough for a client to request a token from the code.
+
+You can also defend against leaked authorization codes by applying <<_proof-key-for-code-exchange, Proof Key for Code Exchange (PKCE)>> to clients.

server_admin/topics/threat/compromised-tokens.adoc

@@ -1,15 +1,15 @@
 
 === 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 {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.
+{project_name} includes several actions to prevent malicious actors from stealing access tokens and refresh tokens. The crucial action is to enforce SSL/HTTPS communication between {project_name} and its clients and applications. {project_name} does not enable SSL by default.
 
-Another thing you can do to mitigate leaked access tokens is to shorten their lifespans.  You can specify this within the <<_timeouts, timeouts page>>.
+Another action to mitigate damage from leaked access tokens is to shorten the token's lifespans. You can specify token lifespans within the <<_timeouts, timeouts page>>. Short lifespans for access tokens force clients and applications to refresh their access tokens after a short time. If an admin detects a leak, the admin can log out all user sessions to invalidate these refresh tokens or set up a revocation policy. 
-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.
 
-You can also mitigate against leaked access tokens and refresh tokens by issuing these tokens as holder-of-key tokens. See <<_mtls-client-certificate-bound-tokens, OAuth 2.0 Mutual TLS Client Certificate Bound Access Token>> to learn how.
+Ensure refresh tokens always stay private to the client and are never transmitted.
 
-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.
+You can mitigate damage from leaked access tokens and refresh tokens by issuing these tokens as holder-of-key tokens. See <<_mtls-client-certificate-bound-tokens, OAuth 2.0 Mutual TLS Client Certificate Bound Access Token>> for more information.
-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.
+If an access token or refresh token is compromised, access the Admin Console and push a not-before revocation policy to all applications. Pushing a not-before policy ensures that any tokens issued before that time become invalid. 
+Pushing a new not-before policy ensures that applications must download new public keys from {project_name} and mitigate damage from a compromised realm signing key. See the <<realm_keys, keys chapter>> for more information.
 
+You can disable specific applications, clients, or users if they are compromised.

server_admin/topics/threat/csrf.adoc

@@ -1,18 +1,10 @@
 
 === CSRF Attacks
 
-Cross-site request forgery (CSRF) is a web-based attack whereby HTTP requests are transmitted from a user that the
+A Cross-site request forgery (CSRF) attack uses HTTP requests from users that websites have already authenticated. Any site using cookie-based authentication is vulnerable to CSRF attacks. You can mitigate these attacks by matching a state cookie against a posted form or query parameter.
-web site trusts or has authenticated with(e.g. via HTTP redirects or HTML forms).  Any site that uses cookie based authentication is vulnerable to these types of attacks.
-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.
+The OAuth 2.0 login specification requires that a state cookie matches against a transmitted state parameter. {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 {project_name} Admin Console is a pure JavaScript/HTML5 application that makes REST calls to the backend {project_name} admin REST API.
+The {project_name} Admin Console is a JavaScript/HTML5 application that makes REST calls to the backend {project_name} admin REST API. These calls all require bearer token authentication and consist of JavaScript Ajax calls, so CSRF is impossible. You can configure the admin REST API to validate the CORS origins.
-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 {project_name} that really falls into CSRF is the user account management pages.
+The user account management section in {project_name} can be vulnerable to CSRF. To prevent CSRF attacks, {project_name} sets a state cookie and embeds the value of this cookie in hidden form fields or query parameters within action links. {project_name} checks the query/form parameter against the state cookie to verify that the user makes the call.
-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.

server_admin/topics/threat/host.adoc

@@ -1,14 +1,8 @@
 
 === Host
 
-{project_name} uses the public hostname for a number of things. For example, in the token issuer fields and URLs sent in
+{project_name} uses the public hostname in several ways, such as within token issuer fields and URLs in password reset emails.
-password reset emails.
 
-By default, the hostname is based on the request headers and there is no check to make sure this hostname is valid.
+By default, the hostname derives from request headers. No validation exists to ensure a hostname is valid. If you are not using a load balancer, or proxy, with {project_name} to prevent invalid host headers, configure the acceptable hostnames.
 
-If you are not using a load balancer or proxy in front of {project_name} that prevents invalid host headers, you must
+The hostname's Service Provider Interface (SPI) provides a way to configure the hostname for requests. You can use this built-in provider to set a fixed URL for frontend requests while allowing backend requests based on the request URI. If the built-in provider does not have the required capability, you can develop a customized provider.
-explicitly configure what hostnames should be accepted.
-
-The Hostname SPI provides a way to configure the hostname for a request. The out of the box provider allows setting
-a fixed URL for frontend requests, while allowing backend requests to be based on the request URI. It is also possible
-to develop your own provider in the case the built-in provider does not provide the functionality needed.

server_admin/topics/threat/open-redirect.adoc

@@ -1,12 +1,6 @@
 
 === 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 validation. An attacker can use the end-user authorization endpoint and the redirect URI parameter to use the authorization server as an open redirector, using a user's trust in an authorization server to launch a phishing attack.
-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.
-
-{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.
 
+{project_name} requires that all registered applications and clients register at least one redirection URI pattern. When a client requests that {project_name} performs a redirect, {project_name} checks the redirect URI against the list of valid registered URI patterns. Clients and applications must register as specific a URI pattern as possible to mitigate open redirector attacks.

server_admin/topics/threat/password-db-compromised.adoc

@@ -1,9 +1,4 @@
 
 === Password database compromised
 
-{project_name} does not store passwords in raw text.
+{project_name} does not store passwords in raw text but as hashed text, using the PBKDF2 hashing algorithm. {project_name} performs 20,000 hashing iterations, the number of iterations recommended by the security community. This number of hashing iterations can adversely affect performance as PBKDF2 hashing uses a significant amount of CPU resources.
-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.
-It is up to you to decide how serious you want to be to protect your password database.
-

server_admin/topics/threat/redirect.adoc

@@ -2,7 +2,4 @@
 [id="unspecific-redirect-uris_{context}"]
 === Unspecific Redirect URIs
 
-For the xref:con-oidc-auth-flows_{context}[Authorization Code Flow], if you register redirect URIs that
+Make your registered redirect URIs as specific as feasible. Registering vague redirect URIs for xref:con-oidc-auth-flows_{context}[Authorization Code Flows] can allow malicious clients to impersonate another client with broader access. Impersonation can happen if two clients live under the same domain, for example.
-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.

server_admin/topics/threat/scope.adoc

@@ -1,10 +1,6 @@
 
 === Limiting Scope
 
-By default, each new client application has an unlimited `role scope mappings`.  This means that every access token that is created
+By default, new client applications have unlimited `role scope mappings`. Every access token for that client contains all permissions that the user has. If an attacker compromises the client and obtains the client's access tokens, each system that the user can access is compromised. 
-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 <<_role_scope_mappings, Scope menu>> for each client.
-Or alternatively, you can set role scope mappings at the Client Scope level and assign Client Scopes to your client by using the
-<<_client_scopes_linking, Client Scope menu>>.
 
+Limit the roles of an access token by using the <<_role_scope_mappings, Scope menu>> for each client. Alternatively, you can set role scope mappings at the Client Scope level and assign Client Scopes to your client by using the <<_client_scopes_linking, Client Scope menu>>.

server_admin/topics/threat/sql.adoc

@@ -1,5 +1,4 @@
 
 === SQL Injection Attacks
 
-At this point in time, there is no knowledge of any SQL injection vulnerabilities in {project_name}.
+Currently, {project_name} has no known SQL injection vulnerabilities.
-

server_admin/topics/threat/ssl.adoc

@@ -1,19 +1,8 @@
 
 === SSL/HTTPS Requirement
 
-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. Attackers can scan your network for access tokens and use them to perform malicious operations for which the token has permission. This attack is known as a man-in-the-middle attack. Use SSL/HTTPS for communication between the {project_name} auth server and the clients {project_name} secures to prevent 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.
 
-{project_name} has <<_ssl_modes,three modes for SSL/HTTPS>>.
+{project_name} has <<_ssl_modes,three modes for SSL/HTTPS>>. SSL is complex to set up, so {project_name} allows non-HTTPS communication over private IP addresses such as localhost, 192.168.x.x, and other private IP addresses. In production, ensure you enable SSL and SSL is compulsory for all operations.
-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, {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.
 
+On the adapter/client-side, you can disable the SSL trust manager. The trust manager ensures the client's identity that {project_name} communicates with is valid and ensures the DNS domain name against the server's certificate. In production, ensure that each of your client adapters uses a truststore to prevent DNS man-in-the-middle attacks.