Pulse And OpenIDConnect (OIDC) User Authentication

Introduction#

Pulse is the identity provider for every Timebase component, and it keeps its own user accounts. It can also hand the sign-in itself to an outside identity provider that speaks OpenID Connect, so that people use the account they already have with Microsoft Entra ID, Google, Okta, Auth0 or a similar service, and Pulse stores no password for them.

Each provider you configure appears as a Sign in with ... button on the Pulse sign-in page, beside the username and password form. A person who signs in that way for the first time is asked to complete a short registration, after which their Pulse account is linked to that external identity. From then on the button signs them straight in.

The IdentityProviders section#

IdentityProviders is a list. Each entry describes one provider:

"IdentityProviders": [
  {
    "Type": "Timebase.Pulse.IdentityProvider.OpenIDConnect.Plugin",
    "DisplayName": "Entra ID",
    "Scheme": "entra",
    "LogoUri": "https://your-pulse-host:4542/logos/entra.svg",
    "Options": {
      "ClientId": "<application (client) id>",
      "ClientSecret": "<client secret value>",
      "Authority": "https://login.microsoftonline.com/<tenant id>/v2.0",
      "Scopes": [ "email", "profile" ],
      "ClaimsToMap": {
        "Name": "preferred_username",
        "Email": "email",
        "GivenName": "given_name",
        "Surname": "family_name"
      }
    }
  }
]

Inside Options:

Options accepts the other settings of the standard OpenID Connect client as well, for example GetClaimsFromUserInfoEndpoint for a provider that puts claims in the user-info response rather than the ID token. You will rarely need them.

What the provider must be told#

Every provider asks for the same three things when you register an application with it:

1. The application type is a web application that keeps a client secret. Choose the confidential or server-side option, not a single-page or mobile application.
2. The redirect URI is Pulse's public address plus /signin-<scheme>, for example https://pulse.example.com:4542/signin-entra. The address is the one in Pulse's Auth:PublicAddress setting, which is the address people type into their browser; a provider will refuse a redirect to any other address. The path is lower case even if you wrote the scheme with capitals.
3. The scopes openid, email and profile, so the provider releases a name and an email address.

Pulse uses the authorization code flow. You do not need to enable implicit grants or ID tokens on the application registration.

Claims#

A claim is a named value the provider releases about the person: their subject identifier, email address, display name and so on. ClaimsToMap tells Pulse which of them fills which field of the Pulse user. The keys are fixed:

A key not listed in ClaimsToMap takes the standard OpenID Connect claim of the same meaning when the provider sends one, so a provider that follows the standard needs little or no mapping. Map explicitly when the provider uses its own names, as Entra ID does for the username.

What happens when a person signs in#

First sign-in. The person clicks the provider's button, signs in there, and is sent back to Pulse. Pulse looks for an account already linked to that external identity. There is none, so it shows a registration page pre-filled from the claims: a suggested username, first name and last name, all editable. Submitting it creates a new Pulse account with no password and no roles, links it to the external identity, and signs the person in. The account is a standard user until an administrator makes it one; see User Management With Timebase Pulse.

Every sign-in after that. The button signs them straight in, with no further prompt from Pulse.

A username that already exists. If the suggested username is already taken, the registration is refused and the person is told to sign in to the existing account with its password and link the provider from their own user page instead. Nothing is merged automatically, and nothing lets a fresh external identity take over an account that exists.

Linking a second identity. A signed-in person opens their own user page and, under External logins, links any configured provider they do not already have. The link acts only on the account they are signed in to. An identity that is already linked to a different Pulse account is refused, with a message saying which to unlink first. Only the account owner can link or unlink; an administrator sees the list on everyone's page but changes it on their own account only.

Unlinking. An account that has a password can unlink every external login. An account with no password cannot unlink its last one, because that would leave no way to sign in: set a password first, then unlink.

Locked accounts. A locked account is refused at the provider's callback the same way it is at the password form, and the sign-in page says so.

Provider walkthroughs#

Microsoft Entra ID#

1. In the Azure portal, open Microsoft Entra ID and then App registrations, and choose New registration.
2. Give it a name such as Timebase Pulse. Under Supported account types, choose single tenant unless you mean to accept accounts from other directories.
3. Under Redirect URI, choose the Web platform and enter https://<your pulse address>/signin-entra. Register.
4. From the Overview page, copy the Application (client) ID into ClientId and the Directory (tenant) ID into the authority: https://login.microsoftonline.com/<tenant id>/v2.0. Use common in place of the tenant id for a multi-tenant registration.
5. Under Certificates & secrets, create a client secret and copy its Value at once into ClientSecret; it is shown only then.
6. Under API permissions, make sure the delegated Microsoft Graph permissions openid, email and profile are present, and grant admin consent if your tenant requires it.
7. Under Token configuration, add the optional ID token claims email and preferred_username.

Entra ID puts the sign-in name in preferred_username, so map Name to it as in the example above. Nothing on the Authentication page needs to be enabled: the authorization code flow works with the defaults.

Google#

1. In the Google Cloud console, create or choose a project, then open APIs & Services and OAuth consent screen. Choose Internal if everyone who signs in belongs to your Google Workspace, otherwise External. Add the scopes openid, .../auth/userinfo.email and .../auth/userinfo.profile.
2. Under Credentials, create an OAuth client ID of type Web application and add https://<your pulse address>/signin-google under Authorized redirect URIs.
3. Copy the client ID, which ends in .apps.googleusercontent.com, into ClientId, and the client secret into ClientSecret.
4. Set Authority to https://accounts.google.com.

{
  "Type": "Timebase.Pulse.IdentityProvider.OpenIDConnect.Plugin",
  "DisplayName": "Sign in with Google",
  "Scheme": "google",
  "Options": {
    "ClientId": "<client id>.apps.googleusercontent.com",
    "ClientSecret": "<client secret>",
    "Authority": "https://accounts.google.com",
    "Scopes": [ "email", "profile" ]
  }
}

Google sends the standard claims, so no mapping is needed.

Any other provider#

Okta, Auth0, Keycloak and the rest follow the same shape. Find the provider's issuer address for Authority, register Pulse as a web application with the redirect URI above, request openid, email and profile, and check the provider's documentation for the claim it puts the preferred username in.

Troubleshooting#