A member who is already signed in to your app can open the Lillia health experience instantly: no second password, no sign-up form, no duplicate account. The first time a member opens Lillia, their Lillia account is created from the details your app already holds. Every later visit lands straight on their Lillia home screen.
The integration uses standard OpenID Connect (OIDC) identity federation. Your organisation remains the source of truth for who the member is. Lillia owns what the member does inside the health experience. Neither side stores the other's passwords, and neither sees the other's session credentials. This integration is in production with a partner today.
What the member sees
Already signed in to your app (silent, zero taps). The member taps your entry point to Lillia. Your app passes the member's identity in the background. Lillia opens, signed in. On the first visit Lillia asks three short set-up questions to personalise the member's dashboard; your app does not need to supply these.
Not yet signed in to your app (one login). Lillia shows a short landing screen with a Continue action. The tap hands the login back to your app, so the member signs in with your login: password, one-time code, biometrics, whatever you use today. Lillia never sees these credentials. The member returns to Lillia signed in.
Who does what
| Your organisation | Lillia |
|---|---|
| Authenticates the member with your existing login | Operates the identity broker that federates to your identity provider |
| Opens Lillia from your app, through the entry link, the token hand-off, or both | Creates the member's Lillia account on first sign-in and links it to your identity |
| Operates the OIDC identity provider that Lillia federates to | Issues Lillia's own short-lived tokens for use inside Lillia |
| Returns a standard ID token with a stable subject and the agreed claims | All health-domain authorisation, preferences, application data and audit logging |
| Enforces eligibility: only entitled members reach Lillia |
How it works
The integration is the standard OIDC authorisation-code flow, with your identity provider upstream and Lillia as the relying party. The token exchange runs on Lillia's servers through a confidential client, so the Lillia screen inside your app never holds an OIDC secret or one of your tokens.
- The member opens Lillia from your app. A member with an active Lillia session goes straight to their home screen.
- Token hand-off: your app posts the member's ID token to Lillia's hand-off endpoint. Lillia verifies it against your published signing keys (signature, issuer, expiry) and returns a one-shot ticket that the Lillia screen exchanges for a session. Silent, no browser round-trip.
- Browser hand-off: without a token, Lillia redirects the member to your sign-in through the registered OIDC client. Your identity provider authenticates the member and returns an authorisation code to Lillia's registered redirect address, which Lillia's servers exchange confidentially.
- Lillia validates your ID token and issues its own session. Your token never leaves the federation boundary and is not stored. On a first sign-in Lillia creates and links the member's account from the claims.
- The member lands on their Lillia home screen inside your app.
Members of a native app can also use an in-app login bridge: when a not-yet-signed-in member taps Continue on the Lillia landing screen, Lillia calls a handler in your app that opens your native sign-in. Your app confirms it took over, and Lillia waits for the member to return. The exact handler contract is agreed with your app team during set-up.
What your organisation provides
| # | Item | Notes |
|---|---|---|
| 1 | OIDC discovery URL | https://<your-idp-domain>/.well-known/openid-configuration preferred; otherwise the authorisation, token and userinfo endpoints |
| 2 | JWKS URL | Your public signing keys. Tokens must be signed RS256 or stronger. Key rotation is honoured automatically. |
| 3 | A confidential OIDC client for Lillia | Grant authorization_code, scopes openid profile email phone; allow-list Lillia's redirect address, which we give you per environment. Send the client secret through a secure channel, never by email. |
| 4 | Your organisation identifier claim | The claim name that carries your tenant or organisation id, and its value. No mapping file is needed. |
| 5 | A real sample ID token | To confirm which claims it emits (see the claims contract below) |
| 6 | Eligibility rule | Either issue a token only to entitled members, or include a status claim such as policy_active: true for Lillia to enforce |
| 7 | One verification member account | For joint validation in Staging, then one in Production before opening to all members |
| 8 | How your app opens Lillia | Entry link, token hand-off, or both; and whether your app implements the in-app login bridge |
Environment coordinates (your entry link, the redirect address to allow-list and the hand-off endpoint) are given in a short environment handover for Staging and again for Production.
ID-token claims contract
| Claim | Requirement | Purpose |
|---|---|---|
sub |
Required | Stable unique member id |
| Your organisation claim (item 4) | Required | Binds the member to your organisation on Lillia |
email, email_verified |
Recommended | Contact and account linking |
given_name, family_name |
Recommended | The member's profile |
phone_number |
Recommended | E.164 format |
locale |
Optional | Language for the member's experience |
Only sub and your organisation claim are needed for the federation to work. The rest save the member from re-entering details you already hold. Lillia does not need medical history or any health data; that is generated and held inside Lillia.
Technical constraints
- Transport: TLS 1.2 or higher on all endpoints.
- Signing: ID tokens signed RS256 or stronger; HS256 is rejected.
- Flow: OIDC
authorization_code; PKCE (S256) supported if enabled on your client. - Secret handling: client secret exchanged out of band through a secure channel.
- Sign-out: local sign-out only in the first release; federated (back-channel) logout can be added later if you publish the endpoint.
Security and data handling
The ID token is used only at the point of federation and is not stored. Once the member is identified, Lillia issues and manages its own short-lived tokens. A member's Lillia account is created on first sign-in and linked to your identity, so every later sign-in resolves to the same account and no duplicates are created. Keeping the two sides in step needs nothing from you: no admin console, no user import, no batch job.
Every sign-in is written to Lillia's audit log. Your members' data stays within your organisation's tenant in the region agreed for your contract, and health data generated inside Lillia is held under Lillia's residency and retention rules. It is not sent back to your organisation unless a data-sharing arrangement is agreed separately.
Validation and go-live
Once the items above are in place, Lillia and your team run these cases together, first in Staging, then in Production with the verification member:
- First sign-in of a new member: account created, home screen opens.
- Returning member: straight to the home screen, no duplicate account.
- Member already signed in to your app: silent sign-on, no landing screen.
- Member not signed in: landing screen, your login, return signed in.
- Ineligible member: refused, with a clear message.
- Expired or tampered token: refused.
Sign-off from both sides closes the environment. Production is opened to all members only after the Production verification passes.
Getting started
Ask your Lillia account contact for the Staging environment handover. Items 1 to 8 above are what we need from you to begin.