Documentation

In Ripplo

1. Run npx ripplo setup, or open the project's settings, choose Environment, then Sign-in connections, then Add connection, then OpenID Connect, and enter a name.
2. Copy the discovery URL, client id, and client secret it shows.

In your app

3. Add the Ripplo provider to your better-auth config. baseUrl is the base URL the app already gives better-auth.
   tsCopy

   import { genericOAuth } from "better-auth/plugins/generic-oauth";
   
   const RIPPLO_PROVIDER_ID = "ripplo";
   
   function ripploProviderPlugins() {
     const clientId = process.env.RIPPLO_IDP_CLIENT_ID;
     const clientSecret = process.env.RIPPLO_IDP_CLIENT_SECRET;
     const discoveryUrl = process.env.RIPPLO_IDP_DISCOVERY_URL;
     if (clientId == null || clientSecret == null || discoveryUrl == null) {
       return [];
     }
     return [
       genericOAuth({
         config: [
           {
             authentication: "basic",
             clientId,
             clientSecret,
             discoveryUrl,
             pkce: false,
             providerId: RIPPLO_PROVIDER_ID,
             redirectURI: `${baseUrl}/api/auth/oauth2/callback/${RIPPLO_PROVIDER_ID}`,
             scopes: ["openid", "email", "profile", "ripplo"],
           },
         ],
       }),
     ];
   }
   
   export const auth = betterAuth({
     account: { accountLinking: { enabled: true, trustedProviders: [RIPPLO_PROVIDER_ID] } },
     plugins: [...existingPlugins, ...ripploProviderPlugins()],
   });

4. Add a GET route at your sign-in page address. The example uses Express. /dashboard is where a signed-in user lands.
   tsCopy

   import { fromNodeHeaders } from "better-auth/node";
   
   app.get("/api/test-sso", (request, response) => {
     void auth.api
       .signInWithOAuth2({
         body: { callbackURL: "/dashboard", providerId: "ripplo" },
         headers: fromNodeHeaders(request.headers),
         returnHeaders: true,
       })
       .then(({ headers, response: started }) => {
         headers.getSetCookie().forEach((cookie) => response.append("set-cookie", cookie));
         response.redirect(302, started.url);
       });
   });

5. Set RIPPLO_IDP_CLIENT_ID, RIPPLO_IDP_CLIENT_SECRET, and RIPPLO_IDP_DISCOVERY_URL to the values from step 2 where your app runs, then deploy.

Back in Ripplo

6. Go back to setup, or to the connection in the project's settings.
7. Enter your app's address followed by /api/auth/oauth2/callback/ripplo as the callback, for example https://app.example.com/api/auth/oauth2/callback/ripplo. Settings calls this field Redirect URIs.
8. Enter the path of that GET route as the Sign-in page, for example /api/test-sso.

In Ripplo

1. Run npx ripplo setup, or open the project's settings, choose Environment, then Sign-in connections, then Add connection, then OpenID Connect, and enter a name.
2. Copy the discovery URL, client id, and client secret it shows.

In your app

3. Add the Ripplo provider to your Auth.js config. allowDangerousEmailAccountLinking lets the email in the token create the user on first sign-in.
   tsCopy

   import NextAuth from "next-auth";
   
   const ripploProvider =
     process.env.RIPPLO_IDP_CLIENT_ID != null &&
     process.env.RIPPLO_IDP_CLIENT_SECRET != null &&
     process.env.RIPPLO_IDP_DISCOVERY_URL != null
       ? [
           {
             id: "ripplo",
             name: "Ripplo",
             type: "oidc" as const,
             clientId: process.env.RIPPLO_IDP_CLIENT_ID,
             clientSecret: process.env.RIPPLO_IDP_CLIENT_SECRET,
             wellKnown: process.env.RIPPLO_IDP_DISCOVERY_URL,
             authorization: { params: { scope: "openid email profile ripplo" } },
             checks: ["state" as const],
             client: { token_endpoint_auth_method: "client_secret_basic" as const },
             allowDangerousEmailAccountLinking: true,
           },
         ]
       : [];
   
   export const { handlers, auth, signIn } = NextAuth({
     providers: [...existingProviders, ...ripploProvider],
   });

4. Add a route handler at your sign-in page address. /dashboard is where a signed-in user lands.
   tsCopy

   import { signIn } from "@/auth";
   
   export async function GET(): Promise<Response> {
     if (process.env.RIPPLO_IDP_CLIENT_ID == null) {
       return new Response("Not found", { status: 404 });
     }
     return signIn("ripplo", { redirectTo: "/dashboard" });
   }

5. Set RIPPLO_IDP_CLIENT_ID, RIPPLO_IDP_CLIENT_SECRET, and RIPPLO_IDP_DISCOVERY_URL to the values from step 2 where your app runs, then deploy.

Back in Ripplo

6. Go back to setup, or to the connection in the project's settings.
7. Enter your app's address followed by /api/auth/callback/ripplo as the callback, for example https://app.example.com/api/auth/callback/ripplo. Settings calls this field Redirect URIs.
8. Enter the path of that route handler as the Sign-in page.

In Ripplo

1. Run npx ripplo setup, or open the project's settings, choose Environment, then Sign-in connections, then Add connection, then OpenID Connect, and enter a name.
2. Copy the discovery URL, client id, and client secret it shows.

In the Clerk dashboard

3. Open SSO connections, choose Add connection, then For all users, then Custom provider.
4. Set Name to "Ripplo" and Key to "ripplo". Clerk puts this information in the HTML of the auth screen, which Ripplo uses to sign in test users.
5. Paste the discovery URL, client id, and client secret from step 2 into Discovery Endpoint, Client ID, and Client Secret.
6. Select Add connection to save. Clerk then opens the connection page.
7. Turn on Enable connection.
8. If Bot sign-up protection is on, turn it off. Its challenge can stop the test browser.
9. Copy the Authorized redirect URLs value Clerk shows, such as https://clerk.example.com/v1/oauth_callback.

Back in Ripplo

10. Go back to setup, or to the connection in the project's settings.
11. Paste that URL as the callback. Settings calls this field Redirect URIs.
12. Enter the path of your login page as the Sign-in page, for example /login.

Ripplo opens that page and clicks the Ripplo button, so the page must show only one Ripplo button. After sign-in, the app must go to another path. A root path that shows the login form when signed out and the app when signed in does not work.

In Ripplo

1. Run npx ripplo setup, or open the project's settings, choose Environment, then Sign-in connections, then Add connection, then OpenID Connect, and enter a name.
2. Copy the discovery URL, client id, and client secret it shows.

In the Keycloak admin console

3. In the realm your test app uses, open Identity providers and add an OpenID Connect v1.0 provider.
4. Set Alias to "ripplo".
5. Turn on Use discovery endpoint and paste the discovery URL from step 2 as the Discovery endpoint.
6. Set Client authentication to Client secret sent as basic auth, then paste the client id and client secret from step 2 into Client ID and Client Secret.
7. Set Scopes to "openid email profile ripplo".
8. Turn on Trust Email and Hide on login page.
9. Keep the default First login flow override, so Keycloak creates the user on first sign-in.
10. Copy the Redirect URI Keycloak shows. It ends in /broker/ripplo/endpoint.

Back in Ripplo

11. Go back to setup, or to the connection in the project's settings.
12. Paste the Redirect URI as the callback. Settings calls this field Redirect URIs.
13. Enter your login path with the provider hint as the Sign-in page, for example /login?kc_idp_hint=ripplo.