Add SecurityIdentityAugmentor section

docs/src/main/asciidoc/security.adoc

@@ -283,3 +283,51 @@ configuration to register the "SunRsaSign" and "SunJCE" security providers:
 quarkus.security.security-providers=SunRsaSign,SunJCE
 ...
 ----
+
+## Security Identity Customization
+
+Internally, the identity providers create and update an istance of the `io.quarkus.security.identity.SecurityIdentity` class which holds the principal, roles, credentials which were used to authenticate the client (user) and other security attributes. An easy option to customize `SecurityIdentity` is to register a custom `SecurityIdentityAugmentor`, for example, the augmentor below adds an addition role:
+
+[source,java]
+--
+import java.util.concurrent.CompletableFuture;
+import java.util.concurrent.CompletionStage;
+import javax.enterprise.context.ApplicationScoped;
+
+import io.quarkus.security.identity.AuthenticationRequestContext;
+import io.quarkus.security.identity.SecurityIdentity;
+import io.quarkus.security.identity.SecurityIdentityAugmentor;
+import io.quarkus.security.runtime.QuarkusSecurityIdentity;
+
+@ApplicationScoped
+public class RolesAugmentor implements SecurityIdentityAugmentor {
+
+    @Override
+    public int priority() {
+        return 0;
+    }
+
+    @Override
+    public CompletionStage<SecurityIdentity> augment(SecurityIdentity identity, AuthenticationRequestContext context) {
+
+        CompletableFuture<SecurityIdentity> cs = new CompletableFuture<>();
+        if (identity.isAnonymous()) {
+            cs.complete(identity);
+        } else {
+            // create a new builder and copy principal, attributes, credentials and roles from the original
+            QuarkusSecurityIdentity.Builder builder = QuarkusSecurityIdentity.builder()
+                .setPrincipal(identity.getPrincipal())
+                .addAttributes(identity.getAttributes())
+                .addCredentials(identity.getCredentials())
+                .addRoles(identity.getRoles());
+
+            // add custom role source here
+            builder.addRole("dummy");
+
+            cs.complete(builder.build());
+        }
+
+        return cs;
+    }
+}
+--