SSO Refactoring (#2818)

# Description of Changes

* Refactoring of SSO code around OAuth & SAML 2
* Enabling auto-login with SAML 2 via the new `SSOAutoLogin` property
* Correcting typos & general cleanup

---

## Checklist

### General

- [x] I have read the [Contribution
Guidelines](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/CONTRIBUTING.md)
- [x] I have read the [Stirling-PDF Developer
Guide](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/DeveloperGuide.md)
(if applicable)
- [x] I have read the [How to add new languages to
Stirling-PDF](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/HowToAddNewLanguage.md)
(if applicable)
- [x] I have performed a self-review of my own code
- [x] My changes generate no new warnings

### Documentation

- [x] I have updated relevant docs on [Stirling-PDF's doc
repo](https://github.com/Stirling-Tools/Stirling-Tools.github.io/blob/main/docs/)
(if functionality has heavily changed)
- [x] I have read the section [Add New Translation
Tags](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/HowToAddNewLanguage.md#add-new-translation-tags)
(for new translation tags only)

### UI Changes (if applicable)

- [ ] Screenshots or videos demonstrating the UI changes are attached
(e.g., as comments or direct attachments in the PR)

### Testing (if applicable)

- [x] I have tested my changes locally. Refer to the [Testing
Guide](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/DeveloperGuide.md#6-testing)
for more details.

src/main/java/stirling/software/SPDF/model/provider/GitHubProvider.java

@@ -0,0 +1,86 @@
+package stirling.software.SPDF.model.provider;
+
+import java.util.ArrayList;
+import java.util.Collection;
+
+import lombok.NoArgsConstructor;
+import stirling.software.SPDF.model.UsernameAttribute;
+
+@NoArgsConstructor
+public class GitHubProvider extends Provider {
+
+    private static final String NAME = "github";
+    private static final String CLIENT_NAME = "GitHub";
+    private static final String AUTHORIZATION_URI = "https://github.com/login/oauth/authorize";
+    private static final String TOKEN_URI = "https://github.com/login/oauth/access_token";
+    private static final String USER_INFO_URI = "https://api.github.com/user";
+
+    public GitHubProvider(
+            String clientId,
+            String clientSecret,
+            Collection<String> scopes,
+            UsernameAttribute useAsUsername) {
+        super(
+                null,
+                NAME,
+                CLIENT_NAME,
+                clientId,
+                clientSecret,
+                scopes,
+                useAsUsername != null ? useAsUsername : UsernameAttribute.LOGIN,
+                null,
+                AUTHORIZATION_URI,
+                TOKEN_URI,
+                USER_INFO_URI);
+    }
+
+    @Override
+    public String getAuthorizationUri() {
+        return AUTHORIZATION_URI;
+    }
+
+    @Override
+    public String getTokenUri() {
+        return TOKEN_URI;
+    }
+
+    @Override
+    public String getUserInfoUri() {
+        return USER_INFO_URI;
+    }
+
+    @Override
+    public String getName() {
+        return NAME;
+    }
+
+    @Override
+    public String getClientName() {
+        return CLIENT_NAME;
+    }
+
+    @Override
+    public Collection<String> getScopes() {
+        Collection<String> scopes = super.getScopes();
+
+        if (scopes == null || scopes.isEmpty()) {
+            scopes = new ArrayList<>();
+            scopes.add("read:user");
+        }
+
+        return scopes;
+    }
+
+    @Override
+    public String toString() {
+        return "GitHub [clientId="
+                + getClientId()
+                + ", clientSecret="
+                + (getClientSecret() != null && !getClientSecret().isEmpty() ? "*****" : "NULL")
+                + ", scopes="
+                + getScopes()
+                + ", useAsUsername="
+                + getUseAsUsername()
+                + "]";
+    }
+}

src/main/java/stirling/software/SPDF/model/provider/GithubProvider.java

@@ -1,114 +0,0 @@
-package stirling.software.SPDF.model.provider;
-
-import java.util.ArrayList;
-import java.util.Arrays;
-import java.util.Collection;
-import java.util.stream.Collectors;
-
-import stirling.software.SPDF.model.Provider;
-
-public class GithubProvider extends Provider {
-
-    private static final String authorizationUri = "https://github.com/login/oauth/authorize";
-    private static final String tokenUri = "https://github.com/login/oauth/access_token";
-    private static final String userInfoUri = "https://api.github.com/user";
-    private String clientId;
-    private String clientSecret;
-    private Collection<String> scopes = new ArrayList<>();
-    private String useAsUsername = "login";
-
-    public String getAuthorizationuri() {
-        return authorizationUri;
-    }
-
-    public String getTokenuri() {
-        return tokenUri;
-    }
-
-    public String getUserinfouri() {
-        return userInfoUri;
-    }
-
-    @Override
-    public String getIssuer() {
-        return new String();
-    }
-
-    @Override
-    public void setIssuer(String issuer) {}
-
-    @Override
-    public String getClientId() {
-        return this.clientId;
-    }
-
-    @Override
-    public void setClientId(String clientId) {
-        this.clientId = clientId;
-    }
-
-    @Override
-    public String getClientSecret() {
-        return this.clientSecret;
-    }
-
-    @Override
-    public void setClientSecret(String clientSecret) {
-        this.clientSecret = clientSecret;
-    }
-
-    @Override
-    public Collection<String> getScopes() {
-        if (scopes == null || scopes.isEmpty()) {
-            scopes = new ArrayList<>();
-            scopes.add("read:user");
-        }
-        return scopes;
-    }
-
-    @Override
-    public void setScopes(String scopes) {
-        this.scopes =
-                Arrays.stream(scopes.split(",")).map(String::trim).collect(Collectors.toList());
-    }
-
-    @Override
-    public String getUseAsUsername() {
-        return this.useAsUsername;
-    }
-
-    @Override
-    public void setUseAsUsername(String useAsUsername) {
-        this.useAsUsername = useAsUsername;
-    }
-
-    @Override
-    public String toString() {
-        return "GitHub [clientId="
-                + clientId
-                + ", clientSecret="
-                + (clientSecret != null && !clientSecret.isEmpty() ? "MASKED" : "NULL")
-                + ", scopes="
-                + scopes
-                + ", useAsUsername="
-                + useAsUsername
-                + "]";
-    }
-
-    @Override
-    public String getName() {
-        return "github";
-    }
-
-    @Override
-    public String getClientName() {
-        return "GitHub";
-    }
-
-    public boolean isSettingsValid() {
-        return super.isValid(this.getClientId(), "clientId")
-                && super.isValid(this.getClientSecret(), "clientSecret")
-                && super.isValid(this.getScopes(), "scopes")
-                && isValid(this.getUseAsUsername(), "useAsUsername");
-    }
-}

src/main/java/stirling/software/SPDF/model/provider/GoogleProvider.java

@@ -1,116 +1,85 @@
 package stirling.software.SPDF.model.provider;
 
 import java.util.ArrayList;
-import java.util.Arrays;
 import java.util.Collection;
-import java.util.stream.Collectors;
 
-import stirling.software.SPDF.model.Provider;
+import lombok.NoArgsConstructor;
+import stirling.software.SPDF.model.UsernameAttribute;
 
+@NoArgsConstructor
 public class GoogleProvider extends Provider {
 
-    private static final String authorizationUri = "https://accounts.google.com/o/oauth2/v2/auth";
-    private static final String tokenUri = "https://www.googleapis.com/oauth2/v4/token";
-    private static final String userInfoUri =
+    private static final String NAME = "google";
+    private static final String CLIENT_NAME = "Google";
+    private static final String AUTHORIZATION_URI = "https://accounts.google.com/o/oauth2/v2/auth";
+    private static final String TOKEN_URI = "https://www.googleapis.com/oauth2/v4/token";
+    private static final String USER_INFO_URI =
             "https://www.googleapis.com/oauth2/v3/userinfo?alt=json";
-    private String clientId;
-    private String clientSecret;
-    private Collection<String> scopes = new ArrayList<>();
-    private String useAsUsername = "email";
 
-    public String getAuthorizationuri() {
-        return authorizationUri;
+    public GoogleProvider(
+            String clientId,
+            String clientSecret,
+            Collection<String> scopes,
+            UsernameAttribute useAsUsername) {
+        super(
+                null,
+                NAME,
+                CLIENT_NAME,
+                clientId,
+                clientSecret,
+                scopes,
+                useAsUsername,
+                null,
+                AUTHORIZATION_URI,
+                TOKEN_URI,
+                USER_INFO_URI);
     }
 
-    public String getTokenuri() {
-        return tokenUri;
+    public String getAuthorizationUri() {
+        return AUTHORIZATION_URI;
     }
 
-    public String getUserinfouri() {
-        return userInfoUri;
+    public String getTokenUri() {
+        return TOKEN_URI;
+    }
+
+    public String getUserinfoUri() {
+        return USER_INFO_URI;
     }
 
     @Override
-    public String getIssuer() {
-        return new String();
+    public String getName() {
+        return NAME;
     }
 
     @Override
-    public void setIssuer(String issuer) {}
-
-    @Override
-    public String getClientId() {
-        return this.clientId;
-    }
-
-    @Override
-    public void setClientId(String clientId) {
-        this.clientId = clientId;
-    }
-
-    @Override
-    public String getClientSecret() {
-        return this.clientSecret;
-    }
-
-    @Override
-    public void setClientSecret(String clientSecret) {
-        this.clientSecret = clientSecret;
+    public String getClientName() {
+        return CLIENT_NAME;
     }
 
     @Override
     public Collection<String> getScopes() {
+        Collection<String> scopes = super.getScopes();
+
         if (scopes == null || scopes.isEmpty()) {
             scopes = new ArrayList<>();
             scopes.add("https://www.googleapis.com/auth/userinfo.email");
             scopes.add("https://www.googleapis.com/auth/userinfo.profile");
         }
+
         return scopes;
     }
 
-    @Override
-    public void setScopes(String scopes) {
-        this.scopes =
-                Arrays.stream(scopes.split(",")).map(String::trim).collect(Collectors.toList());
-    }
-
-    @Override
-    public String getUseAsUsername() {
-        return this.useAsUsername;
-    }
-
-    @Override
-    public void setUseAsUsername(String useAsUsername) {
-        this.useAsUsername = useAsUsername;
-    }
-
     @Override
     public String toString() {
         return "Google [clientId="
-                + clientId
+                + getClientId()
                 + ", clientSecret="
-                + (clientSecret != null && !clientSecret.isEmpty() ? "MASKED" : "NULL")
+                + (getClientSecret() != null && !getClientSecret().isEmpty() ? "*****" : "NULL")
                 + ", scopes="
-                + scopes
+                + getScopes()
                 + ", useAsUsername="
-                + useAsUsername
+                + getUseAsUsername()
                 + "]";
     }
-
-    @Override
-    public String getName() {
-        return "google";
-    }
-
-    @Override
-    public String getClientName() {
-        return "Google";
-    }
-
-    public boolean isSettingsValid() {
-        return super.isValid(this.getClientId(), "clientId")
-                && super.isValid(this.getClientSecret(), "clientSecret")
-                && super.isValid(this.getScopes(), "scopes")
-                && isValid(this.getUseAsUsername(), "useAsUsername");
-    }
 }

src/main/java/stirling/software/SPDF/model/provider/KeycloakProvider.java

@@ -1,106 +1,72 @@
 package stirling.software.SPDF.model.provider;
 
 import java.util.ArrayList;
-import java.util.Arrays;
 import java.util.Collection;
-import java.util.stream.Collectors;
 
-import stirling.software.SPDF.model.Provider;
+import lombok.NoArgsConstructor;
+import stirling.software.SPDF.model.UsernameAttribute;
 
+@NoArgsConstructor
 public class KeycloakProvider extends Provider {
 
-    private String issuer;
-    private String clientId;
-    private String clientSecret;
-    private Collection<String> scopes = new ArrayList<>();
-    private String useAsUsername = "email";
+    private static final String NAME = "keycloak";
+    private static final String CLIENT_NAME = "Keycloak";
 
-    @Override
-    public String getIssuer() {
-        return this.issuer;
+    public KeycloakProvider(
+            String issuer,
+            String clientId,
+            String clientSecret,
+            Collection<String> scopes,
+            UsernameAttribute useAsUsername) {
+        super(
+                issuer,
+                NAME,
+                CLIENT_NAME,
+                clientId,
+                clientSecret,
+                scopes,
+                useAsUsername,
+                null,
+                null,
+                null,
+                null);
     }
 
     @Override
-    public void setIssuer(String issuer) {
-        this.issuer = issuer;
+    public String getName() {
+        return NAME;
     }
 
     @Override
-    public String getClientId() {
-        return this.clientId;
-    }
-
-    @Override
-    public void setClientId(String clientId) {
-        this.clientId = clientId;
-    }
-
-    @Override
-    public String getClientSecret() {
-        return this.clientSecret;
-    }
-
-    @Override
-    public void setClientSecret(String clientSecret) {
-        this.clientSecret = clientSecret;
+    public String getClientName() {
+        return CLIENT_NAME;
     }
 
     @Override
     public Collection<String> getScopes() {
+        Collection<String> scopes = super.getScopes();
+
         if (scopes == null || scopes.isEmpty()) {
             scopes = new ArrayList<>();
             scopes.add("profile");
             scopes.add("email");
         }
+
         return scopes;
     }
 
-    @Override
-    public void setScopes(String scopes) {
-        this.scopes =
-                Arrays.stream(scopes.split(",")).map(String::trim).collect(Collectors.toList());
-    }
-
-    @Override
-    public String getUseAsUsername() {
-        return this.useAsUsername;
-    }
-
-    @Override
-    public void setUseAsUsername(String useAsUsername) {
-        this.useAsUsername = useAsUsername;
-    }
-
     @Override
     public String toString() {
         return "Keycloak [issuer="
-                + issuer
+                + getIssuer()
                 + ", clientId="
-                + clientId
+                + getClientId()
                 + ", clientSecret="
-                + (clientSecret != null && !clientSecret.isEmpty() ? "MASKED" : "NULL")
+                + (getClientSecret() != null && !getClientSecret().isBlank() ? "*****" : "NULL")
                 + ", scopes="
-                + scopes
+                + getScopes()
                 + ", useAsUsername="
-                + useAsUsername
+                + getUseAsUsername()
                 + "]";
     }
-
-    @Override
-    public String getName() {
-        return "keycloak";
-    }
-
-    @Override
-    public String getClientName() {
-        return "Keycloak";
-    }
-
-    public boolean isSettingsValid() {
-        return isValid(this.getIssuer(), "issuer")
-                && isValid(this.getClientId(), "clientId")
-                && isValid(this.getClientSecret(), "clientSecret")
-                && isValid(this.getScopes(), "scopes")
-                && isValid(this.getUseAsUsername(), "useAsUsername");
-    }
 }

src/main/java/stirling/software/SPDF/model/provider/Provider.java

@@ -0,0 +1,134 @@
+package stirling.software.SPDF.model.provider;
+
+import static stirling.software.SPDF.model.UsernameAttribute.EMAIL;
+
+import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.Collection;
+import java.util.stream.Collectors;
+
+import lombok.Data;
+import lombok.NoArgsConstructor;
+
+import stirling.software.SPDF.model.UsernameAttribute;
+import stirling.software.SPDF.model.exception.UnsupportedUsernameAttribute;
+
+@Data
+@NoArgsConstructor
+public class Provider {
+
+    public static final String EXCEPTION_MESSAGE = "The attribute %s is not supported for %s.";
+
+    private String issuer;
+    private String name;
+    private String clientName;
+    private String clientId;
+    private String clientSecret;
+    private Collection<String> scopes;
+    private UsernameAttribute useAsUsername;
+    private String logoutUrl;
+    private String authorizationUri;
+    private String tokenUri;
+    private String userInfoUri;
+
+    public Provider(
+            String issuer,
+            String name,
+            String clientName,
+            String clientId,
+            String clientSecret,
+            Collection<String> scopes,
+            UsernameAttribute useAsUsername,
+            String logoutUrl,
+            String authorizationUri,
+            String tokenUri,
+            String userInfoUri) {
+        this.issuer = issuer;
+        this.name = name;
+        this.clientName = clientName;
+        this.clientId = clientId;
+        this.clientSecret = clientSecret;
+        this.scopes = scopes == null ? new ArrayList<>() : scopes;
+        this.useAsUsername =
+                useAsUsername != null ? validateUsernameAttribute(useAsUsername) : EMAIL;
+        this.logoutUrl = logoutUrl;
+        this.authorizationUri = authorizationUri;
+        this.tokenUri = tokenUri;
+        this.userInfoUri = userInfoUri;
+    }
+
+    public void setScopes(String scopes) {
+        if (scopes != null && !scopes.isBlank()) {
+            this.scopes =
+                    Arrays.stream(scopes.split(",")).map(String::trim).collect(Collectors.toList());
+        }
+    }
+
+    private UsernameAttribute validateUsernameAttribute(UsernameAttribute usernameAttribute) {
+        switch (name) {
+            case "google" -> {
+                return validateGoogleUsernameAttribute(usernameAttribute);
+            }
+            case "github" -> {
+                return validateGitHubUsernameAttribute(usernameAttribute);
+            }
+            case "keycloak" -> {
+                return validateKeycloakUsernameAttribute(usernameAttribute);
+            }
+            default -> {
+                return usernameAttribute;
+            }
+        }
+    }
+
+    private UsernameAttribute validateKeycloakUsernameAttribute(
+            UsernameAttribute usernameAttribute) {
+        switch (usernameAttribute) {
+            case EMAIL, NAME, GIVEN_NAME, FAMILY_NAME, PREFERRED_USERNAME -> {
+                return usernameAttribute;
+            }
+            default ->
+                    throw new UnsupportedUsernameAttribute(
+                            String.format(EXCEPTION_MESSAGE, usernameAttribute, clientName));
+        }
+    }
+
+    private UsernameAttribute validateGoogleUsernameAttribute(UsernameAttribute usernameAttribute) {
+        switch (usernameAttribute) {
+            case EMAIL, NAME, GIVEN_NAME, FAMILY_NAME -> {
+                return usernameAttribute;
+            }
+            default ->
+                    throw new UnsupportedUsernameAttribute(
+                            String.format(EXCEPTION_MESSAGE, usernameAttribute, clientName));
+        }
+    }
+
+    private UsernameAttribute validateGitHubUsernameAttribute(UsernameAttribute usernameAttribute) {
+        switch (usernameAttribute) {
+            case LOGIN, EMAIL, NAME -> {
+                return usernameAttribute;
+            }
+            default ->
+                    throw new UnsupportedUsernameAttribute(
+                            String.format(EXCEPTION_MESSAGE, usernameAttribute, clientName));
+        }
+    }
+
+    @Override
+    public String toString() {
+        return "Provider [name="
+                + getName()
+                + ", clientName="
+                + getClientName()
+                + ", clientId="
+                + getClientId()
+                + ", clientSecret="
+                + (getClientSecret() != null && !getClientSecret().isEmpty() ? "*****" : "NULL")
+                + ", scopes="
+                + getScopes()
+                + ", useAsUsername="
+                + getUseAsUsername()
+                + "]";
+    }
+}

src/main/java/stirling/software/SPDF/model/provider/UnsupportedProviderException.java

@@ -1,7 +0,0 @@
-package stirling.software.SPDF.model.provider;
-
-public class UnsupportedProviderException extends Exception {
-    public UnsupportedProviderException(String message) {
-        super(message);
-    }
-}