diff --git a/UPGRADE-2.8.md b/UPGRADE-2.8.md
index 1d299af3e6..cf3edac756 100644
--- a/UPGRADE-2.8.md
+++ b/UPGRADE-2.8.md
@@ -546,6 +546,95 @@ Security
* The `VoterInterface::supportsClass` and `supportsAttribute` methods were
deprecated and will be removed from the interface in 3.0.
+
+ * The the `key` setting of `anonymous`, `remember_me` and `http_digest`
+ is deprecated, and will be removed in 3.0. Use `secret` instead.
+
+ Before:
+
+ ```yaml
+ security:
+ # ...
+ firewalls:
+ default:
+ # ...
+ anonymous: { key: "%secret%" }
+ remember_me:
+ key: "%secret%"
+ http_digest:
+ key: "%secret%"
+ ```
+
+ ```xml
+
+
+
+
+
+
+
+
+
+
+
+
+ ```
+
+ ```php
+ // ...
+ $container->loadFromExtension('security', array(
+ // ...
+ 'firewalls' => array(
+ // ...
+ 'anonymous' => array('key' => '%secret%'),
+ 'remember_me' => array('key' => '%secret%'),
+ 'http_digest' => array('key' => '%secret%'),
+ ),
+ ));
+ ```
+
+ After:
+
+ ```yaml
+ security:
+ # ...
+ firewalls:
+ default:
+ # ...
+ anonymous: { secret: "%secret%" }
+ remember_me:
+ secret: "%secret%"
+ http_digest:
+ secret: "%secret%"
+ ```
+
+ ```xml
+
+
+
+
+
+
+
+
+
+
+
+
+ ```
+
+ ```php
+ // ...
+ $container->loadFromExtension('security', array(
+ // ...
+ 'firewalls' => array(
+ // ...
+ 'anonymous' => array('secret' => '%secret%'),
+ 'remember_me' => array('secret' => '%secret%'),
+ 'http_digest' => array('secret' => '%secret%'),
+ ),
+ ));
+ ```
* The `intention` option is deprecated for all the authentication listeners,
and will be removed in 3.0. Use the `csrf_token_id` option instead.