Documentation

Enterprise

Configure OIDC Flow

Register an OIDC application, configure the backend, and test employee sign-in.

1. Register an application

In your identity provider, create an application with these settings:

  • Application type: confidential web application.
  • Grant types: Authorization Code and Refresh Token.
  • Client authentication: client_secret_basic or client_secret_post.
  • Access tokens: signed JWTs for your API.
  • Access: assign the employees or groups allowed to use Ottex.

Redirect URI: register this endpoint using your backend’s hostname.

https://api.acme.example/auth/callback

The backend handles this callback and opens Ottex. No callback page on your company website is required.

2. Configure the backend

Set these environment variables using the values from your identity provider:

ENTERPRISE=true
AUTH_ISSUER_URL=https://identity.acme.example
AUTH_AUDIENCE=ottex-api
OIDC_CLIENT_ID=ottex-backend
OIDC_CLIENT_SECRET=replace-with-your-client-secret
OIDC_REDIRECT_URI=https://api.acme.example/auth/callback
OIDC_SCOPES="openid profile email"
  • Issuer: the exact OIDC issuer URL, including any tenant or realm path. It must publish discovery metadata and signing keys.
  • Audience: the API identifier in the access token’s aud claim. Configure the provider to issue tokens for this API; use an identifier different from the client ID.
  • Client credentials: the application’s client ID and secret. Keep the secret on the backend.
  • Redirect URI: must exactly match the registered HTTPS callback.
  • Scopes: keep openid; add API scopes and offline_access if your provider requires them.
  • Signing algorithm: RS256 by default. Set AUTH_SIGNING_ALGS if your issuer uses another supported algorithm.

Restart the backend after changing its environment.

3. Test sign-in

  • Sign in from Ottex with an assigned company account.
  • Test dictation to verify authenticated API access.
  • Check session refresh after the access token expires.

Troubleshooting

  • Redirect mismatch: compare the registered callback with OIDC_REDIRECT_URI, including scheme, host, port, and path.
  • Invalid audience: check that the token’s aud includes AUTH_AUDIENCE. This variable validates the audience; it does not request one from the provider.
  • Missing refresh token: enable refresh-token issuance. Add offline_access if required. Login fails without a refresh token.
Connect the desktop app