> For the complete documentation index, see [llms.txt](https://docs.helvia.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.helvia.ai/security/end-user-authentication.md). # End-User Authentication End-user authentication is how an agent verifies who someone is, during a conversation. Helvia supports two paths: validate a token the embedding site already supplies, or prompt the user to sign in mid-conversation. Either way, the verified claims become workflow inputs you can use to personalize answers, gate sensitive actions, or route conditionally. {% hint style="info" %} **Advanced feature:** End-user authentication is one of the platform's most powerful capabilities. See the [Key Terms](#key-terms) for any unfamiliar vocabulary. {% endhint %} ### How Authentication Works Authentication is how the platform verifies who the end user actually is. Once verified, the user's name, email, and other claims become variables the workflow can read for the rest of the session. Helvia supports two modes for authenticating end users. The platform picks between them automatically based on whether a valid pre-auth token arrives with the conversation. ```mermaid flowchart TD A[Agent reaches an
authentication step] --> B{Pre-auth token
attached?} B -- Yes --> C[Validate token
against configured
providers] B -- No --> D[Show sign-in button] D --> E[User signs in with
identity provider] E --> F[Resume conversation
at the next node] C --> G([User's identity
attached to session]) F --> G classDef brand fill:#615DEC,stroke:#615DEC,color:#fff class A,G brand ``` A few platform behaviors keep the authentication experience smooth at runtime.
TitleDescription

:circle-arrow-right:

Auto-Resume

The conversation picks up at the exact node once the user completes the sign-in

:arrows-rotate:

Automatic Token Refresh (Supported)

Expired tokens refresh in the background so long sessions never re-prompt the user

:id-card:

Identity in the Workflow

Verified claims become Auth.* variables that any node can read

:layer-group:

Per-Host Validation

Add a separate token provider for each embedding context, validated independently
{% hint style="warning" %} **Channel availability:** * The pre-authenticated path is available only on [Webchat](/deploy/webchat.md) * Interactive sign-in works across every channel that can render a button {% endhint %} ### Prerequisites The two modes have different prerequisites. Confirm the right pieces are in place before enabling either on a live agent. {% columns %} {% column %} #### Pre-Authenticated Tokens No Workspace integration needed. The embedding site must already authenticate the user against an external identity provider, then [deliver the token](/deploy/webchat.md#user-pre-authentication) to Webchat via `setAuthToken` or `customData`. {% endcolumn %} {% column %} #### Interactive Sign-In This mode requires an [OpenID integration](/administration/integrations.md#sso-1) to authenticate users with your identity provider. Set up the integration in **Workspace > Integrations**. {% endcolumn %} {% endcolumns %} ### Configure Authentication for an Agent Authentication is configured per agent under **Designer > Security**. The page has two independent sections: * pre-authenticated tokens * interactive OIDC sign-in Configure at least one for the agent to authenticate users. Both can run side by side if your deployment needs them.
{% stepper %} {% step %} #### Enable OIDC Sign-In (Optional) Toggle **OIDC Authentication** on and pick an integration. Adjust the claims and email-verification options as needed.
OIDC Authentication configuration * **OIDC Integration:** The Workspace OpenID integration used for interactive sign-in. Configured in **Workspace > Integrations**. * **Additional Claims:** Comma-separated list of extra claim names to extract from the ID token, beyond the standard ones. Example: `preferred_username, tid, groups`. * **Require email verification:** When enabled, sign-ins are rejected unless the identity provider returns `email_verified: true`
{% endstep %} {% step %} #### Add a Pre-Auth Token Provider (Optional) Skip if the agent will never be embedded in a page that already authenticates the user. Toggle **Pre-Authenticated Token Providers** on, then select **Add Provider** for each distinct embedding context the agent serves.
Pre-Authenticated Token Provider configuration * **Provider name:** A label for the provider, used only inside the platform for identification * **Audience (aud):** The `aud` claim the platform expects in incoming tokens. Tokens whose `aud` does not match any configured provider are rejected. * **JWKS URI:** The URL where the identity provider publishes its JSON Web Key Set. Used to verify the token signature. * **Refresh Token Endpoint:** Optional. The endpoint the platform calls to refresh expired tokens during a session.
{% endstep %} {% step %} #### Save and Verify Select **Save** to commit the configuration. With at least one mode enabled, you can now use the authentication nodes in your workflows to authenticate end users. {% endstep %} {% endstepper %} ### Using Identity in Workflows Once a user is authenticated, their claims are exposed as workflow [session variables](/build/variables.md#session-variables-reference) under `Auth.*` and stay available for the rest of the session. Reference them in conditions, prompts, API calls, or any node that reads workflow variables, the same way you would reference any other user attribute. Three workflow nodes work directly with this state and are what most workflows use to gate access:
TitleDescription

:lock:

Authenticate User

Triggers authentication for the current user: pre-auth token check first, sign-in button as fallback

:shield-check:

Is Authenticated

Checks the current session and routes to Success or Error, refreshing expired tokens automatically

:arrow-right-from-arc:

Logout

Clears the authentication session, with an optional sign-out from the identity provider
### The End-User Experience The user-facing journey depends on which authentication path the agent takes: {% columns %} {% column %} #### Pre-Authenticated Tokens The conversation starts already authenticated. The user is never prompted to sign in or offered a sign-out option. {% endcolumn %} {% column %} #### Interactive Sign-In The agent shows a sign-in button the moment the workflow reaches an authentication step. After a successful sign-in, a green shield appears in the sendbox bottom bar. Selecting it lets the user sign out. {% endcolumn %} {% endcolumns %} ### Key Terms | Term | Meaning | | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **OIDC** | OpenID Connect, an identity-layer protocol built on OAuth 2.0. The standard the platform uses for interactive sign-in. | | **OpenID integration** | A Workspace-level configuration that captures an identity provider's discovery URL and client credentials. | | **Identity provider** | The external system that authenticates users and issues tokens, for example Microsoft Entra ID, Google, Okta, or Keycloak | | **Claim** | A single piece of identity information returned by the identity provider, such as `name`, `email`, or `groups`. Multiple claims together describe the user. | | **Token** | A signed string the identity provider issues to represent an authenticated user. The platform verifies the signature before trusting any claims inside. | | **Pre-authenticated token** | A token the embedding site already holds when the conversation starts, because the user is signed in upstream. The platform validates it without prompting for a fresh sign-in. | | **Audience (`aud`)** | A claim inside the token that names who the token is meant for. The platform only accepts tokens whose `aud` matches a configured provider. | | **JWKS** | JSON Web Key Set, the public keys the identity provider publishes so token signatures can be verified | | **Embedding site** | The web page or host context where the agent is loaded through webchat. Examples: a SharePoint web part, an intranet portal, a public landing page. | ### Best Practices * **Prefer pre-authenticated tokens when the host already authenticates:** Skipping the sign-in button removes a step from the user journey and keeps the experience inside the embedding page's session * **Use the Is Authenticated node for mid-flow re-checks:** It is cheaper than re-prompting and handles token refresh transparently * **Request only the claims you use:** Add to **Additional Claims** what the workflow actually reads, since extras clutter your variables and make\ audits harder * **Authenticate as late as possible:** Place the Authenticate User node just before the first step that needs identity, so unauthenticated users can still reach steps that don't require it * **Add a provider per embedding context:** When the same agent runs in two host sites with different audiences, configure two pre-auth providers rather than one broad rule {% hint style="success" %} You can now authenticate end users mid-conversation, validate tokens from embedding sites, and use the resulting claims to personalize and adjust any step of the workflow. {% endhint %} --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.helvia.ai/security/end-user-authentication.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.