Skip Navigation Links

OIDC Public Client Implementation Guide

Guide how to connect client side integrations for end users (custom UI) to Flip using OIDC

This guide helps you implement OpenID Connect (OIDC) authentication for browser-based integrations that connect to the Flip platform, for example using menu items in the Flip navigation.

To integrate backend services directly, please refer to Service-2-Service API Authentication

Getting an OIDC client for your integration

Approach your Customer Success contact to obtain a public OIDC client, which comes without a client secret. Public OIDC clients work best for browser-based integrations where the web app communicates directly with the Flip Identity Provider.

Your Customer Success contact will need the following information:

  • Name and short description of the integration to determine a good client id and ensure the OIDC client can be properly identified
  • Base URL for valid redirects into the integration, needs to be in the form https://{domain}/{segment}
  • Optional: URL to redirect to after a logout - will default to the base URL if not provided

Once the client is registered, your CS contact will provide you with:

  • a client id
  • the idp-host url
  • your organisation ID

Identity Provider Endpoints

Your application needs to interact with several endpoints. These follow standard OIDC patterns. If you are using an OIDC library, you typically only need to configure the Base URL as the authority — the library will discover all other endpoints automatically via the Discovery Document.

  • Base URL
    https://{idp-host}/realms/{organisation-id} |
  • Discovery Document (use this to auto-configure)
    https://{idp-host}/realms/{organisation-id}/.well-known/openid-configuration |
  • Authorization Endpoint
    https://{idp-host}/realms/{organisation-id}/protocol/openid-connect/auth |
  • Token Endpoint
    https://{idp-host}/realms/{organisation-id}/protocol/openid-connect/token |
  • UserInfo Endpoint
    https://{idp-host}/realms/{organisation-id}/protocol/openid-connect/userinfo |
  • JWKS Endpoint (for token validation)
    https://{idp-host}/realms/{organisation-id}/protocol/openid-connect/certs |
  • Logout Endpoint
    https://{idp-host}/realms/{organisation-id}/protocol/openid-connect/logout |

Replace {idp-host} and {organisation-id} with the values provided by your CS contact.

Authentication Flow

Use the Authorization Code Flow with PKCE (Proof Key for Code Exchange). This is the most secure flow for browser-based applications. When configuring your OIDC library, set the response type to code and enable PKCE. Do not use the Implicit Flow.

Scopes

When initiating the authorization request, include openid profile email as scopes.

Your OIDC client is pre-configured with the following default scopes, which are always included in tokens: profile, roles, email. This means user profile information, assigned roles, and email address are available without additional scope configuration, but your library may require to list scopes explicitly.

Be aware that depending on your organisation setup, not all users might have an email address, or it may not be a company email address.

Note: Do not request offline_access unless you know what you are doing, as this significantly increases the security exposure of your app. Offline refresh tokens have a significantly higher lifetime. You will still receive a normal refresh token.

Token Claims

The ID token and UserInfo endpoint response include standard OIDC claims such as sub, email, name, and preferred_username, external_id, as well as a roles claim containing the user's assigned global roles (e.g. no user group roles). Use sub as the stable user identifier. Use the UserInfo endpoint as the canonical source for available user information.

Logout

To log a user out, redirect them to the Logout Endpoint with the following query parameters:

  • id_token_hint — the ID token obtained during authentication. This identifies the session to terminate.
  • post_logout_redirect_uri — where to send the user after logout. Must match one of your registered redirect URIs.

Most OIDC libraries provide a signoutRedirect() method (or equivalent) that handles this automatically.

Implementation Recommendations

Use Established Libraries (Strongly Recommended)

Important: Do not implement OIDC flows manually. The protocol involves cryptographic operations, security validations, and edge cases that are easy to get wrong.

Use well-maintained, audited libraries, such as:

  • oidc-client-ts - Modern library for browser-based applications (works with any framework, including React)
  • Passport - Express-compatible authentication middleware for Node.js
  • react-oidc-context - React-specific hooks and components (built on oidc-client-ts)
  • angular-oauth2-oidc - For Angular applications

We recommend to use general purpose oidc libraries and avoid anything keycloak specific.

What Libraries Handle for You

Good OIDC libraries automatically:

  • Generate and validate PKCE challenges
  • Verify JWT signatures and token claims
  • Refresh expired access tokens
  • Manage session state
  • Implement security best practices
  • Fetch and cache endpoint URLs from the discovery document

Minimal Configuration Example

Using oidc-client-ts:

Replace the placeholder values with the credentials provided by your CS contact.


Token Refresh
Your OIDC client is configured to issue refresh tokens. Most libraries handle token refresh automatically in the background. Ensure your library is configured for silent renewal (e.g., automaticSilentRenew: true in oidc-client-ts).
Access tokens are intentionally short-lived. When a token expires, the library will use the refresh token to obtain a new access token without requiring user interaction.


Security Best Practices
When implementing your public client:
    

  • Use an established OIDC library - Don't implement the protocol manually
    • 

  • Enable PKCE - Usually default in modern libraries
    • 

  • Use HTTPS - For all communications
    • 

  • Store tokens in memory only - See Token Storage below
    • 

  • Implement CSP headers - Content Security Policy for additional protection
    • 

  • Use short-lived tokens - Rely on automatic token refresh
    • 

  • Clear tokens on logout - Ensure proper cleanup
    • 

  • Handle errors gracefully - Provide clear feedback to users
    • 



Token Storage


Important: Do not store tokens in browser storage (localStorage or sessionStorage) — both are vulnerable to XSS attacks.


Recommended approach: Use in-memory storage. Tokens are lost on page refresh, but since Flip maintains the user's Identity Provider session, re-authentication is typically seamless and does not require the user to re-enter credentials.
If your library requires explicit storage configuration, use its built-in in-memory storage mechanism.
Note that with in-memory storage, each browser tab maintains its own independent session. Opening the application in a new tab or refreshing the page will trigger a seamless re-authentication via the existing Identity Provider session, which may briefly show a loading state before the user is fully authenticated again.


CORS
CORS is configured automatically for your registered redirect URIs.
This does not cover localhost origins, so direct browser-to-IdP requests will fail during local development.
Use a local reverse proxy (e.g., via your bundler's proxy configuration) to forward authentication requests through your own origin instead
or request a dedicated local development client.


Testing Your Implementation
    

  1. Test the complete login flow from start to finish
    2. 

  2. Verify token refresh works automatically
    3. 

  3. Test logout and confirm tokens are cleared
    4. 

  4. Verify API calls include valid Bearer tokens
    5. 

  5. Test handling of expired tokens
    6. 

  6. Check error scenarios (network failures, declined consent)
    7. 



Troubleshooting
If you encounter issues:
    

  1. Check browser console for errors and network requests
    2. 

  2. Ensure you're using the correct organisation-id and client ID
    3. 

  3. Verify redirect URIs match your registered configuration - use the discovery document endpoint (.well-known/openid-configuration) to verify
    4. 

  4. Review your library's documentation and examples
    5. 

  5. Contact your CS contact for configuration assistance
    6. 



Additional Resources
    

  • Consult your OIDC library's documentation for specific implementation details
    • 

  • Review OIDC and OAuth 2.0 documentation and specifications for deeper understanding
    • 

For questions or assistance, please contact your Customer Success representative.