Single Sign-On
Let your users reach agrirouter with the identity they already have in your solution
Single Sign-On (SSO) lets your users arrive at agrirouter carrying the identity they already hold in your solution, instead of maintaining a separate agrirouter password. Your Identity Provider (IdP) is registered as an upstream IdP in agrirouter's Keycloak, and agrirouter brokers the login.
Each partner solution is identified by a slug: a short, stable name assigned by the agrirouter team (for example, iotool). The slug appears in your redirect URLs and in the URL that starts the flow, so it is fixed once assigned.
Setting up SSO is a one-time exchange between you and the agrirouter team. Once it is in place, your solution starts the flow with a single redirect.
Setup
Setup has two halves: what is configured on your side, and what is requested from the agrirouter team. The slug is assigned by the agrirouter team, so the values below can only be finalised once the request has been processed.
Create an OAuth/OIDC client in your IdP
An OAuth/OIDC client is created in your IdP for agrirouter to broker against, configured with the following parameters. The <idp-slug> placeholder is replaced with the slug assigned to your solution.
| Parameter | Value |
|---|---|
| Redirect URL | https://auth.agrirouter.com/realms/agrirouter/broker/<idp-slug>/endpoint |
| Post Logout Redirect URL | https://auth.agrirouter.com/realms/agrirouter/broker/<idp-slug>/endpoint/logout_response |
PKCE (Proof Key for Code Exchange) should be enabled where your IdP supports it, using either the S256 method (preferred) or plain. Clients with PKCE disabled are also supported, so this does not block the integration.
Prefer S256 over plain. The plain method transmits the code verifier unhashed, which offers no protection if the authorization request is intercepted.
Send a request to the agrirouter team
The client cannot be brokered until it is registered on the agrirouter side. Write to support@agrirouter.com including:
- Display name of your solution, as it should be shown to users — for example,
DKE-Data IO-Tool. - Desired slug (short name) of your solution — for example,
iotool. The slug must be precise and must not conflict with other solutions. - Whether PKCE is required on the configured client, and with which method (
S256orplain). - How customer email addresses are confirmed in your solution, described in enough detail to be assessed. Based on this description, the agrirouter team determines whether email addresses delivered by your IdP are fully trusted, or whether they are re-verified on the agrirouter side.
The email verification decision is what determines whether your users are asked for an emailed authorization code when a new agrirouter account is created. If delivered email addresses are fully trusted, that step is skipped on the create path. Linking to an existing agrirouter account is always verified by an emailed code, regardless of this decision.
Wait for confirmation
Once the request has been processed, your IdP is registered as an upstream IdP and the slug is confirmed. The flow can then be started.
Usage
After the request has been processed, the SSO flow is initiated by calling or redirecting the user's browser to the start URL, with your assigned slug:
https://app.agrirouter.com/api/sso/start/<idp-slug>From there, the user is sent to your IdP to authenticate, and agrirouter takes over once the identity comes back.
What the user experiences
What the user is asked next depends on whether their partner identity is already linked to an agrirouter account, and whether they are already signed in. The decision tree below covers every path.
The paths reduce to three outcomes:
- Already linked. The identity is recognised and the user is logged in. If they are signed in as a different account, they are asked whether to switch to the linked one; declining leaves the existing session untouched.
- Linked to an existing account. The user confirms which agrirouter account to link, then proves ownership of that address with an emailed authorization code.
- A new account is created. The account is created from the identity delivered by your IdP. An emailed authorization code is requested first unless email addresses from your IdP are fully trusted.
In every case the user ends up logged in with their partner identity linked, and later logins skip the linking questions entirely.
Errors
On failure, the user is redirected to /sso/error?reason=.... The reason is the error reported by Keycloak, session_expired when the SSO session is unknown or has expired, or unknown_error. SSO sessions expire 10 minutes after the flow is started.