Authentication & Authorization

Precept relies on a "bring your own IdP" model — the only requirement is that your IdP supports OAuth 2.0 / OpenID Connect. Any OIDC-compliant provider will work, including (but not limited to):

• Auth0 / Okta
• Amazon Cognito
• Google Identity Platform
• Microsoft Entra ID
• Keycloak
• ORY Hydra

Configuring Your IdP

1. Register Precept as an Application

In your IdP, create a new Single Page Application (SPA) registration with the following settings:

Setting	Value
Application type	Single Page Application (SPA)
Allowed callback URL	https://<your-precept-host>/
Allowed logout URL	https://<your-precept-host>/
Allowed grant types	Authorization Code (with PKCE)

The UI uses the Authorization Code flow with PKCE — no client secret is needed.

2. Register an API / Resource Server

Create an API (or "resource server") entry in your IdP to represent the Precept backend. The identifier you choose here becomes the audience value in Precept's configuration.

For example, you might use https://precept.example.com/api as the identifier.

3. Configure Precept

Point Precept at your IdP by setting the http.auth.* server options. The three required options are:

• http.auth.issuer-base-url — your IdP's issuer URL (must expose /.well-known/openid-configuration)
• http.auth.audience — the API identifier registered in your IdP
• http.auth.ui.client-id — the OAuth 2.0 client ID for the Precept UI

See the Server Options reference for the full list of http.auth.* options, including optional settings for authority override, login query parameters, and query parameter whitelisting.

Example Configuration

# Required
PRECEPT_HTTP_AUTH_ISSUER_BASE_URL=https://example.us.auth0.com/
PRECEPT_HTTP_AUTH_AUDIENCE=https://precept.example.com/api
PRECEPT_HTTP_AUTH_UI_CLIENT_ID=abc123def456

# Optional — pass the audience to the IdP - required by Auth0 during login
PRECEPT_HTTP_AUTH_UI_QUERY_PARAMS='{"audience":"https://precept.example.com/api"}'

# Optional — allow the "connection" param to be set via URL
PRECEPT_HTTP_AUTH_UI_QUERY_PARAMS_WHITELIST=connection

Provider-Specific Notes

Auth0 / Okta

Auth0 requires the audience parameter at login time to issue an access token. Set PRECEPT_HTTP_AUTH_UI_QUERY_PARAMS to include it:

PRECEPT_HTTP_AUTH_UI_QUERY_PARAMS='{"audience":"https://precept.example.com/api"}'

If you use Auth0 Organizations or enterprise connections, whitelist the relevant param so it can be passed dynamically:

PRECEPT_HTTP_AUTH_UI_QUERY_PARAMS_WHITELIST=connection

Keycloak

Set the issuer base URL to your realm endpoint:

PRECEPT_HTTP_AUTH_ISSUER_BASE_URL=https://keycloak.example.com/realms/precept

Microsoft Entra ID

Use the v2.0 endpoint as the issuer:

PRECEPT_HTTP_AUTH_ISSUER_BASE_URL=https://login.microsoftonline.com/<tenant-id>/v2.0

Authorization & Policies

Precept uses a permission-based authorization model via custom JWT claims. Your IdP can embed a https://precept.sh/policy claim in the access token containing an array of permission strings.

Available Permissions

Permission	Description
config.global.write	Modify global configuration settings for any PDM
pdm.create	Upload and activate new PDMs
pdm.delete	Remove existing PDMs and their configuration

Policies are for administering the Precept server and adding & removing integrations. With no policy claims, tokens authorize end-consumer usage of the platform, enabling usage of API calls to any integration which either:

• A user has individually authenticated to, or
• An admin has configured with global or org-level credentials

Setting Up Policies

To assign policies, configure your IdP to inject the https://precept.sh/policy claim into access tokens based on user roles or group membership. See the Auth0 tutorial for a step-by-step example using Auth0 Actions.

The claim should be an array of permission strings:

{
  "https://precept.sh/policy": [
    "config.global.write",
    "pdm.create",
    "pdm.delete"
  ]
}

OIDC Scopes

The UI requests the following OIDC scopes during login:

• openid — required for OIDC
• profile — user display name
• email — user email address

Ensure these scopes are enabled for your application in your IdP.