SONAR-16567 Use user-friendly date format and improve notification message

6 files changed, 46 insertions, 29 deletions

diff --git a/server/sonar-docs/src/pages/setup/operate-server.md b/server/sonar-docs/src/pages/setup/operate-server.md
index b2e79ffdcc2..d336946dd7c 100644
--- a/server/sonar-docs/src/pages/setup/operate-server.md
+++ b/server/sonar-docs/src/pages/setup/operate-server.md
@@ -200,7 +200,7 @@ server {
 ```
 
 ### Forward SonarQube custom headers
-SonarQube adds custom HTTP headers in order for some features to function properly. The reverse proxy should be configured to forward the following header: `sq-authentication-token-expiration`.
+SonarQube adds custom HTTP headers in order for some features to function properly. The reverse proxy should be configured to forward the following header: `SonarQube-Authentication-Token-Expiration`.
 
 ## Secure your Network
 
diff --git a/server/sonar-webserver-auth/src/main/java/org/sonar/server/authentication/UserSessionInitializer.java b/server/sonar-webserver-auth/src/main/java/org/sonar/server/authentication/UserSessionInitializer.java
index 880fc46ccb5..1ccb613385b 100644
--- a/server/sonar-webserver-auth/src/main/java/org/sonar/server/authentication/UserSessionInitializer.java
+++ b/server/sonar-webserver-auth/src/main/java/org/sonar/server/authentication/UserSessionInitializer.java
@@ -52,7 +52,7 @@ public class UserSessionInitializer {
    */
   private static final String ACCESS_LOG_LOGIN = "LOGIN";
 
-  private static final String SQ_AUTHENTICATION_TOKEN_EXPIRATION = "sq-authentication-token-expiration";
+  private static final String SQ_AUTHENTICATION_TOKEN_EXPIRATION = "SonarQube-Authentication-Token-Expiration";
 
   // SONAR-6546 these urls should be get from WebService
   private static final Set<String> SKIPPED_URLS = Set.of(
diff --git a/server/sonar-webserver-auth/src/main/java/org/sonar/server/usertoken/notification/TokenExpirationEmailComposer.java b/server/sonar-webserver-auth/src/main/java/org/sonar/server/usertoken/notification/TokenExpirationEmailComposer.java
index d26497caf40..3202d08ef05 100644
--- a/server/sonar-webserver-auth/src/main/java/org/sonar/server/usertoken/notification/TokenExpirationEmailComposer.java
+++ b/server/sonar-webserver-auth/src/main/java/org/sonar/server/usertoken/notification/TokenExpirationEmailComposer.java
@@ -42,16 +42,22 @@ public class TokenExpirationEmailComposer extends EmailSender<TokenExpirationEma
     email.addTo(emailData.getRecipients().toArray(String[]::new));
     UserTokenDto token = emailData.getUserToken();
     if (token.isExpired()) {
-      email.setSubject(format("Your token with name \"%s\" has expired.", token.getName()));
+      email.setSubject(format("Your token \"%s\" has expired.", token.getName()));
     } else {
-      email.setSubject(format("Your token with name \"%s\" will expire on %s.", token.getName(), parseDate(token.getExpirationDate())));
+      email.setSubject(format("Your token \"%s\" will expire.", token.getName()));
     }
     email.setHtmlMsg(composeEmailBody(token));
   }
 
   private String composeEmailBody(UserTokenDto token) {
     StringBuilder builder = new StringBuilder();
-    builder.append("Token Summary<br/><br/>")
+    if (token.isExpired()) {
+      builder.append(format("Your token \"%s\" has expired.<br/><br/>", token.getName()));
+    } else {
+      builder.append(format("Your token \"%s\" will expire on %s.<br/><br/>", token.getName(), parseDate(token.getExpirationDate())));
+    }
+    builder
+      .append("Token Summary<br/><br/>")
       .append(format("Name: %s<br/>", token.getName()))
       .append(format("Type: %s<br/>", token.getType()));
     if (PROJECT_ANALYSIS_TOKEN.name().equals(token.getType())) {
@@ -62,11 +68,16 @@ public class TokenExpirationEmailComposer extends EmailSender<TokenExpirationEma
       builder.append(format("Last used on: %s<br/>", parseDate(token.getLastConnectionDate())));
     }
     builder.append(format("%s on: %s<br/>", token.isExpired() ? "Expired" : "Expires", parseDate(token.getExpirationDate())))
-      .append(format("<br/>If this token is still needed, visit <a href=\"%s/account/security/\">here</a> to generate an equivalent.", emailSettings.getServerBaseURL()));
+      .append(
+        format("<br/>If this token is still needed, please consider <a href=\"%s/account/security/\">generating</a> an equivalent.<br/><br/>", emailSettings.getServerBaseURL()))
+      .append("Don't forget to update the token in the locations where it is in use. "
+        + "This may include the CI pipeline that analyzes your projects, "
+        + "the IDE settings that connect SonarLint to SonarQube, "
+        + "and any places where you make calls to web services.");
     return builder.toString();
   }
 
   private static String parseDate(long timestamp) {
-    return Instant.ofEpochMilli(timestamp).atZone(ZoneOffset.UTC).toLocalDate().format(DateTimeFormatter.ofPattern("dd/MM/yyyy"));
+    return Instant.ofEpochMilli(timestamp).atZone(ZoneOffset.UTC).toLocalDate().format(DateTimeFormatter.ofPattern("MMMM dd, yyyy"));
   }
 }
diff --git a/server/sonar-webserver-auth/src/test/java/org/sonar/server/authentication/UserSessionInitializerTest.java b/server/sonar-webserver-auth/src/test/java/org/sonar/server/authentication/UserSessionInitializerTest.java
index f577adaea42..4e1608ef119 100644
--- a/server/sonar-webserver-auth/src/test/java/org/sonar/server/authentication/UserSessionInitializerTest.java
+++ b/server/sonar-webserver-auth/src/test/java/org/sonar/server/authentication/UserSessionInitializerTest.java
@@ -212,7 +212,7 @@ public class UserSessionInitializerTest {
     when(threadLocalSession.isLoggedIn()).thenReturn(true);
 
     assertThat(underTest.initUserSession(request, response)).isTrue();
-    verify(response).addHeader("sq-authentication-token-expiration", formatDateTime(expirationTimestamp));
+    verify(response).addHeader("SonarQube-Authentication-Token-Expiration", formatDateTime(expirationTimestamp));
   }
 
   private void assertPathIsIgnored(String path) {
diff --git a/server/sonar-webserver-auth/src/test/java/org/sonar/server/usertoken/notification/TokenExpirationEmailComposerTest.java b/server/sonar-webserver-auth/src/test/java/org/sonar/server/usertoken/notification/TokenExpirationEmailComposerTest.java
index 17a6ad0c936..d5d1513be45 100644
--- a/server/sonar-webserver-auth/src/test/java/org/sonar/server/usertoken/notification/TokenExpirationEmailComposerTest.java
+++ b/server/sonar-webserver-auth/src/test/java/org/sonar/server/usertoken/notification/TokenExpirationEmailComposerTest.java
@@ -53,16 +53,19 @@ public class TokenExpirationEmailComposerTest {
     var emailData = new TokenExpirationEmail("admin@sonarsource.com", token);
     var email = mock(HtmlEmail.class);
     underTest.addReportContent(email, emailData);
-    verify(email).setSubject(String.format("Your token with name \"projectToken\" will expire on %s.", parseDate(expiredDate)));
-    verify(email).setHtmlMsg(String.format("Token Summary<br/><br/>"
-        + "Name: projectToken<br/>"
-        + "Type: PROJECT_ANALYSIS_TOKEN<br/>"
-        + "Project: projectA<br/>"
-        + "Created on: 01/01/2022<br/>"
-        + "Last used on: 01/01/2022<br/>"
-        + "Expires on: %s<br/><br/>"
-        + "If this token is still needed, visit <a href=\"http://localhost/account/security/\">here</a> to generate an equivalent.",
-      parseDate(expiredDate)));
+    verify(email).setSubject(String.format("Your token \"projectToken\" will expire."));
+    verify(email).setHtmlMsg(
+      String.format("Your token \"projectToken\" will expire on %s.<br/><br/>"
+          + "Token Summary<br/><br/>"
+          + "Name: projectToken<br/>"
+          + "Type: PROJECT_ANALYSIS_TOKEN<br/>"
+          + "Project: projectA<br/>"
+          + "Created on: January 01, 2022<br/>"
+          + "Last used on: January 01, 2022<br/>"
+          + "Expires on: %s<br/><br/>"
+          + "If this token is still needed, please consider <a href=\"http://localhost/account/security/\">generating</a> an equivalent.<br/><br/>"
+          + "Don't forget to update the token in the locations where it is in use. This may include the CI pipeline that analyzes your projects, the IDE settings that connect SonarLint to SonarQube, and any places where you make calls to web services.",
+        parseDate(expiredDate), parseDate(expiredDate)));
   }
 
   @Test
@@ -72,15 +75,18 @@ public class TokenExpirationEmailComposerTest {
     var emailData = new TokenExpirationEmail("admin@sonarsource.com", token);
     var email = mock(HtmlEmail.class);
     underTest.addReportContent(email, emailData);
-    verify(email).setSubject("Your token with name \"globalToken\" has expired.");
-    verify(email).setHtmlMsg(String.format("Token Summary<br/><br/>"
-        + "Name: globalToken<br/>"
-        + "Type: GLOBAL_ANALYSIS_TOKEN<br/>"
-        + "Created on: 01/01/2022<br/>"
-        + "Last used on: 01/01/2022<br/>"
-        + "Expired on: %s<br/><br/>"
-        + "If this token is still needed, visit <a href=\"http://localhost/account/security/\">here</a> to generate an equivalent.",
-      parseDate(expiredDate)));
+    verify(email).setSubject("Your token \"globalToken\" has expired.");
+    verify(email).setHtmlMsg(
+      String.format("Your token \"globalToken\" has expired.<br/><br/>"
+          + "Token Summary<br/><br/>"
+          + "Name: globalToken<br/>"
+          + "Type: GLOBAL_ANALYSIS_TOKEN<br/>"
+          + "Created on: January 01, 2022<br/>"
+          + "Last used on: January 01, 2022<br/>"
+          + "Expired on: %s<br/><br/>"
+          + "If this token is still needed, please consider <a href=\"http://localhost/account/security/\">generating</a> an equivalent.<br/><br/>"
+          + "Don't forget to update the token in the locations where it is in use. This may include the CI pipeline that analyzes your projects, the IDE settings that connect SonarLint to SonarQube, and any places where you make calls to web services.",
+        parseDate(expiredDate)));
   }
 
   private UserTokenDto createToken(String name, String project, long expired) {
@@ -99,6 +105,6 @@ public class TokenExpirationEmailComposerTest {
   }
 
   private String parseDate(long timestamp) {
-    return Instant.ofEpochMilli(timestamp).atZone(ZoneOffset.UTC).toLocalDate().format(DateTimeFormatter.ofPattern("dd/MM/yyyy"));
+    return Instant.ofEpochMilli(timestamp).atZone(ZoneOffset.UTC).toLocalDate().format(DateTimeFormatter.ofPattern("MMMM dd, yyyy"));
   }
 }
diff --git a/server/sonar-webserver-webapi/src/main/java/org/sonar/server/usertoken/ws/GenerateAction.java b/server/sonar-webserver-webapi/src/main/java/org/sonar/server/usertoken/ws/GenerateAction.java
index 95ed509eb32..67599db213d 100644
--- a/server/sonar-webserver-webapi/src/main/java/org/sonar/server/usertoken/ws/GenerateAction.java
+++ b/server/sonar-webserver-webapi/src/main/java/org/sonar/server/usertoken/ws/GenerateAction.java
@@ -108,7 +108,7 @@ public class GenerateAction implements UserTokensWsAction {
 
     action.createParam(PARAM_EXPIRATION_DATE)
       .setSince("9.6")
-      .setDescription("The expiration date of the token being generated, in ISO 8601 format (YYYY-MM-DD).");
+      .setDescription("The expiration date of the token being generated, in ISO 8601 format (YYYY-MM-DD). If not set, default to no expiration.");
   }
 
   @Override