Sign-in and SSO (planned)

Planned. Self-hosted deployment is not available yet. Where a step needs something the first release does not do yet, it says so.

In a self-hosted install, sign-in is yours. Provantix-managed Google sign-in does not exist there, and no Provantix account can sign in. People sign in with a password or, better, with your identity provider.

The first administrator

The installer asks you to create the first administrator at the end of the install: an email address and a password. This needs no contact with Provantix. Self sign-up is then closed:

LEDGER_SIGNUP=invite

Everyone else is added by an administrator from Members, and signs in with a code sent by email (so Email must work first).

Single sign-on with your identity provider

Your own domain means your own identity provider, so single sign-on is part of the first release, not an option. Provantix signs people in with OpenID Connect against any standards-based provider: Okta, Keycloak, Microsoft AD FS, Ping Identity, Auth0, Microsoft Entra ID, Google Workspace and others. Choose Other OpenID Connect for any provider that is not Entra or Google. What a provider must offer:

  • an issuer URL whose /.well-known/openid-configuration document is reachable from the machine;
  • the authorization code flow, with a client ID and a client secret;
  • id tokens signed with RS256 (the default in all the providers above);
  • the person's email address in the token, in the email claim, or in preferred_username or upn if the provider puts it there.

The providers named above meet these requirements in their default configuration. We confirm each against a real tenant before the first release, and the first customer's provider is tested in the pilot before go-live. Provantix does not run the provider for you: you register an application once and enter its details.

  1. In your identity provider, create an OAuth or OIDC application of type Web. Set the redirect address (also called the callback or redirect URI) to your own deployment's address followed by /api/auth/sso/callback:

    https://<your-domain>/api/auth/sso/callback
    

    <your-domain> is a placeholder for the hostname you chose for this deployment, on your own domain (for example provantix.yourcompany.com). It is never provantix.tech. Settings, Access tab, Single sign-on in your deployment shows the exact address to register, built from your public address.

    The address must match LEDGER_PUBLIC_URL exactly (see Domains and TLS). Ask for the scopes openid and email (and profile if you want display names).

  2. In Provantix, as an administrator, open Settings, Access tab, Single sign-on, choose the provider (Other OpenID Connect for Okta, Keycloak, AD FS, Ping or Auth0), and enter the issuer URL, the client ID, the client secret and the routing email domain, then switch it on. Examples of an issuer URL: Keycloak https://idp.corp.example.com/realms/corp, Okta https://corp.okta.com, AD FS https://adfs.corp.example.com/adfs.

  3. Test with a second person before you rely on it, in a private window, with an administrator still signed in.

By default only people an administrator has invited can sign in through SSO; an administrator can change that. The routing domain must be your own.

If your identity provider is on a private address

By default the platform refuses to make outbound calls to private network addresses, as protection against requests being aimed at your internal services. In your own network the identity provider is usually on one, so name it in the internal allow-list in the settings file, then restart the service:

LEDGER_INTERNAL_HOSTS=idp.corp.example.com

An entry names a host (idp.corp.example.com, or *.corp.example.com), a single IPv4 address, or an IPv4 range (10.41.0.0/16, no broader than /8); separate entries with commas. Only what you name is opened. See Alerts for the full rules. The provider's discovery document and its token and key endpoints are all fetched from the machine, so each host they name must be reachable (and listed, if private). The provider must be served over HTTPS with a certificate the machine trusts; if it uses an internal authority, add the authority to the machine's trust store.

The break-glass token

If your identity provider is down, or you are locked out, there is a break-glass token: a long random value that the deployment's settings file holds as LEDGER_ADMIN_TOKEN. It is generated on your machine and known only to you. It lets an administrator on the machine create an invitation for a new administrator. Provantix never has it and cannot use it.

  • Store it in your own secret manager, not in a chat or a ticket.
  • Rotate it by changing the value in the settings file and restarting the service.

What does not exist in a self-hosted install

  • Provantix staff accounts. No Provantix staff domain is registered, and none can be added by us.
  • Managed Google sign-in. It is part of Provantix's own identity setup.
  • The Provantix operator console. It exists only on our hosted service. Your deployment has its own administrators and no operator above them.

Sessions and sign-out

A person is signed out when their session ends or when an administrator removes them. If the licence cannot be validated for six hours, nobody can sign in until it can; see Licensing.