state = base64url(dbName) + "." + base64url(32-random-bytes)

// package org.restheart.plugins.accounts  (in restheart-commons)
public interface OAuthProvider {
    String getProviderName();
    String getAuthorizationUrl(String clientId, String clientSecret,
                               String callbackUrl, String scope, String state);
    BsonDocument fetchUserProfile(String clientId, String clientSecret,
                                  String callbackUrl, String scope, String code) throws Exception;
}

import org.bson.BsonDocument;
import org.bson.BsonNull;
import org.bson.BsonString;
import org.restheart.plugins.Initializer;
import org.restheart.plugins.Inject;
import org.restheart.plugins.RegisterPlugin;
import org.restheart.plugins.accounts.OAuthProvider;
import org.restheart.plugins.accounts.OAuthProviderRegistry;

@RegisterPlugin(name = "myappOAuthProvider", description = "MyApp OAuth provider")
public class MyAppOAuthProvider implements OAuthProvider, Initializer {

    // Inject OAuthProviderRegistry (not OAuthService) — available in restheart-commons only
    @Inject("oauthService")
    private OAuthProviderRegistry oauthService;

    @Override
    public void init() {
        oauthService.registerProvider(this);
    }

    /**
     * Must return the key used in oauthConfig.providers.
     * The OAuth endpoints derive the provider name from the URL path:
     *   /auth/oauth/authorize/myapp  →  getProviderName() == "myapp"
     */
    @Override
    public String getProviderName() { return "myapp"; }

    /**
     * Build and return the provider's authorization URL.
     * Include the state parameter verbatim — it is required for CSRF protection.
     */
    @Override
    public String getAuthorizationUrl(String clientId, String clientSecret,
                                      String callbackUrl, String scope, String state) {
        // Use any OAuth library or build the URL manually.
        // Example with ScribeJava:
        //   return new ServiceBuilder(clientId)
        //           .apiSecret(clientSecret).callback(callbackUrl).defaultScope(scope)
        //           .build(MyAppApi.instance()).getAuthorizationUrl(state);
        return "https://myapp.example.com/oauth/authorize"
                + "?client_id=" + clientId
                + "&redirect_uri=" + callbackUrl
                + "&scope=" + scope
                + "&state=" + state;
    }

    /**
     * Exchange the authorization code for an access token, then fetch the user
     * profile. Return a BsonDocument with: email, name, providerId, avatarUrl.
     */
    @Override
    public BsonDocument fetchUserProfile(String clientId, String clientSecret,
                                         String callbackUrl, String scope, String code)
            throws Exception {
        // 1. Exchange code for access token (use any HTTP client).
        var token = exchangeCodeForToken(clientId, clientSecret, callbackUrl, code);

        // 2. Fetch user profile and map to BsonDocument.
        return new BsonDocument()
                .append("email",      new BsonString(fetchEmail(token)))
                .append("name",       new BsonString(fetchName(token)))
                .append("providerId", new BsonString(fetchProviderId(token)))
                .append("avatarUrl",  BsonNull.VALUE);
    }

    // private helper methods ...
}

oauthConfig:
  enabled: true
  api-base-url: https://api.example.com
  frontend-success-url: https://app.example.com/app
  frontend-error-url:   https://app.example.com/login?error=oauth_error

  providers:
    myapp:
      enabled: true
      client-id:     "…"
      client-secret: "…"
      scope:         "read:profile"