Setting Up Azure App Registration for Xbox OAuth

If you want your users to sign in with their Xbox Live accounts, you need to set up an Azure app registration. This guide walks you through the process step by step, and explains why this approach is better than using shared credentials.

Why Your Own Azure App?

You might wonder: why can't OpenXBL just handle all the OAuth stuff? Some platforms offer "dev keys" or shared credentials to make things easier. Here's why that's actually a bad idea:

Branding: When users authenticate, they see a consent screen. With your own app registration, this screen shows your app's name and logo. With shared credentials, users would see "OpenXBL" instead of your brand.

Token isolation: This is the big one. If all apps used OpenXBL's shared credentials, and a user went to their Microsoft account and revoked access to "OpenXBL", it would disconnect them from every app using that shared credential. Your app would break because of something completely unrelated to you.

Rate limits: Microsoft applies rate limits per app registration. With your own credentials, you get your own quota.

This is the same approach Auth0 takes. They offer "dev keys" for quick testing, but require you to use your own credentials in production. The "easier" path creates real problems at scale.

Step 1: Create the App Registration

Head to the Azure Portal's App Registrations page. You'll need a Microsoft account (the same one you use for Xbox works fine).

Click "New registration" and fill in:

• Name: Your app's name (users see this on the consent screen)
• Supported account types: Select "Personal Microsoft accounts only"
• Redirect URI: Select "Web" and enter https://api.xbl.io/app/callback

Important: The redirect URI must be https://api.xbl.io/app/callback. OpenXBL handles the OAuth tokenization process, then redirects to your app's callback URL that you configure in the dashboard. This way, you don't need to update Azure every time you change your callback URL.

Step 2: Copy Your Client ID

After creating the app, you'll land on the Overview page. Copy the "Application (client) ID" - it's a GUID that looks likexxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.

This is public information. It identifies your app but doesn't grant access on its own.

Step 3: Create a Client Secret

In the left sidebar, click "Certificates & secrets", then "New client secret". Give it a description (like "Production" or "Development") and pick an expiration.

Important: Copy the secret value immediately. Azure only shows it once. If you lose it, you'll need to create a new one.

Unlike the client ID, the secret must stay private. Never commit it to version control or expose it in client-side code.

Step 4: Add to OpenXBL

Now head to the OpenXBL dashboard and create a new app. Enter your client ID, client secret, and your app's callback URL (where you want users sent after authentication). The wizard will test your Azure credentials before saving.

Once created, you'll get a public key. The OAuth flow works like this:

1. Redirect users to: https://xbl.io/app/auth/YOUR_PUBLIC_KEY
2. Users authenticate with Microsoft (seeing your app's branding)
3. Microsoft redirects to OpenXBL
4. OpenXBL processes tokens and redirects to your callback URL

For CLI Users

If you prefer the command line, you can use Azure CLI:

az ad app create \
  --display-name "My Xbox App" \
  --sign-in-audience PersonalMicrosoftAccount \
  --web-redirect-uris "https://api.xbl.io/app/callback"

# Then create a secret
az ad app credential reset --id YOUR_APP_ID

Common Issues

"Invalid client" error: Double-check your client ID and secret. The secret expires, so if it worked before and stopped, you might need to create a new one.

"Redirect URI mismatch": The URI in your code must exactly match what's registered in Azure. Watch for trailing slashes and http vs https.

"AADSTS50011": The redirect URI isn't registered. Add it in Azure under Authentication → Platform configurations.

Security Notes

Rotate your client secrets periodically. Azure lets you have multiple active secrets, so you can create a new one, update your app, then delete the old one with no downtime.

Store secrets in environment variables or a secrets manager. Never hardcode them.