¶ OpenID Connect (OIDC)
BillRun supports authentication via external Identity Providers (IdP) using industry-standard protocols. This allows organizations to integrate BillRun with their existing SSO, IAM, or federation infrastructure. This feature available exclusively in the BillRun Enterprise Edition.
The first supported protocol is OpenID Connect (OIDC). Additional protocols may be added in the future.
¶ Overview
Integrating BillRun with an external Identity Provider requires two main steps:
- Configure the authentication provider in BillRun
- Provide the necessary configuration details to the client’s Identity Provider
¶ BillRun Configuration
Authentication providers are configured under config.auth.
¶ Example: OpenID Connect Configuration
Config.auth = {
"protocols": [
"oidc"
],
"oidc": [
{
"name": "temp_name",
"label": "CAS",
"issuer_url": "http://cas-mock-server:8443",
"client_id": "react-app2",
"client_secret": "react-secret2",
"scopes": ["openid", "profile", "billrun", "roles"],
"roles_path": "billrun_roles.billing"
}
]
}¶ Configuration Fields
¶ Common Fields
| Field | Description |
| protocols | List of authentication protocols enabled for the project. A protocol must be listed here for it to be active and visible in the UI. |
¶ OIDC Provider Configuration
Each entry in the oidc array represents a single OpenID Connect provider.
| Field | Description |
| name | Unique identifier for the provider configuration. Also used as part of the OIDC redirect URL. |
| label | Display name shown on the BillRun login screen (for example, on the login button). |
| issuer_url | Base URL of the Identity Provider (OIDC issuer). |
| client_id | Client identifier registered with the Identity Provider. |
| client_secret | Client secret used by BillRun to authenticate with the Identity Provider. |
| scopes | (Optional) An array of strings defining the specific OIDC scopes. Defaults to ["openid", “profile”, “billrun”] if omitted. |
| roles_path | (Optional) The path used to extract the user's billing roles. defaults to billrun_roles.billing if omitted. |
Note: The login button will only be displayed if the relevant protocol (e.g. oidc) is listed in the protocols array.
¶ Client (Identity Provider) Configuration
¶ Required Scope and Claims
BillRun extracts user roles and permissions from the ID token or UserInfo response. The exact location of these roles within the response is defined by the roles_path configuration field.
If roles_path is omitted, BillRun defaults to extracting from billrun_roles.billing.
Regardless of the configured path (e.g., whether it sits at the root or is nested under a custom path), the Identity Provider must return the data containing this exact nested structure:
{
"billrun_roles": {
"crm": {
"crm_roles": ["role_1", "role_2"],
"crm_security_groups": ["sg_1", "sg_2"],
"crm_is_admin": 1
},
"billing": ["read", "write", "admin"]
}
}Role mapping notes:
- crm_roles – CRM-level roles assigned to the user
- crm_security_groups – CRM security groups
- crm_is_admin – Indicates administrative access (1 = admin, 0 = non-admin)
- billing – Billing module permissions
Different authentication protocols may require different role-mapping mechanisms.
¶ Redirect URL Configuration
For OIDC, the client’s Identity Provider must allow the following redirect URL:
https://<billrun-host>/auth/login?protocol=oidc&provider=<provider_name>¶ Parameters
| Parameter | Description |
| protocol | Must match the protocol name (e.g. oidc). |
| provider | Must match the name field defined in the BillRun configuration. |
Example: https://billrun.host/auth/login?protocol=oidc&provider=keycloak
¶ Notes on Other Protocols
Additional authentication protocols may require:
- Different configuration fields
- Alternative role/permission mapping strategies
- Different redirect URL formats
- Refer to the relevant protocol documentation when enabled.