Authgear on Ubuntu 24.04 on Azure User Guide

Overview

This image runs Authgear 2026-06-11.0, the open source authentication server and identity provider from Authgear, on Ubuntu 24.04 LTS. Authgear implements the OpenID Connect and OAuth 2 standards, so your web and mobile applications delegate authentication to Authgear and receive standard tokens back. Out of the box it supports passwords, passwordless email and SMS one time codes, passkeys and biometric login, social and enterprise single sign on, and multi factor authentication, plus user management, sessions and an admin portal.

The pinned upstream server and admin portal are run as the official quay.io/theauthgear/authgear-server and authgear-portal containers under systemd services that start them on boot and restart them on failure, backed by a local PostgreSQL 16 database and Redis on the same VM. The server serves the end user auth pages and OIDC endpoints on port 3000 and the admin portal on port 3003. The resolver and admin GraphQL API are bound to loopback only. PostgreSQL and Redis are bound to loopback and hold all state.

What is included:

• Authgear 2026-06-11.0 (official authgear-server and authgear-portal images, pinned by digest), run by systemd
• The end user hosted auth pages and OIDC / OAuth 2 endpoints on :3000
• The admin portal on :3003
• Per-VM PostgreSQL and Redis passwords, per-VM OAuth and admin API signing keys, and a per-VM admin account, all generated on first boot and recorded in a root-only file
• Database migrations applied and the project configured automatically on first boot
• PostgreSQL 16 (with the pg_partman extension for the audit log) and Redis, both bound to loopback
• postgresql.service, redis-server.service, docker.service, authgear-server.service and authgear-portal.service as systemd units, enabled and active
• No administrator or signing key baked into the image
• 24/7 cloudimg support

Prerequisites

An active Azure subscription, an SSH key pair, and a VNet plus subnet in the target region. Standard_B2s (2 vCPU / 4 GiB RAM) is a sensible starting point; size up for heavier use. NSG inbound: allow 22/tcp from your management network, 3000/tcp for the auth endpoints and hosted sign in pages, and 3003/tcp for the admin portal. Authgear serves plain HTTP on those ports; for production, front it with your own domain and TLS and set the public origin accordingly (see the final steps).

Step 1 - Deploy from the Azure Marketplace

Sign in to the Azure Portal, choose Create a resource, search the Marketplace for Authgear by cloudimg, and select Create. On Basics pick your subscription, resource group, region and size; under Administrator account choose SSH public key and paste your key; under Inbound port rules allow SSH (22), 3000 and 3003. Then Review + create then Create.

Step 2 - Deploy from the Azure CLI

az vm create \
  --resource-group <your-rg> \
  --name authgear-1 \
  --image <cloudimg-authgear-marketplace-image> \
  --size Standard_B2s \
  --admin-username azureuser \
  --ssh-key-values ~/.ssh/id_rsa.pub \
  --public-ip-sku Standard

# open the auth endpoints and the admin portal
az vm open-port --resource-group <your-rg> --name authgear-1 --port 3000 --priority 1010
az vm open-port --resource-group <your-rg> --name authgear-1 --port 3003 --priority 1020

Step 3 - Connect to your VM

ssh azureuser@<vm-public-ip>

First boot generates the per-VM database and Redis passwords, the OAuth and admin API signing keys, and the admin account, applies the database migrations, configures the project and registers the app to your VM's public address. On a fresh Standard_B2s this takes about a minute; the commands below wait for it if needed.

Step 4 - Confirm the services are running

systemctl is-active postgresql redis-server docker authgear-server authgear-portal
docker ps --format 'table {{.Image}}\t{{.Names}}\t{{.Status}}'

All five services report active and both application containers are up:

active
active
active
active
active
IMAGE                                              NAMES             STATUS
quay.io/theauthgear/authgear-portal:2026-06-11.0   authgear-portal   Up About a minute
quay.io/theauthgear/authgear-server:2026-06-11.0   authgear-server   Up About a minute

Step 5 - Retrieve your per-VM credentials

The admin email and password, the portal and app URLs and the OIDC discovery URL are written to a root-only file on first boot:

sudo cat /root/authgear-credentials.txt

AUTHGEAR_ADMIN_EMAIL=admin@authgear.local
AUTHGEAR_ADMIN_PASSWORD=<generated-per-vm>
AUTHGEAR_PORTAL_URL=http://<vm-public-ip>:3003
AUTHGEAR_APP_URL=http://<vm-public-ip>:3000
AUTHGEAR_APP_HOST=<vm-public-ip>:3000
AUTHGEAR_OIDC_DISCOVERY=http://<vm-public-ip>:3000/.well-known/openid-configuration

Step 6 - Confirm the endpoints and OIDC discovery

Both servers expose a health endpoint, and the server publishes a standard OpenID Connect discovery document. The app resolves requests by the Host header, so read your VM's app host from the credentials file and pass it:

curl -s http://127.0.0.1:3000/healthz -o /dev/null -w "server /healthz: HTTP %{http_code}\n"
curl -s http://127.0.0.1:3003/healthz -o /dev/null -w "portal /healthz: HTTP %{http_code}\n"
APP_HOST=$(sudo grep '^AUTHGEAR_APP_HOST=' /root/authgear-credentials.txt | cut -d= -f2-)
curl -s -H "Host: ${APP_HOST}" http://127.0.0.1:3000/.well-known/openid-configuration \
  | jq '{issuer, authorization_endpoint, token_endpoint, jwks_uri, userinfo_endpoint}'

The discovery document returns the standard OIDC endpoints, all rooted at your VM's public address:

server /healthz: HTTP 200
portal /healthz: HTTP 200
{
  "issuer": "http://<vm-public-ip>:3000",
  "authorization_endpoint": "http://<vm-public-ip>:3000/oauth2/authorize",
  "token_endpoint": "http://<vm-public-ip>:3000/oauth2/token",
  "jwks_uri": "http://<vm-public-ip>:3000/oauth2/jwks",
  "userinfo_endpoint": "http://<vm-public-ip>:3000/oauth2/userinfo"
}

Step 7 - Sign in to the admin portal

Open AUTHGEAR_PORTAL_URL (http://<vm-public-ip>:3003) in a browser and sign in with the admin email and password from the credentials file. The portal opens on the Getting Started dashboard for your accounts project, with the full navigation for User Management, Authentication, Applications, multi factor authentication, Attack Protection, Branding and the Audit Log.

Step 8 - Manage users

Under User Management then Users you see the directory for your project, starting with the admin account created on first boot. From here you create users, assign roles and groups, and inspect sessions.

Step 9 - Preview the end user sign in experience

The hosted auth pages your applications send end users to are served on port 3000. Visiting http://<vm-public-ip>:3000/login (or clicking Preview login page in the portal) shows the sign in and sign up flow that Authgear renders and manages for you.

Step 10 - Connect your application

In the portal open Applications and create an application for your web, single page or mobile app. Authgear gives you a client ID and the endpoints from the discovery document above. Point your OpenID Connect client at:

• Issuer / discovery: http://<vm-public-ip>:3000/.well-known/openid-configuration
• Authorization endpoint: http://<vm-public-ip>:3000/oauth2/authorize
• Token endpoint: http://<vm-public-ip>:3000/oauth2/token

Any standards compliant OpenID Connect library (for example the Authgear SDKs, or a generic OIDC client) can then run the full sign in, token and userinfo flow against your instance.

Step 11 - Production hardening

Authgear resolves the tenant by the HTTP Host header and issues tokens for its public origin, which the image sets to your VM's current public IP on every boot. For production you should put Authgear behind your own domain name and TLS:

1. Point a DNS record (for example auth.example.com) at your VM and terminate TLS in front of it (a reverse proxy or an Azure load balancer / Application Gateway).
2. In the admin portal open Branding then Custom Domains (or Authentication) and add your domain so Authgear serves and issues tokens for https://auth.example.com.
3. Restrict the NSG so only your proxy reaches ports 3000 and 3003, and keep 22/tcp limited to your management network.

The admin GraphQL API stays bound to 127.0.0.1:3002 and is never exposed on the network.

Maintenance

• Restart the stack: sudo systemctl restart authgear-server authgear-portal
• View logs: sudo docker logs authgear-server and sudo docker logs authgear-portal
• Database and cache: PostgreSQL 16 and Redis run locally, bound to loopback, and hold all Authgear state. Back up PostgreSQL with your standard tooling.
• OS updates: unattended security upgrades are enabled; the base is fully patched at build time.

Support

Every cloudimg image comes with 24/7 support. If you need help deploying or operating Authgear, contact us at support@cloudimg.co.uk.