Set up single sign-on with your identity provider
Let members sign in to your community with the account they already have, by connecting your OAuth 2.0 or OpenID Connect provider in Brand Control Center.
With SSO configured, the sign-in sheet shows a Continue with <your brand> button next to Google and Apple. It appears on your community site, in the Genuin app, and in your SDK-powered app. A member who taps it is sent to your identity provider, signs in there or is recognised by an existing session, and comes back signed in to the community. Genuin creates the member account from the profile your provider returns and links it to the provider's user id, so the same person gets the same account on every device.
SSO is for brands whose users already have accounts with an OAuth 2.0 or OpenID Connect provider such as Auth0, Okta, Cognito, or Keycloak. If your app has its own session and no OAuth provider, use Auto Login instead; see Understand user authentication mechanisms in the Genuin SDK for the comparison.
Before you begin
| Requirement | Detail |
|---|---|
| An application at your identity provider | A confidential client that supports the authorization code flow. You need its client ID and client secret. |
| Callback URLs registered with that application | Add Genuin's callback URL for each environment you use. The four URLs are listed under this table. |
| A user info endpoint | Genuin reads the member's profile from your provider's user info endpoint after sign-in. It needs a user id, an email address, and an email-verified flag. |
| Discovery document, if you have one | https://<issuer>/.well-known/openid-configuration. With it, you enter one URL instead of three endpoints. |
Callback URLs:
- Production:
https://api.begenuin.com/api/v4/thirdparty/callbackandhttps://nodejs.prod.begenuin.com/api/v4/thirdparty/callback - QA:
https://api.qa.begenuin.com/api/v4/thirdparty/callbackandhttps://nodejs.qa.begenuin.com/api/v4/thirdparty/callback
Configure SSO
- In Brand Control Center, go to Settings > Setup Single Sign On (SSO).
- Fill in Primary Details:
| Field | What to enter |
|---|---|
| CTA Display Name | A name for the sign-in button. Required, although the apps currently label the button Continue with <your brand name>. |
| Client ID | The application's client ID from your provider. |
| Client Secret | The application's client secret. The eye icon shows or hides it while you type. |
| Third Party ID | Optional. The identifier Genuin uses for your provider. Leave it empty to use your community subdomain. |
- Answer Have an "OIDC Discovery Endpoint"?
- Yes: paste the discovery URL into OIDC Discovery Endpoint. Genuin reads the authorization, token, and user info endpoints from it.
- No: enter the three endpoints yourself. Authorization Endpoint is where the member is sent to sign in; Token Endpoint is where Genuin exchanges the code for tokens; User Info Endpoint is where it reads the profile. Authorization Endpoint Query Params and Token Endpoint Body Params take the names of extra parameters your provider expects on those requests.
- Set Scope.
openid,profile, andemailare always sent; add any scope your user info endpoint needs for the fields you map. Your discovery document lists the scopes it supports underscopes_supported. - Fill in User Info Mapping. Each row maps a Genuin field (Key) to the name of the field in your user info response (Value).
userid,email, andemailVerifiedare required; for a standard OpenID Connect provider they map tosub,email, andemail_verified. Click New to mapage,bio,birthdate,country_code,gender,is_mobile_verified, ormobileas well. For a field inside a nested object, write the path with dots, such asdata.profile.id.
- Click Save. Brand Control Center confirms with "SSO configuration successfully updated." The brand sign-in button appears on your community site and in your apps on their next load.
- Test it: open your community site, choose to sign in, and click Continue with <your brand>. You're sent to your provider and back, signed in as a member whose email matches the one your provider returned.
How the sign-in runs
- The member taps Continue with <your brand>. The app asks Genuin for the authorization URL for your provider and opens it.
- The member signs in at your provider, or is passed through by an existing provider session.
- Your provider redirects to Genuin's callback with an authorization code. The callback forwards the code to the page or app the member started from.
- The app sends the code to Genuin. Genuin exchanges it at your token endpoint, calls your user info endpoint, and applies the mapping.
- Genuin finds the member by your provider's user id, or creates the account on first sign-in, and starts a session.
Google and Apple sign-in stay available next to your button, and a member can use any of them.
Limitations
- One provider per brand. The form holds a single configuration.
- Authorization code flow only. SAML and the implicit flow aren't supported.
- Mapping reads the user info endpoint, not the ID token. A claim that exists only in the ID token can't be mapped.
- Extra parameters are names only. The query and body parameter boxes take parameter names; their values aren't configurable.
- The button label is your brand name. The CTA Display Name is stored but not shown.
- No test button. Verify by signing in on the community site after saving.
