documentation: update system admin guide

cloudfoundry · Oct 4, 2023 · de6c560 · de6c560
1 parent bf51726
commit de6c560
Showing 1 changed file with 48 additions and 26 deletions.
diff --git a/docs/Sysadmin-Guide.rst b/docs/Sysadmin-Guide.rst
@@ -68,7 +68,7 @@ Requirements:
 
 ::
 
-    java >= 1.7
+    java >= 11
 
 Clone, build UAA server:
 
@@ -103,14 +103,15 @@ written as an environment variable. For a Cloud Foundry application this could l
     ---
       applications:
       - name: standalone-uaa-cf-war
-        memory: 512M
+        memory: 4096M
         instances: 1
         host: standalone-uaa
-        path: cloudfoundry-identity-uaa-3.0.0-SNAPSHOT.war
+        path: cloudfoundry-identity-uaa-0.0.0-SNAPSHOT.war
         env:
           JBP_CONFIG_SPRING_AUTO_RECONFIGURATION: '[enabled: false]'
-          JBP_CONFIG_TOMCAT: '{tomcat: { version: 7.0.+ }}'
+          JBP_CONFIG_TOMCAT: '{tomcat: { version: 9.0.+ }}'
           SPRING_PROFILES_ACTIVE: hsqldb,default
+          JAVA_OPTS: '-Djava.security.egd=file:/dev/./urandom -Dlogging.config=/usr/local/tomcat/conf/log4j2.properties'
           UAA_CONFIG_YAML: |
             uaa.url: http://standalone-uaa.cfapps.io
             login.url: http://standalone-uaa.cfapps.io
@@ -145,19 +146,29 @@ database:
 Token signing
 -------------
 
-UAA can use either symmetric key encryption (shared secrets) or public
-key encryption.
+UAA supports either symmetric key encryption (shared secrets) or public
+key encryption, however it is strongly recommended to use public key encryption.
 
 .. code-block:: yaml
 
    jwt:
-      token:
-         signing-key: …
-         verification-key: …
-
-If you want to use symmetric key encryption, signing and verification values should be the same.
-
-Generating new asymmetric key pairs
+     token:
+       policy:
+         activeKeyId: key-id-1-or-better-a-UUID
+         keys:
+           key-id-1-or-better-a-UUID:
+             signingAlg: RS256
+             signingKey: …
+             signingCert: …
+
+If you want to use symmetric key encryption, signing and verification values should be the same and the signingAlg can be from HS256 to HS512.
+The public or asymmetric key encryption requires at least a signingKey. This key must be compatible to the signingAlg. If no parameter signingAlg is
+specified the default either RS256 or HS256 is taken. This default depends on the key and its format. For other algorithms, e.g. see the supported
+ones in RFC 7518 (https://datatracker.ietf.org/doc/html/rfc7518#section-3.1), the signingKey must be compatible, e.g. ES256. If you set signingCert,
+then the token_key endpoint contain the x5t claim with the PEM encoded X509 representation. This can be used as trust anchor towards other OIDC
+Identity Proviers. If no signingCert is defined, then it does not appear in token_key.
+
+Generating new asymmetric key pairs for RSA based algorithm
 
 ::
 
@@ -166,25 +177,36 @@ Generating new asymmetric key pairs
     openssl genrsa -out privkey.pem 2048
     openssl rsa -pubout -in privkey.pem -out pubkey.pem
 
+Generating new asymmetric key pairs for Elliptic Curve based algorithm, e.g. ES256
+
+::
+
+    openssl ecparam -genkey -name prime256v1 -noout -out ec256-key-pair.pem
+
 Aysmmetric key pairs can be set directly in the yaml file using block literals.
 Make sure the entire key is indented.
 
 .. code-block:: yaml
 
    jwt:
-      token:
-         signing-key: |
-            -----BEGIN RSA PRIVATE KEY-----
-            MIIEowIBAAKCAQEAyV3Ws3gLOvi169ZPx8v3t9UZpxcG0fqtQzC4X+Ff7dlx4w6P
-            ...
-            pYPYK4M+4Gwi7O49a63G+lzX7BqUWYBXR84iZG+vWz2F3ICjiOIz
-            -----END RSA PRIVATE KEY-----
-         verification-key: |
-            -----BEGIN PUBLIC KEY-----
-            MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAyV3Ws3gLOvi169ZPx8v3
-            ...
-            XwIDAQAB
-            -----END PUBLIC KEY-----
+     token:
+       policy:
+         activeKeyId: key-id-1-or-better-a-UUID
+         keys:
+           key-id-1-or-better-a-UUID:
+             signingAlg: RS256
+             signingKey: |
+               -----BEGIN RSA PRIVATE KEY-----
+               MIIEowIBAAKCAQEAyV3Ws3gLOvi169ZPx8v3t9UZpxcG0fqtQzC4X+Ff7dlx4w6P
+               ...
+               pYPYK4M+4Gwi7O49a63G+lzX7BqUWYBXR84iZG+vWz2F3ICjiOIz
+               -----END RSA PRIVATE KEY-----
+             signingCert: |
+               -----BEGIN CERTIFICATE-----
+               MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAyV3Ws3gLOvi169ZPx8v3
+               ...
+               XwIDAQAB
+               -----END PUBLIC KEY-----
 
 Clients
 -------