Skip to content

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

  1. Log in to the Azure Portal and navigate to Microsoft Entra ID.
  2. Select App registrations from the left panel, and click New registration.
  3. Fill in the following details:
  4. Name: Liferay Tunnel Gateway (or similar)
  5. Supported account types: Select your preference (e.g., Accounts in this organizational directory only to restrict to your company domain).
  6. 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)
  7. Click Register.
  8. Copy the Application (client) ID and Directory (tenant) ID from the Overview page.
  9. Navigate to Certificates & secrets -> Client secrets -> New client secret.
  10. 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

  1. Log in to the Google Cloud Console.
  2. Create or select a project.
  3. Navigate to APIs & Services -> OAuth consent screen:
  4. Set User Type to Internal (to restrict logins exclusively to members of your Google Workspace domain) or External (open to any Google account).
  5. Complete required fields (App name, support email, developer contact).
  6. Navigate to Credentials -> Create Credentials -> OAuth client ID.
  7. Select Application type: Web application.
  8. Set the following details:
  9. Name: Liferay Tunnel Gateway
  10. 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)
  11. 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

  1. Log in to the AWS Management Console and navigate to IAM Identity Center.
  2. Select Applications -> Add application.
  3. Under Application type, choose Add custom SAML 2.0 application or Add custom OAuth 2.0 / OIDC application. Select OAuth 2.0 / OIDC client.
  4. Configure the application settings:
  5. Application Name: Liferay Tunnel Gateway
  6. 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)
  7. Under Scopes, ensure the following scopes are enabled:
  8. openid
  9. profile
  10. email
  11. Save and extract the Client ID, Client Secret, and the OIDC Issuer URL (typically of the format https://oidc.<aws-region>.amazonaws.com/ or https://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:

This uses our existing E2E Keycloak Docker setup to run a local OIDC Identity Provider.

  1. Start the SSO Environment: Run the following command at the repository root:

    make e2e-sso
    
    Note: This spins up a complete Keycloak instance on http://localhost:8088 pre-configured with the client ID lfr-tunnel.

  2. Add Local Config: Save a file named server-config-local-sso.yaml with the following contents:

    domains:
      - "lfr-demo.local"
    http_bind_addr: "0.0.0.0:8080"
    db_path: "./lfr-tunnel-local-sso.db"
    
    sso_providers:
      - id: "keycloak-local"
        name: "Local Keycloak"
        client_id: "lfr-tunnel"
        client_secret: "secret"
        issuer_url: "http://localhost:8088/realms/liferay"
        icon: "key"
        skip_issuer_check: true
    

  3. Build the gateway server, then run the built binary:
    make build
    ./bin/lfr-tunneld -config server-config-local-sso.yaml
    

Not go run. go run links 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.

  1. 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"
    
  2. Start Dex container:
    docker run -d --name dex-mock -p 5556:5556 -v $(pwd)/dex-config.yaml:/etc/dex/config.docker.yaml dexidp/dex:v2.38.0
    
  3. Configure server-config.yaml:
    sso_providers:
      - id: "dex"
        name: "Dex Mock OIDC"
        client_id: "lfr-tunnel-dex"
        client_secret: "dex-secret-key"
        issuer_url: "http://localhost:5556/dex"
        icon: "key"
    

5. SSO-Only Mode (disable_email_login)

disable_email_login: true

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/verify refuses 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_verification says who vouches for the email address in the ID token:
  • provider (the default) requires email_verified: true and refuses the sign-in otherwise.
  • gateway accepts email_verified: true. When the claim is false or 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_domains and closed registrations are checked before any email is sent. This mode needs working SMTP, and it still works with disable_email_login: true, because the link only completes an SSO sign-in.
  • trust accepts the address as the provider asserts it.

  • skip_email_verified_check is the older form of email_verification: trust, and is what an unset email_verification falls back to. It accepts an ID token without email_verified: true. Some providers never send it (Microsoft Entra ID), and some send it as false for 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_domains is still enforced.

  • satisfies_mfa makes a sign-in through this provider meet force_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 to force_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's amr claim ([SSO] <provider>: sign-in for … amr=[…]), so you can confirm the provider reports mfa.

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