Custom Subdomains & DNS

Connected applications can request custom branding subdomains under *.campusone.com.ng (e.g., clearance.campusone.com.ng) to provide students with a trusted, seamless single-sign-on experience.

This guide details the subdomain lifecycle, CNAME mapping, TXT domain ownership validation, and how our automated background verification agent operates.

Subdomain Lifecycle

The subdomain setup process involves four distinct stages:

1. Requesting a Subdomain

When registering or updating your application inside the Developer Console, specify:

• Campus One Subdomain: Your requested name (e.g., bursary-portal).
• CNAME Target: The destination hosting server where your app is hosted (e.g., cname.vercel-dns.com, custom-alb.amazonaws.com, etc.).

2. DNS Record Provisioning (Admin Approval)

Once an administrator reviews and approves the application, Campus One programmatically registers two records in our central Cloudflare DNS zone:

1. CNAME Record: Maps your requested subdomain ([subdomain].campusone.com.ng) to your specified CNAME Target.
2. TXT Record: Provisions a randomized validation token to confirm domain delegation and ownership mapping.

Asynchronous Propagation Agent

DNS updates can take time to propagate across global nameservers. Rather than requiring developers to manually check or refresh repeatedly, Campus One employs an automated Propagation Agent running in the background.

Verification via DNS-over-HTTPS (DoH)

To prevent server caching issues and bypass standard local ISP resolver lag, Campus One performs real-time queries using Cloudflare's DNS-over-HTTPS (DoH) API directly from our Worker edge nodes:

curl -H "accept: application/dns-json" \
  "https://cloudflare-dns.com/dns-query?name=clearance.campusone.com.ng&type=CNAME"

Our system validates that the resolved CNAME alias matches the developer's requested CNAME target. Once verified, the app's official homepageUrl is updated to the newly active subdomain.

Developer Steps for Domain Setup

To ensure successful propagation, connect your web host provider to your Campus One custom subdomain:

Step 1: Add Custom Domain to Your Web Host

In your hosting console (e.g., Vercel, Netlify, AWS Amplify, or custom Nginx virtual host):

1. Navigate to Domain Settings.
2. Add the custom domain: [your-subdomain].campusone.com.ng.

Step 2: Configure DNS Settings

Since Campus One acts as the DNS authority for campusone.com.ng, our system creates the DNS records on Cloudflare pointing to your target. You do not need to add records to standard registrars. Just ensure your hosting console is configured to expect traffic arriving from [your-subdomain].campusone.com.ng.

Step 3: Wait for Propagation & Alert

Once approved, the background propagation agent checks the status every 10 minutes. When successful:

1. You will receive an in-app notification badge.
2. A congratulatory email will arrive in your developer inbox.
3. Your student login portal's launch link will automatically point to https://[your-subdomain].campusone.com.ng.

Troubleshooting

[!WARNING] Subdomain Lock: Once a subdomain has been verified and marked active, the subdomain and CNAME target inputs are locked in the branding configuration to prevent broken links and session Hijacking. If you need to migrate your CNAME target, contact the system administrator.

[!TIP] SSL/TLS Certificates: Ensure your hosting provider is configured to auto-renew SSL certificates (e.g., Let's Encrypt) for the custom subdomain. If traffic fails to load over HTTPS, double check your web host's SSL settings.