Airgentic Help
This page explains how the secure authentication flow works in plain language. You don't need to understand all of this to set up a secure service, but it can be helpful as a reference, especially if you're discussing the integration with your security or IT team.
When you set up a secure service, the Airgentic widget works with your existing identity provider (e.g. Microsoft Entra ID) to verify who the user is before allowing access to chat and search. The key principles are:
User opens the page that contains the Airgentic widget (e.g. your intranet homepage).
Widget checks for a session. If the user already has a valid session from a recent sign-in, the widget is immediately ready to use. If not, the flow continues.
Redirect to sign-in. The widget redirects the user to your identity provider's sign-in page (e.g. the Microsoft login screen). This is the same sign-in experience your users already know from other organisational apps.
User signs in. The user enters their credentials on your identity provider's page. Airgentic is not involved in this step.
Redirect back. After successful sign-in, the identity provider redirects the user back to your site (the callback URL) with a one-time authorisation code in the URL.
Code exchange. The widget sends this code to the Airgentic backend. The backend contacts your identity provider directly to exchange the code for proof of the user's identity, using the client secret you provided along with a PKCE proof to ensure the exchange is secure.
Authorisation check. The backend checks the user's identity against your authorisation rules (email domain, individual addresses, or group membership). If the user is allowed, the backend issues a short-lived session token.
Ready to use. The widget stores the session token and removes the temporary code from the address bar. From this point on, every chat message and search request includes the session token, and the Airgentic server only processes requests with a valid token.
If the session token expires, the widget redirects the user to sign in again, repeating the same flow.
An industry standard that allows a website to delegate sign-in to an identity provider. The website redirects the user to the identity provider to sign in, and the identity provider sends back a signed token confirming the user's identity (email, name, and optionally group memberships). The website never handles the user's password.
The system that manages your user accounts and performs sign-in — for example, Microsoft Entra ID, Okta, or Google Workspace. Your organisation already uses it for other applications; Airgentic reuses it so your users don't need a separate account or password.
A security measure for browser-based sign-in flows. When the widget starts the sign-in process, it generates a random secret and sends a derived "challenge" to the identity provider. When exchanging the authorisation code for a token, the widget proves it has the original secret. This ensures that even if someone intercepts the authorisation code, they cannot use it to complete the sign-in.
The URL on your site where the identity provider sends the user after sign-in. It temporarily contains the one-time authorisation code. This URL must match exactly in three places: your identity provider's app registration, the Airgentic service configuration, and the data-auth-redirect-uri attribute in your embed code.
A short-lived token issued by the Airgentic backend after a successful sign-in and authorisation check. It contains information like the user's identity, the service they're accessing, and an expiry time. The widget includes this token with every request, and the Airgentic server validates it before processing any chat or search query.
The list of website origins (e.g. https://intranet.yourorg.gov.au) from which the widget is permitted to operate. The Airgentic server rejects requests from origins not in this list, preventing other websites from embedding or using your widget.