ServicePulse Authentication Configuration

ServicePulse supports authentication using OpenID Connect (OIDC) and works with any OpenID Connect compliant identity provider (Microsoft Entra ID, Okta, Auth0, Keycloak, etc.). When enabled, users must sign in with their identity provider before accessing the dashboard.

Ensure ServiceControl has been setup with authentication and TLS encryption. This is a prerequisite for ServicePulse authentication.

Configuration

Authentication in ServicePulse is configured in the primary ServiceControl instance. ServicePulse fetches authentication settings on startup from the ServiceControl API and the following settings are set:

Setting	Description
`enabled`	Enable or disable authentication
`authority`	The OIDC authority URL (identity provider)
`client_id`	The OIDC client ID registered with your identity provider
`api_scopes`	API scopes to request (space-separated or JSON array)
`audience`	The audience claim for the access token (required by some identity providers)

Identity Provider Setup

When registering ServicePulse with your identity provider, configure the following:

Setting	Value
Application type	Single Page Application (SPA)
Grant type	Authorization Code with PKCE
Redirect URI	`https://your-servicepulse-url/`
Post-logout redirect URI	`https://your-servicepulse-url/`
Silent renew URI	`https://your-servicepulse-url/silent-renew.html`

Identity Provider Guides

For step-by-step instructions on configuring specific identity providers, see:

Microsoft Entra ID

Required Scopes

ServiceControl API Access

ServicePulse requests the following OIDC scopes in addition to any API scopes configured:

openid - Required for OIDC
profile - User's name and profile information
email - User's email address
offline_access - Enables refresh tokens for silent renewal

Token Management

Storage

User tokens are stored in the browser's sessionStorage. This means:

Tokens are cleared when the browser tab is closed
Each browser tab maintains its own session
Tokens are not shared across tabs

Silent Renewal

ServicePulse automatically renews access tokens before they expire using a hidden iframe (silent-renew.html). This provides a seamless experience without requiring users to re-authenticate.

If silent renewal fails (e.g., session expired at the identity provider), users are redirected to log in again.

User Interface

When authentication is enabled and the user is signed in, the dashboard header displays:

User's name (from the name claim)
User's email (from the email claim)
A sign-out button

Troubleshooting

"Authentication required" error

This error appears when:

Authentication is enabled but no valid token exists
The token has expired and silent renewal failed
The user cancelled the login flow

Solution: Click the login button or refresh the page to initiate authentication.

Redirect loop or login failures

Common causes:

Incorrect redirect URI - Ensure the redirect URI registered with your identity provider exactly matches the ServicePulse URL (including trailing slash if present)
CORS issues - Your identity provider must allow requests from the ServicePulse origin
Clock skew - Ensure server clocks are synchronized; token validation is time-sensitive

Silent renewal fails repeatedly

This can occur when:

The identity provider session has expired
Third-party cookies are blocked (required for iframe-based renewal)
The silent-renew.html page is not accessible

Solution: Check the browser console for specific error messages. Some browsers block third-party cookies by default, which can prevent silent renewal from working.

Token not included in API requests

Verify that:

Authentication is enabled in ServiceControl
The user has completed the login flow
The token has not expired

Check the browser's Network tab to confirm the Authorization: Bearer header is present on API requests.

Security Considerations

HTTPS Required

For production deployments, always use HTTPS. OIDC tokens are sensitive credentials that should only be transmitted over encrypted connections.

Session Duration

Token lifetime is controlled by your identity provider. Consider configuring:

Access token lifetime - Short-lived (e.g., 1 hour) for security
Refresh token lifetime - Longer-lived to enable silent renewal
Session policies - Maximum session duration before re-authentication is required