Skip to main content

Developer Setup: OpenID Integration

To enable federated login, GoWit can act as an OpenID client and use a marketplace’s existing identity provider (Auth0, Okta, etc.) for authentication. Follow the steps below to configure your environment.

1. Prerequisites​

  • Marketplace’s OpenID discovery URL (e.g., https://yourdomain.auth0.com/.well-known/openid-configuration)
  • Client ID and Client Secret from the identity provider
  • Redirect URI registered/whitelisted with the identity provider
  • Role mapping requirements (e.g., advertiser, admin)

2. Configuration Steps​

  1. Register GoWit as a client

    • In the identity provider console, create a new OpenID Connect (OIDC) application.
    • Add GoWit’s redirect URI(s) to the application’s whitelist. Typical format: 
      https://<gowit-domain>/auth/callback
    • Retrieve the Client ID and Client Secret generated for this application.

  2. Configure GoWit with OpenID settings

    • In GoWit’s configuration (ENV or config file), set: 
      OPENID_DISCOVERY_URL=<provider_discovery_url>
      OPENID_CLIENT_ID=<client_id>
      OPENID_CLIENT_SECRET=<client_secret>
      OPENID_REDIRECT_URI=<gowit_redirect_uri>
    • Ensure secure storage of the client secret (e.g., environment variables or a secrets manager).

  3. Role Mapping

    • Define how marketplace roles (e.g., advertiser, admin) map to GoWit roles.
    • If the identity provider includes role claims, configure GoWit to parse the relevant claim (e.g., roles, groups).
    • Example: 
      {
        "roles": ["advertiser", "admin"]
      }
      Ensure GoWit grants permissions accordingly.

  4. Handle discovery and tokens

    • Use the discovery URL to load the provider’s configuration (authorization endpoint, token endpoint, JWKS, etc.).
    • Implement the authorization code flow:
      1. Redirect users to the provider’s authorization endpoint with required parameters (client_id, redirect_uri, scope, state).
      2. After authentication, handle the callback to exchange the authorization code for an ID token and access token at the token endpoint.
      3. Validate the ID token signature and claims using the provider’s JWKS.

3. Testing the Integration​

  1. Start GoWit with the configured OpenID settings.
  2. Navigate to the login route that initiates the OpenID flow.
  3. Log in using marketplace credentials.
  4. Verify that:
    • The user is redirected back to GoWit successfully.
    • Appropriate roles are assigned based on the identity provider’s claims.
    • Restricted endpoints respect the mapped roles.

4. Troubleshooting​

  • Invalid Redirect URI: Ensure the exact URI is registered with the identity provider.
  • Token Signature Errors: Confirm the discovery endpoint is correct and that GoWit retrieves and caches the provider’s JWKS properly.
  • Incorrect Role Mappings: Check claim names and value formats; confirm the identity provider is sending the roles claim as expected.

By following these steps, developers can integrate GoWit with an external OpenID-compliant identity provider to support federated login scenarios.