KEYCLOAK-16234 initial commit (#41)

* Fix Users TOC

* KEYCLOAK-16234 initial commit

* Modularization

* messing

* removes duplicate module calls

* Post feedback changes

Co-authored-by: Andy Munro <amunro@redhat.com>

server_admin/topics/roles-groups.adoc

@@ -0,0 +1,18 @@
+
+== Assigning permissions and access using roles and groups
+
+Roles and groups have a similar purpose, which is to give users access and permissions to use applications. Groups are a collection of users to which you apply roles and attributes. Roles define specific applications permissions and access control. Groups are an optional capability.
+
+A role typically applies to one type of user. Typical roles in an organization include `Admin`, `user`, `manager`, and `employee`. An application can assign access and permissions to a role and then assign multiple users to that role so the users share the same access and permissions. For example, the Admin Console has roles that give permission to users to access parts of the Admin Console.
+
+There is a global namespace for roles and each client also has its own dedicated namespace where roles can be defined. 
+
+include::roles-groups/proc-creating-realm-roles.adoc[]
+include::roles-groups/con-client-roles.adoc[]
+include::roles-groups/proc-converting-composite-roles.adoc[]
+include::roles-groups/proc-assigning-role-mappings.adoc[]
+include::roles-groups/con-default-roles.adoc[]
+include::roles-groups/con-role-scope-mappings.adoc[]
+include::roles-groups/proc-managing-groups.adoc[]
+include::roles-groups/con-comparing-groups-roles.adoc[]
+include::roles-groups/proc-specifying-default-groups.adoc[]

server_admin/topics/sso-protocols.adoc

@@ -1,5 +1,12 @@
 
 == SSO Protocols
+[role="_abstract"]
+This section discusses authentication protocols, the {project_name} authentication server and how applications, secured by the {project_name} authentication server, interact with these protocols.
 
-The chapter gives a brief overview of the authentication protocols and how the {project_name} authentication server
+include::sso-protocols/con-oidc.adoc[]
-and the applications it secures interact with these protocols.
+include::sso-protocols/con-oidc-auth-flows.adoc[]
+include::sso-protocols/con-server-oidc-uri-endpoints.adoc[]
+include::sso-protocols/con-saml.adoc[]
+include::sso-protocols/con-saml-bindings.adoc[]
+include::sso-protocols/ref-saml-vs-oidc.adoc[]
+include::sso-protocols/con-sso-docker.adoc[]

server_admin/topics/sso-protocols/con-oidc-auth-flows.adoc

@@ -0,0 +1,73 @@
+[id="con-oidc-auth-flows_{context}"]
+
+==== OIDC Auth Flows
+[role="_abstract"]
+OIDC has several methods, or flows, that clients or applications can use to authenticate users and receive _identity_ and _access_ tokens.  The method depends on the type of application or client requesting access.
+
+[[_oidc-auth-flows-authorization]]
+
+===== Authorization Code Flow
+
+The Authorization Code Flow is a browser-based protocol and suits authenticating and authorizing browser-based applications. It uses browser redirects to obtain _identity_ and _access_ tokens.
+
+. A user connects to an application using a browser. The application detects the user is not logged into the application.
+. The application redirects the browser to {project_name} for authentication.
+. The application passes a callback URL as a query parameter in the browser redirect. {project_name} uses the parameter upon successful authentication.
+. {project_name} authenticates the user and creates a one-time, short lived, temporary code.
+. {project_name} redirects to the application using the callback URL and adds the temporary code as a query parameter in the callback URL.
+. The application extracts the temporary code and makes a background REST invocation to {project_name}
+to exchange the code for an _identity_ and _access_ and _refresh_ token.  To prevent replay attacks, the temporary code cannot be used more than once.
+
+[NOTE]
+====
+A system is vulnerable to a stolen token for the lifetime of that token. For security and scalability reasons, access_ tokens are generally set to expire quickly so subsequent token requests fail. If a token expires, an application can obtain a new access token using the additional _refresh_ token sent by the login protocol. 
+====
+
+[[_confidential-clients]]
+_Confidential_ clients provide client secrets when they exchange the temporary codes for tokens. _Public_ clients are not required to provide client secrets.
+_Public_ clients are secure when HTTPS is strictly enforced and redirect URIs registered for the client are strictly controlled.  HTML5/JavaScript clients have to be _public_ clients because there is no way to securely transmit the client secret to HTML5/JavaScript clients. For more details, see the xref:assembly-managing-clients_{context}[Managing Clients] chapter.
+
+{project_name} also supports the https://tools.ietf.org/html/rfc7636[Proof Key for Code Exchange] specification.
+
+[[_oidc-auth-flows-implicit]]
+
+===== Implicit Flow
+
+The Implicit Flow is a browser-based protocol. It is similar to the Authorization Code Flow but with fewer requests and no refresh tokens. 
+
+[NOTE]
+====
+The possibility exists of _access_ tokens leaking in the browser history when tokens are transmitted via redirect URIs (see below).
+
+Also, this flow does not provide clients with refresh tokens. Therefore, access tokens have to be long-lived or users  have to re-authenticate when they expire.  
+
+We do not advise using this flow. This flow is supported because it is in the OIDC and OAuth 2.0 specification.
+====
+
+The protocol works as follows:
+
+. A user connects to an application using a browser. The application detects the user is not logged into the application.
+. The application redirects the browser to {project_name} for authentication.
+. The application passes a callback URL as a query parameter in the browser redirect. {project_name} uses the query parameter upon successful authentication.
+. {project_name} authenticates the user and creates an _identity_ and _access_ token. {project_name}
+redirects to the application using the callback URL and additionally adds the _identity_ and _access_ tokens as a query parameter in the callback URL.
+. The application extracts the _identity_ and _access_ tokens from the callback URL.
+
+[[_oidc-auth-flows-direct]]
+
+===== Resource Owner Password Credentials Grant (Direct Access Grants)
+
+_Direct Access Grants_ are used by REST clients to obtain tokens on behalf of users.  It is a HTTP POST request that contains:
+
+* The credentials of the user. The credentials are sent within form parameters.
+* The id of the client.
+* The clients secret (if it is a confidential client).
+
+The HTTP response contains the _identity_, _access_, and _refresh_ tokens.
+
+[[_client_credentials_grant]]
+===== Client Credentials Grant
+
+The _Client Credentials Grant_ creates a token based on the metadata and permissions of a service account associated with the client instead of obtaining a token that works on behalf of an external user. _Client Credentials Grants_ are used by REST clients.
+
+See the <<_service_accounts,Service Accounts>> chapter for more information.

server_admin/topics/sso-protocols/con-oidc.adoc

@@ -0,0 +1,20 @@
+[id="con-oidc_{context}"]
+
+=== OpenID Connect
+[role="_abstract"]
+link:https://openid.net/connect/[OpenID Connect] (OIDC) is an authentication protocol that is an extension of link:https://tools.ietf.org/html/rfc6749[OAuth 2.0].
+
+OAuth 2.0 is a framework for building authorization protocols and is incomplete. OIDC, however, is a full authentication and authorization protocol that uses the link:https://jwt.io[Json Web Token] (JWT) standards.  The JWT standards define an identity token JSON format and methods to digitally sign and encrypt data in a compact and web-friendly way.
+
+In general, OIDC implements two use cases. The first case is an application requesting that a  {project_name} server authenticates a user. Upon successful login, the application receives an _identity token_ and an _access token_. 
+The _identity token_ contains user information including user name, email, and profile information. The realm digitally signs the _access token_ which contains access information (such as user role mappings) that applications use to determine the resources users can access in the application.
+
+The second use case is a client accessing remote services. 
+
+* The client requests an _access token_ from {project_name} to invoke on remote services on behalf of the user. 
+* {project_name} authenticates the user and asks the user for consent to grant access to the requesting client.
+* The client receives the _access token_ which is digitally signed by the realm.  
+* The client makes REST requests on remote services using the _access token_. 
+* The remote REST service extracts the _access token_.
+* The remote REST service verifies the tokens signature.
+* The remote REST service decides, based on access information within the token, to process or reject the request.

server_admin/topics/sso-protocols/con-saml-bindings.adoc

@@ -0,0 +1,45 @@
+[id="con-saml-bindings_{context}"]
+
+==== SAML Bindings
+[role="_abstract"]
+{project_name} supports three binding types.
+
+===== Redirect Binding
+
+_Redirect_ binding uses a series of browser redirect URIs to exchange information.
+
+. A user connects to an application using a browser. The application detects the user is not authenticated. 
+. The application generates an XML authentication request document and encodes it as a query parameter in a URI. The URI is used to redirect to the {project_name} server. Depending on your settings, the application can also digitally sign the XML document and include the signature as a query parameter in the redirect URI to {project_name}.  This signature is used to validate the client that sends the request.
+. The browser redirects to {project_name}.  
+. The server extracts the XML auth request document and verifies the digital signature, if required.
+. The user enters their authentication credentials.
+. After authentication, the server generates an XML authentication response document. The document contains a SAML assertion that holds metadata about the user, including name, address, email, and any role mappings the user has.  The document is usually digitally signed using XML signatures, and may also be encrypted.
+. The XML authentication response document is encoded as a query parameter in a redirect URI. The URI brings the browser back to the application.  The digital signature is also included as a query parameter.
+. The application receives the redirect URI and extracts the XML document.
+. The application verifies the realm's signature to ensure it is receiving a valid authentication response.  The information inside the SAML assertion is used to make access decisions or display user data.
+
+===== POST Binding
+
+_POST_ binding is similar to _Redirect_ binding but _POST_ binding exchanges XML documents using POST requests instead of using GET requests. _POST_ Binding uses JavaScript to make the browser send a POST request to the {project_name} server or application when exchanging documents. HTTP responds with an HTML document which contains an HTML form containing embedded JavaScript.  When the page loads, the JavaScript automatically invokes the form.
+
+_POST_ binding is recommended due to two restrictions:
+
+*Security*
+
+With _Redirect_ binding, the SAML response is part of the URL. It is less secure as it is possible to capture the response in logs.
+
+*Size*
+
+Sending the document in the HTTP payload provides more scope for large amounts of data than in a limited URL.
+
+===== ECP
+
+Enhanced Client or Proxy (ECP) is a SAML v.2.0 profile which allows the exchange of SAML attributes outside the context of a web browser. It is often used by REST or SOAP-based clients.
+
+====  {project_name} Server SAML URI Endpoints
+
+{project_name} has one endpoint for all SAML requests.
+
+`http(s)://authserver.host/auth/realms/{realm-name}/protocol/saml`
+
+All bindings use this endpoint.

server_admin/topics/sso-protocols/con-saml.adoc

@@ -0,0 +1,13 @@
+[id="con-saml_{context}"]
+
+[[_saml]]
+
+=== SAML
+[role="_abstract"]
+link:http://saml.xml.org/saml-specifications[SAML 2.0] is a similar specification to OIDC but more mature.  It is descended from SOAP and web service messaging specifications so is generally more verbose than OIDC.  SAML 2.0 is an authentication protocol that exchanges XML documents between authentication servers and applications.  XML signatures and encryption are used to verify requests and responses.
+
+In general, SAML implements two use cases. 
+
+The first use case is an application that requests the {project_name} server authenticates a user.  Upon successful login, the application will receive an XML document. This document contains an SAML assertion that specifies user attributes. The realm digitally signs the the document which contains access information (such as user role mappings) that applications use to determine the resources users are allowed to access in the application.
+
+The second use case is a client accessing remote services.  The client requests a SAML assertion from {project_name} to invoke on remote services on behalf of the user.

server_admin/topics/sso-protocols/con-server-oidc-uri-endpoints.adoc

@@ -0,0 +1,25 @@
+[id="con-server-oidc-uri-endpoints_{context}"]
+
+====  {project_name} Server OIDC URI Endpoints
+[role="_abstract"]
+The following is a list of OIDC endpoints that {project_name} publishes. These endpoints can be used when a non-{project_name} client adapter uses OIDC to communicate with the authentication server. They are all relative URLs. The root of the URL consists of the HTTP(S) protocol, hostname, and the path, which is usually prefixed with _/auth_:  For example 
+
+[source, subs="attributes"]
+----
+https://localhost:8080/auth
+----
+
+/realms/{realm-name}/protocol/openid-connect/auth::
+  Used for obtaining a temporary code in the Authorization Code Flow or obtaining tokens using the Implicit Flow, Direct Grants, or Client Grants.
+
+/realms/{realm-name}/protocol/openid-connect/token::
+  Used by the Authorization Code Flow to convert a temporary code into a token.
+
+/realms/{realm-name}/protocol/openid-connect/logout::
+  Used for performing logouts.
+
+/realms/{realm-name}/protocol/openid-connect/userinfo::
+  Used for the User Info service described in the OIDC specification.
+
+/realms/{realm-name}/protocol/openid-connect/revoke::
+  Used for OAuth 2.0 Token Revocation described in https://tools.ietf.org/html/rfc7009[RFC7009].

server_admin/topics/sso-protocols/con-sso-docker.adoc

@@ -0,0 +1,30 @@
+[id="con-sso-docker_{context}"]
+
+[[_docker]]
+
+=== Docker Registry v2 Authentication
+
+[NOTE]
+====
+Docker authentication is disabled by default. To enable docker authentication, see link:{installguide_profile_link}[{installguide_profile_name}].
+====
+[role="_abstract"]
+link:https://docs.docker.com/registry/spec/auth/[Docker Registry V2 Authentication] is a protocol, similar to OIDC, that authenticates users against Docker registries.  {project_name}'s implementation of this protocol lets Docker clients use a {project_name} authentication server authenticate against a registry. This protocol uses standard token and signature mechanisms but it does deviate from a true OIDC implementation. It deviates by using a very specific JSON format for requests and responses as well as mapping repository names and permissions to the OAuth scope mechanism.
+
+==== Docker Authentication Flow
+The authentication flow is described in the link:https://docs.docker.com/registry/spec/auth/token/[Docker API documentation]. The following is a summary from the perspective of the {project_name} authentication server:
+
+* Perform a `docker login`.
+* The Docker client requests a resource from the Docker registry.  If the resource is protected and no authentication token is in the request, the Docker registry server responds with a 401 HTTP message with some information on the permissions that are required and the location of the authorization server.
+* The Docker client constructs an authentication request based on the 401 HTTP message from the Docker registry. The client uses the locally cached credentials (from the `docker login` command) as part of the link:https://tools.ietf.org/html/rfc2617[HTTP Basic Authentication] request to the {project_name} authentication server.
+* The {project_name} authentication server attempts to authenticate the user and return a JSON body containing an OAuth-style Bearer token.
+* The Docker client receives a bearer token from the JSON response and uses it in the authorization header to request the protected resource.
+* The Docker registry receives the new request for the protected resource with the token from the {project_name} server. The registry validates the token and grants access to the requested resource (if appropriate).
+
+NOTE: {project_name} does not create a browser SSO session after successful authentication with the Docker protocol. The browser SSO session does not use the Docker protocol as it cannot refresh tokens or obtain the status of a token or session from the {project_name} server; therefore a browser SSO session is not necessary. For more details, see the <<_transient-session, transient session>> section.
+
+====  {project_name} Docker Registry v2 Authentication Server URI Endpoints
+
+{project_name} has one endpoint for all Docker auth v2 requests.
+
+`http(s)://authserver.host/auth/realms/{realm-name}/protocol/docker-v2`

server_admin/topics/sso-protocols/ref-saml-vs-oidc.adoc

@@ -0,0 +1,21 @@
+[id="ref-saml-vs-oidc_{context}"]
+
+=== OpenID Connect vs. SAML
+[role="_abstract"]
+The following lists a number of factors to consider when choosing a protocol.
+
+For most purposes, {project_name} recommends using OIDC.
+
+*OIDC*
+
+* OIDC is specifically designed to work with the web.  
+* OIDC is suited for HTML5/JavaScript applications because it is easier to implement on the client side than SAML.
+* OIDC tokens are in the JSON format which makes them easier for Javascript to consume. 
+* OIDC has features to make security implementation easier. For example, see the link:https://openid.net/specs/openid-connect-session-1_0.html#ChangeNotification[iframe trick] that the specification uses to determine a users login status.
+
+*SAML*
+
+* SAML is designed as a layer to work on top of the web.
+* SAML can be more verbose than OIDC.
+* Users pick SAML over OIDC because there is a perception that it is mature.
+* Users pick SAML over OIDC existing applications that are secured with it.

server_admin/topics/sso-protocols/saml-vs-oidc.adoc

@@ -1,15 +0,0 @@
-
-=== OpenID Connect compared to SAML
-
-Choosing between OpenID Connect and SAML is not just a matter of using a newer protocol (OIDC) instead of the older more mature protocol (SAML).
-
-For most purposes, {project_name} recommends using OIDC.
-
-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 more suited for HTML5/JavaScript applications because it is
-easier to implement on the client side than SAML. As tokens are in the JSON format,
-they are easier to consume by JavaScript. You will also find several nice features that
-make implementing security in your web applications easier. For example, check out the link:https://openid.net/specs/openid-connect-session-1_0.html#ChangeNotification[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 with it.

server_admin/topics/threat/compromised-codes.adoc

@@ -1,11 +1,10 @@
 
 === Compromised Authorization Code
 
-For the <<_oidc-auth-flows, 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], it would be very hard for an attacker to compromise {project_name} authorization codes.
 {project_name} generates a cryptographically strong random value for its authorization codes so it would be very hard to guess an access token.
 An authorization code can only be used once to obtain an access token.
 In the admin console you can specify how long an authorization code is valid for on the <<_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.
-

server_admin/topics/threat/redirect.adoc

@@ -2,8 +2,7 @@
 [id="unspecific-redirect-uris_{context}"]
 === Unspecific Redirect URIs
 
-For the <<_oidc-auth-flows,Authorization Code Flow>>, if you register redirect URIs that
+For the xref:con-oidc-auth-flows_{context}[Authorization Code Flow], if you register redirect URIs that
 are too general, then it would be possible for a rogue client to impersonate a different client that has a broader scope
 of access.  This could happen for instance if two clients live under the same domain.  So, it's a good idea to make your
 registered redirect URIs as specific as feasible.
-

server_admin/topics/users.adoc

@@ -0,0 +1,16 @@
+
+== User Management
+
+This section describes the administration functions for managing users.
+
+include::users/proc-searching-user.adoc[leveloffset=2]
+include::users/proc-creating-user.adoc[leveloffset=2]
+include::users/proc-deleting-user.adoc[leveloffset=2]
+include::users/proc-configuring-user-attributes.adoc[leveloffset=2]
+include::users/credentials.adoc[leveloffset=2]
+include::users/con-required-actions.adoc[leveloffset=2]
+include::users/impersonation.adoc[leveloffset=2]
+include::users/user-registration.adoc[leveloffset=2]
+include::users/recaptcha.adoc[leveloffset=2]
+include::users/personal_data.adoc[leveloffset=2]
+

server_admin/topics/users/con-required-actions.adoc

@@ -22,4 +22,6 @@ Update Profile::
    The user must update profile information, such as name, address, email, and phone number.
 
 
-
+include::proc-setting-required-actions.adoc[leveloffset=3]
+include::proc-setting-default-required-actions.adoc[leveloffset=3]
+include::proc-enabling-terms-conditions.adoc[leveloffset=3]

server_admin/topics/users/credentials.adoc

@@ -0,0 +1,60 @@
+[[_user-credentials]]
+= User Credentials
+
+When viewing a user if you go to the `Credentials` tab you can manage a user's credentials.
+
+.Credential Management
+image:{project_images}/user-credentials.png[]
+
+The credentials are listed in a table, which has the following fields:
+
+Position::
+   The arrow buttons in this column allows you to shift the priority of the credential for the user, with the topmost credential having the highest priority.
+   This priority determines which credential will be shown first to a user in case of a choice during login. The highest priority of those available to the
+   user will be the one selected.
+Type::
+   This shows the type of the credential, for example `password` or `otp`.
+User Label::
+   This is an assignable label to recognise the credential when presented as a selection option during login. It can be set to any value to describe the
+   credential.
+Data::
+   This shows the non-confidential technical information about the credential. It is originally hidden, but you can press `Show data...` to reveal it for a
+   credential.
+Actions::
+   This column has two buttons. `Save` records the value of the User Label, while `Delete` will remove the credential.
+
+== Creating a Password for the User
+
+If a user doesn't have a password, or if the password has been deleted, the `Set Password` section will be shown on the page.
+
+.Credential Management - Set Password
+image:images/user-credentials-set-password.png[]
+
+To create a password for a user, type in a new one. Click on the `Set Password` button after you've typed everything in.
+If the `Temporary` switch is on, this new password can only be used once and the user will be asked to change their password after they have
+logged in.
+
+If a user already has a password, it can be reset in the `Reset Password` section.
+
+Alternatively, if you have <<_email, email>> set up, you can send an email to the user that asks
+them to reset their password.  Choose `Update Password` from the `Reset Actions` list box and click `Send Email`. You can optionally
+set the validity of the e-mail link which defaults to the one preset in `Tokens` tab in the realm settings.
+The sent email contains a link that will bring the user to the update password screen.
+
+Note that a user can only have a single credential of type password.
+
+== Creating other credentials
+
+You cannot configure other types of credentials for a specific user within the Admin Console. This is the responsibility of the user.
+You can only delete credentials for a user on the `Credentials` tab, for example if the user has lost an OTP device, or if a credential
+has been compromised.
+
+== Creating an OTP
+
+If OTP is conditional in your realm, the user will have to go to the User Account Management service to re-configure a new OTP generator. If OTP is required, then the user will be asked
+to re-configure a new OTP generator when they log in.
+
+Like passwords, you can alternatively send an email to the user that will ask them to reset their OTP generator.  Choose
+`Configure OTP` in the `Reset Actions` list box and click the `Send Email` button.  The sent email
+contains a link that will bring the user to the OTP setup screen. You can use this method even if the user already has an OTP credential,
+and would like to set up some more.

server_admin/topics/users/proc-enabling-terms-conditions.adoc

@@ -3,7 +3,7 @@
 // con-required-actions.adoc
 
 [id="proc-enabling-terms-conditions_{context}"]
-= Enabling terms and conditions
+= Enabling terms and conditions as a required action
 
 You can enable a required action that new users must accept the terms and conditions before logging in to {project_name} for the first time.    
 

server_admin/topics/users/proc-setting-default-required-actions.adoc

@@ -1,6 +1,5 @@
-// Module included in the following assemblies:
+[id="proc-setting-default-required-actions_{context}"]
-//
+= Setting default required actions
-// con-required-actions.adoc
 
 [id="proc-setting-default-required-actions_{context}"]
 = Setting required actions for all users
@@ -11,4 +10,4 @@ You can specify what actions are required before the first login of all new user
 
 . Click *Authentication* in the menu.
 . Click the *Required Actions* tab.
-. Click the checkbox in the *Default Action* column for one or more required actions. When a new user logs in for the first time, the selected actions must be executed.
+. Click the checkbox in the *Default Action* column for one or more required actions. When a new user logs in for the first time, the selected actions must be executed.

server_admin/topics/users/proc-setting-required-actions.adoc

@@ -1,6 +1,7 @@
-// Module included in the following assemblies:
+[id="proc-setting-required-actions_{context}"]
-//
+= Setting required actions
-// con-required-actions.adoc
+
+You can add and remove the required actions for existing users in the admin console. 
 
 [id="proc-setting-required-actions_{context}"]
 = Setting required actions for one user