Sign in with BuzzCloud
BuzzCloud is a standard OpenID Connect provider. Any OIDC or OAuth 2.1 library works. Point it at the issuer and it discovers the rest.
Issuer https://buzzcloud.win/auth
Discovery https://buzzcloud.win/auth/.well-known/openid-configuration
Apps are registered by the BuzzCloud owner under Account → Developer apps. BuzzOS is registered already as buzzos.
Endpoints
| Endpoint | URL |
|---|---|
| Authorize | /auth/oauth/authorize |
| Token | /auth/oauth/token |
| Device authorization | /auth/oauth/device_authorization (users enter the code at /auth/device) |
| User info | /auth/oauth/userinfo |
| Keys (JWKS) | /auth/oauth/jwks |
| Revoke (sign out) | /auth/oauth/revoke |
Scopes and claims
| Scope | Gives the app |
|---|---|
openid | sub: the account’s permanent ID (it never changes, even if the email does) |
profile | name |
email | email, plus email_verified: false (BuzzCloud doesn’t verify emails yet) |
offline_access | Asks to stay signed in. Apps allowed refresh tokens get one either way. |
Rules
- PKCE with S256 is required for every app, public or confidential.
- Redirect URIs must match exactly. Allowed:
https://…, loopbackhttp://127.0.0.1/…(any port), or a reverse-domain app scheme likewin.buzzcloud.buzzos:/oauth2redirect. - Access tokens and ID tokens are RS256 JWTs that last 1 hour. Access tokens have
typ: at+jwt,aud= your client ID, andsid= the sign-in. - Refresh tokens last 180 days and rotate on every use: always store the new one. Reusing an old refresh token signs that device out (it looks like a stolen token).
- Users see every signed-in device under Account → Signed-in apps and can sign any of them out. After that, refresh fails with
invalid_grant: send the user back to sign-in. - Pass
device_name(e.g. “Pixel 8”) on the authorize or device request so the account page can label the device.
BuzzOS (Android)
Browser sign-in with AppAuth
Use AppAuth for Android. It opens a Custom Tab, does PKCE, and returns through the app scheme.
// build.gradle: implementation "net.openid:appauth:0.11.1"
// manifestPlaceholders = [appAuthRedirectScheme: "win.buzzcloud.buzzos"]
AuthorizationServiceConfiguration.fetchFromIssuer(
Uri.parse("https://buzzcloud.win/auth")) { config, ex ->
val request = AuthorizationRequest.Builder(
config!!, "buzzos", ResponseTypeValues.CODE,
Uri.parse("win.buzzcloud.buzzos:/oauth2redirect"))
.setScopes("openid", "profile", "email", "offline_access")
.setAdditionalParameters(mapOf("device_name" to Build.MODEL))
.build()
startActivityForResult(authService.getAuthorizationRequestIntent(request), RC_AUTH)
}
// In onActivityResult: performTokenRequest(response.createTokenExchangeRequest()) and keep the
// AuthState (it holds the refresh token and does rotation for you).
System account (Settings → Accounts)
To make BuzzCloud a real Android account, add an AbstractAccountAuthenticator service in a BuzzOS system app:
- Account type:
win.buzzcloud.account. Account name: the user’s email, withsubstored as user data. Key the account onsub, because the email can change. addAccount()starts the AppAuth flow above. Store the refresh token withsetPassword(), or better, encrypted with the Android Keystore.getAuthToken()refreshes when the 1-hour access token is near expiry, and saves the rotated refresh token.- On
invalid_grant, callAccountManager.invalidateAuthToken()and return a sign-in intent. - Removing the account calls
/auth/oauth/revokewith the refresh token.
Setup wizard (no browser yet): device code
POST https://buzzcloud.win/auth/oauth/device_authorization
client_id=buzzos&scope=openid profile email offline_access&device_name=Pixel 8
→ { "device_code": "bcdc_…", "user_code": "BCDF-GHJK",
"verification_uri": "https://buzzcloud.win/auth/device",
"verification_uri_complete": "https://buzzcloud.win/auth/device?code=BCDF-GHJK",
"expires_in": 600, "interval": 5 }
Show the code and a QR of verification_uri_complete. Then poll every interval seconds:
POST https://buzzcloud.win/auth/oauth/token
grant_type=urn:ietf:params:oauth:grant-type:device_code&device_code=bcdc_…&client_id=buzzos
Keep polling while you get authorization_pending. On slow_down, add 5 seconds to the interval. Stop on access_denied or expired_token. Success returns the same tokens as browser sign-in.
Web and server apps
Register a confidential app to get a client secret. Authenticate at the token endpoint with HTTP Basic (client_secret_basic) or form fields (client_secret_post). Still send PKCE. Validate the ID token against the JWKS: check iss, aud, exp and your nonce.
Other prompt values: none returns login_required or consent_required instead of showing a page, and login asks for the password again.