lfr-tunnel Cloud SSO & OIDC Setup Guide¶
This guide provides step-by-step instructions to configure Microsoft Entra ID (Azure AD), Google Cloud Identity (OAuth 2.0), and AWS IAM Identity Center (AWS SSO) as Identity Providers (IdPs) for lfr-tunneld. It also covers how to create configuration files to test these integrations locally.
What every sign-in checks (#2451). Each sign-in uses PKCE (S256) and a nonce, so a stolen authorization code or a replayed ID token is refused. You can set your identity provider to require PKCE. The provider must also assert email_verified: true, because the email address is what the gateway finds the account by. A sign-in without it gets a 403 and an audit row (user.sso_denied.unverified_email). When a sign-in fails at the provider, the user sees a generic message and the detail goes to the server log.
1. Microsoft Entra ID (Azure AD)¶
A. Entra ID App Registration Setup¶
- Log in to the Azure Portal and navigate to Microsoft Entra ID.
- Select App registrations from the left panel, and click New registration.
- Fill in the following details:
- Name:
Liferay Tunnel Gateway(or similar) - Supported account types: Select your preference (e.g., Accounts in this organizational directory only to restrict to your company domain).
- Redirect URI: Select Web and enter:
https://<your-tunnel-gateway-host>/api/auth/callback?provider=entra-id(For local testing, use:http://localhost:8000/api/auth/callback?provider=entra-id) - Click Register.
- Copy the Application (client) ID and Directory (tenant) ID from the Overview page.
- Navigate to Certificates & secrets -> Client secrets -> New client secret.
- Create a secret, copy the value immediately (it will be masked later).
B. YAML Configuration Block¶
Add the following to your server-config.yaml:
allowed_email_domains:
- yourcompany.com # Enforce login only to corporate emails
sso_providers:
- id: "entra-id"
name: "Microsoft Entra ID"
client_id: "YOUR_APPLICATION_CLIENT_ID"
client_secret: "YOUR_CLIENT_SECRET_VALUE"
issuer_url: "https://login.microsoftonline.com/YOUR_DIRECTORY_TENANT_ID/v2.0"
icon: "microsoft"
# Entra ID never sends email_verified, so without this every sign-in is refused. Set it only
# because your tenant's directory owns every address it asserts.
skip_email_verified_check: true
2. Google Cloud Identity / Google Workspace¶
A. Google Cloud Console Setup¶
- Log in to the Google Cloud Console.
- Create or select a project.
- Navigate to APIs & Services -> OAuth consent screen:
- Set User Type to Internal (to restrict logins exclusively to members of your Google Workspace domain) or External (open to any Google account).
- Complete required fields (App name, support email, developer contact).
- Navigate to Credentials -> Create Credentials -> OAuth client ID.
- Select Application type: Web application.
- Set the following details:
- Name:
Liferay Tunnel Gateway - Authorized redirect URIs:
https://<your-tunnel-gateway-host>/api/auth/callback?provider=google(For local testing, use:http://localhost:8000/api/auth/callback?provider=google) - Click Create and copy the Client ID and Client Secret.
B. YAML Configuration Block¶
Add the following to your server-config.yaml:
allowed_email_domains:
- yourworkspace-domain.com
sso_providers:
- id: "google"
name: "Google Workspace"
client_id: "YOUR_GOOGLE_CLIENT_ID.apps.googleusercontent.com"
client_secret: "YOUR_GOOGLE_CLIENT_SECRET"
issuer_url: "https://accounts.google.com"
icon: "google"
3. AWS IAM Identity Center (successor to AWS SSO)¶
A. AWS IAM Identity Center Setup¶
- Log in to the AWS Management Console and navigate to IAM Identity Center.
- Select Applications -> Add application.
- Under Application type, choose Add custom SAML 2.0 application or Add custom OAuth 2.0 / OIDC application. Select OAuth 2.0 / OIDC client.
- Configure the application settings:
- Application Name:
Liferay Tunnel Gateway - Redirect URLs:
https://<your-tunnel-gateway-host>/api/auth/callback?provider=aws-idc(For local testing, use:http://localhost:8000/api/auth/callback?provider=aws-idc) - Under Scopes, ensure the following scopes are enabled:
openidprofileemail- Save and extract the Client ID, Client Secret, and the OIDC Issuer URL (typically of the format
https://oidc.<aws-region>.amazonaws.com/orhttps://identitycenter.amazonaws.com/sso/oidc).
B. YAML Configuration Block¶
Add the following to your server-config.yaml:
allowed_email_domains:
- your-aws-org-domain.com
sso_providers:
- id: "aws-idc"
name: "AWS Identity Center"
client_id: "YOUR_AWS_CLIENT_ID"
client_secret: "YOUR_AWS_CLIENT_SECRET"
issuer_url: "https://oidc.YOUR_AWS_REGION.amazonaws.com"
icon: "aws"
4. Local Testing Files & Simulation¶
To test your SSO integration locally without deploying active infrastructure, you can choose between two methods:
Option A: Local Keycloak SSO (Recommended)¶
This uses our existing E2E Keycloak Docker setup to run a local OIDC Identity Provider.
-
Start the SSO Environment: Run the following command at the repository root:
Note: This spins up a complete Keycloak instance onhttp://localhost:8088pre-configured with the client IDlfr-tunnel. -
Add Local Config: Save a file named
server-config-local-sso.yamlwith the following contents: - Build the gateway server, then run the built binary:
Not
go run.go runlinks the executable inside the Go work directory (GOTMPDIR, or the system temp directory when that is unset) and runs it from there. An unsigned binary appearing in a temp directory and then opening network listeners is a signature endpoint-protection products quarantine on. Build to a path you chose, then execute that.
Option B: Local Mock OIDC Server (Dex)¶
Dex is a lightweight open-source OIDC provider that acts as a portal to other user databases. You can run Dex locally using Docker.
- Create a
dex-config.yaml:issuer: http://127.0.0.1:5556/dex storage: type: memory web: http: 0.0.0.0:5556 staticClients: - id: lfr-tunnel-dex redirectURIs: - 'http://localhost:8080/api/auth/callback?provider=dex' name: 'Liferay Tunnel' secret: dex-secret-key enablePasswordDB: true staticPasswords: - email: "developer@lfr-demo.local" hash: "$2a$10$w2Og7HzbetZGEs5GHAW5eeIHUIVX9Uqiyz1bT5D.S528B8g1yV.eq" # password: password username: "developer" userID: "12345" - Start Dex container:
- Configure
server-config.yaml:
5. SSO-Only Mode (disable_email_login)¶
With this set, no emailed link can sign anyone in or create an account (#2449):
- Self-registration (
/api/register-request) and requesting a sign-in link (/api/auth/magic-link) return 403. - Admin invites (
/api/admin/invite) return 403, and neither portal offers the Invite User button; each shows why in its place. A new person joins by signing in through the identity provider. /api/auth/verifyrefuses every magic link, including links sent before the switch and the owner's own. Nobody has an email fallback.
Recovery if the identity provider is unavailable: set disable_email_login: false in server-config.yaml on the gateway over SSH and restart lfr-tunneld. Email sign-in is back as soon as the service is. This is the only route back in, so keep SSH access to the gateway working before switching to SSO-only.
6. Per-provider trust settings¶
These settings on an sso_providers entry change how far the gateway trusts that provider. Each applies to that provider only; every other provider stays strict.
sso_providers:
- id: "liferay"
name: "Liferay SSO"
client_id: "…"
client_secret: "…"
issuer_url: "https://login.liferay.com"
email_verification: gateway # confirm the address by email when the provider has not
satisfies_mfa: true # a sign-in here meets force_mfa
email_verificationsays who vouches for the email address in the ID token:provider(the default) requiresemail_verified: trueand refuses the sign-in otherwise.gatewayacceptsemail_verified: true. When the claim isfalseor missing, the gateway emails the address a one-time link and finishes the sign-in only when it is used. The link opens a page with a Confirm and sign in button, works once, expires after 15 minutes, and signs in whichever browser opens it. The confirmation is stored on the account, so later sign-ins go straight through. Accounts that have already proven their address count as confirmed: an approved email registration, or a magic-link sign-in.allowed_email_domainsand closed registrations are checked before any email is sent. This mode needs working SMTP, and it still works withdisable_email_login: true, because the link only completes an SSO sign-in.-
trustaccepts the address as the provider asserts it. -
skip_email_verified_checkis the older form ofemail_verification: trust, and is what an unsetemail_verificationfalls back to. It accepts an ID token withoutemail_verified: true. Some providers never send it (Microsoft Entra ID), and some send it asfalsefor directory-managed accounts (Okta, for staff whose address came from the corporate directory). Set it only when the provider's directory owns every address it asserts.allowed_email_domainsis still enforced. satisfies_mfamakes a sign-in through this provider meetforce_mfa, because the provider performs MFA itself; users are not also made to enrol the gateway's own TOTP. It is decided per session: the same person signing in by magic link is still held toforce_mfa. Set it only when the provider's sign-on policy requires MFA. Without it, an SSO sign-in by someone who has set up the gateway's own authenticator code is asked for that code before the session starts, as a magic-link sign-in is. When email sign-in is off and every provider has it, nothing asks for the gateway's own authenticator code, so Account Settings says the provider handles MFA instead of offering to set one up, and the server refuses new enrolments. An enrolment made earlier can still be removed. Each SSO sign-in logs the ID token'samrclaim ([SSO] <provider>: sign-in for … amr=[…]), so you can confirm the provider reportsmfa.
Every SSO sign-in sets the account's first and last name from given_name and family_name, taken from the ID token or, when it carries none (as with Okta), from the provider's userinfo endpoint, so the admin Users list matches the directory. A session that signed in that way shows both names read-only in Account Settings, and the server refuses changes to them. Preferred Name stays editable, and on a first sign-in it defaults to given_name. A magic-link session, or a provider that sends no names, leaves the names editable. Administrators get one "New User Registration (SSO)" alert under the same switch as email registrations; later sign-ins send nothing.
Last Updated: 2026-11-18 | Last Reviewed: 2026-11-18