KEYCLOAK-16468 Read-only user attributes (#1081)

(cherry picked from commit 4e505128a5b8d7f916a330bc0fef883da04a441b)
(cherry picked from commit 511b127bb36baed787da7cf2d88549bd14e5d0a9)

Co-authored-by: Stian Thorgersen <stianst@gmail.com>

authorization_services/topics/policy-js-policy.adoc

@@ -1,6 +1,9 @@
 [[_policy_js]]
 = JavaScript-Based Policy
 
+WARNING: If your policy implementation is using Attribute based access control (ABAC) as in the examples below, then please make sure that
+users are not able to edit the protected attributes and the corresponding attributes are read-only. See the details in the link:{adminguide_link}#_read_only_user_attributes[Threat model mitigation chapter].
+
 You can use this type of policy to define conditions for your permissions using JavaScript. It is one of the rule-based policy types
 supported by {project_name}, and provides flexibility to write any policy based on the <<_policy_evaluation_api, Evaluation API>>.
 

server_admin/topics.adoc

@@ -110,6 +110,7 @@ include::topics/threat.adoc[]
 include::topics/threat/host.adoc[]
 include::topics/threat/admin.adoc[]
 include::topics/threat/brute-force.adoc[]
+include::topics/threat/read-only-attributes.adoc[]
 include::topics/threat/clickjacking.adoc[]
 include::topics/threat/ssl.adoc[]
 include::topics/threat/csrf.adoc[]

server_admin/topics/authentication/x509.adoc

@@ -186,6 +186,9 @@ Defines how to match the certificate identity to an existing user. _Username or
 `A name of user attribute` (optional)::
 A custom attribute which value will be matched against the certificate identity. Multiple custom attributes are relevant when attribute mapping is related to multiple values, e.g. 'Certificate Serial Number and IssuerDN'.
 
+WARNING: It is highly recommended that attribute used here is read-only for the users. By default, only the `usercertificate` attribute is read-only by {project_name}.
+If you use a different attribute name, you may need to add it to the list of read-only attributes. See the details in the link:#_read_only_user_attributes[Threat model mitigation chapter].
+
 `CRL Checking Enabled` (optional)::
 Defines whether to check the revocation status of the certificate using Certificate Revocation List.
 

server_admin/topics/threat/read-only-attributes.adoc

@@ -0,0 +1,60 @@
+[[_read_only_user_attributes]]
+=== Read-only User Attributes
+
+Typical users who are stored in {project_name} have various attributes related to their user profiles. Such attributes include email, firstName or lastname.
+However users may also have attributes, which are not typical profile data, but rather metadata. The metadata attributes usually should be read-only for the users
+and the typical users never should have a way to update those attributes from the {project_name} user interface or Account REST API. Some of the attributes should
+be even read-only for the administrators when creating or updating user with the Admin REST API.
+
+The metadata attributes are usually attributes from those groups:
+
+* Various links or metadata related to the user storage providers. For example in case of the LDAP integration, the `LDAP_ID` attribute contains
+the ID of the user in the LDAP server.
+* Metadata provisioned by User Storage. For example `createdTimestamp` provisioned from the LDAP should be always read-only by user or administrator.
+* Metadata related to various authenticators. For example `KERBEROS_PRINCIPAL` attribute can contain the kerberos principal name of the particular user. Similarly attribute
+`usercertificate` can contain metadata related to binding the user with the data from the X.509 certificate, which is used typically when X.509 certificate authentication is enabled.
+* Metadata related to the identificator of users by the applications/clients. For example `saml.persistent.name.id.for.my_app` can contain SAML NameID, which will
+be used by the client application `my_app` as the identifier of the user.
+* Metadata related to the authorization policies, which are used for the attribute based access control (ABAC). Values of those attributes may be used for the
+authorization decisions. Hence it is important that those attributes cannot be updated by the users.
+
+From the long term perspective, {project_name} will have a proper User Profile SPI, which will allow fine-grained configuration of every user attribute. Currently
+this capability is not fully available yet. So {project_name} has the internal list of user attributes, which are read-only for the users and read-only for the administrators configured
+at the server level.
+
+This is the list of the read-only attributes, which are used internally by the {project_name} default providers and functionalities and hence are always read-only:
+
+* For users: `KERBEROS_PRINCIPAL`, `LDAP_ID`, `LDAP_ENTRY_DN`, `CREATED_TIMESTAMP`, `createTimestamp`, `modifyTimestamp`, `userCertificate`, `saml.persistent.name.id.for.*`, `ENABLED`, `EMAIL_VERIFIED`
+* For administrators: `KERBEROS_PRINCIPAL`, `LDAP_ID`, `LDAP_ENTRY_DN`, `CREATED_TIMESTAMP`, `createTimestamp`, `modifyTimestamp`
+
+System administrators have a way to add additional attributes to this list. The configuration is currently available at the server level.
+You can add this configuration to your `standalone(-*).xml` files to the configuration of the {project_name} server subsystem:
+
+[options="nowrap"]
+----
+<spi name="userProfile">
+    <provider name="legacy-user-profile" enabled="true">
+        <properties>
+            <property name="read-only-attributes" value="[&quot;foo&quot;,&quot;bar*&quot;]"/>
+            <property name="admin-read-only-attributes" value="[&quot;foo&quot;]"/>
+        </properties>
+    </provider>
+</spi>
+----
+
+The same can be configured with the usage of the JBoss CLI with the commands:
+
+
+[options="nowrap"]
+----
+/subsystem=keycloak-server/spi=userProfile/:add
+/subsystem=keycloak-server/spi=userProfile/provider=legacy-user-profile/:add(properties={},enabled=true)
+/subsystem=keycloak-server/spi=userProfile/provider=legacy-user-profile/:map-put(name=properties,key=read-only-attributes,value=[foo,bar*])
+/subsystem=keycloak-server/spi=userProfile/provider=legacy-user-profile/:map-put(name=properties,key=admin-read-only-attributes,value=[foo])
+----
+
+For this example, users and administrators would not be able to update attribute `foo`. Users would not be able to edit any attributes starting with the `bar`.
+So for example `bar` or `barrier`. Configuration is case insensitive, so attributes like `FOO` or `BarRier` will be denied as well for this example. The wildcard character `\*` is supported
+only at the end of the attribute name, so the administrator can effectively deny all the attributes starting with the specified character. The `*` in the middle of the attribute is considered
+as a normal character.
+

server_admin/topics/users/attributes.adoc

@@ -10,3 +10,7 @@ image:{project_images}/user-attributes.png[]
 
 Enter in the attribute name and value in the empty fields and click the `Add` button next to it to add a new field.
 Note that any edits you make on this page will not be stored until you hit the `Save` button.
+
+NOTE: Some attributes that are read-only and are not supposed to be updated by the administrators. This includes attributes, which are read-only
+by design like for example `LDAP_ID`, which is filled automatically by the LDAP provider. Some other attributes should be read-only for
+typical user administrators due to security reasons. See the details in the link:#_read_only_user_attributes[Threat model mitigation chapter].

server_development/topics/auth-spi.adoc

@@ -17,6 +17,9 @@ After the action is performed successfully, the user doesn't have to perform the
 {project_name} comes with some built in required actions like "reset password".  This action forces the user to change their password after they have logged in.
 You can write and plug in your own required actions.
 
+WARNING: If your authenticator or required action implementation is using some user attributes as the metadata attributes for linking/establishing the user identity,
+then please make sure that users are not able to edit the attributes and the corresponding attributes are read-only. See the details in the link:{adminguide_link}#_read_only_user_attributes[Threat model mitigation chapter].
+
 === Terms
 
 To first learn about the Authentication SPI, let's go over some of the terms used to describe it.

server_development/topics/user-storage.adoc

@@ -9,6 +9,9 @@ User Storage SPI provider implementations can also perform complex criteria quer
 
 User Storage SPI provider implementations are packaged and deployed similarly to (and often are) Java EE components. They are not enabled by default, but instead must be enabled and configured per realm under the `User Federation` tab in the administration console.
 
+WARNING: If your user provider implementation is using some user attributes as the metadata attributes for linking/establishing the user identity,
+then please make sure that users are not able to edit the attributes and the corresponding attributes are read-only. The example is the `LDAP_ID` attribute, which the built-in {project_name}
+LDAP provider is using for to store the ID of the user on the LDAP server side. See the details in the link:{adminguide_link}#_read_only_user_attributes[Threat model mitigation chapter].
 
 
 

upgrading/topics/keycloak/changes.adoc

@@ -2,6 +2,21 @@
 
 === Migrating to 12.0.2
 
+==== Read-only attributes
+
+There was added support for the read-only user attributes. This includes the user attributes, which are not supposed to be edited by the user
+or by the administrator when updating user with REST API or with the {project_name} user interfaces. It can be important especially if you
+use:
+
+* Custom user storage providers
+* Custom authenticators
+* Custom Javascript authorization policies, which establish authorization based on some user attribute
+* X.509 authenticator with custom attribute for mapping the X.509 certificate to the user identity
+* Any other custom functionality, where some of the user attributes are used as the metadata for storing authentication/authorization/identity context rather
+than simple user profile informations.
+
+See the details in the link:{adminguide_link}#_read_only_user_attributes[Threat model mitigation chapter].
+
 ==== Valid Request URIs
 
 If you use the OpenID Connect parameter `request_uri`, a requirement exists that your client needs to have `Valid Request URIs` configured.