KlugAuth documentation

Introduction

KlugAuth lets users of an AIR app create an account or sign in with Sign in with Apple or Sign in with Google, using the sign-in sheet of the operating system. Your app receives the provider's signed identity token, which your server verifies before it creates or opens the account. No password is typed, stored or sent.

Google sign-in on iOS and macOS uses the standard OAuth 2.0 authorization-code flow with PKCE in the system's web authentication sheet; no Google SDK is bundled.

Requirements

Add the extension

1 · Copy the ANE and declare it

Copy com.klug.auth.KlugAuth.ane into the extension folder of your project, add it to your build (IDE: native extension of the project; command line: -external-library-path for compiling, -extdir for packaging) and declare it:

<extensions>
    <extensionID>com.klug.auth.KlugAuth</extensionID>
</extensions>

2 · iOS (and the iPad app on the Mac)

Sign in with Apple needs one entitlement. Google needs no Info.plist entry and no URL scheme: the sign-in window returns to the app by itself.

<iPhone>
    <Entitlements><![CDATA[
    <key>com.apple.developer.applesignin</key>
    <array>
        <string>Default</string>
    </array>
    ]]></Entitlements>
</iPhone>

Package with a provisioning profile that was created after Sign in with Apple was enabled on the App ID (see Guides · Apple setup), otherwise signing fails or the sheet reports an error.

3 · macOS

For the macOS build, add the entitlements to the entitlements file you sign the app with (codesign --entitlements). Sign in with Apple needs the same entitlement as on iOS. Sandboxed apps (Mac App Store) also need outgoing network access, which the Google sign-in uses to complete the login:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>com.apple.security.app-sandbox</key>
    <true/>
    <key>com.apple.security.network.client</key>
    <true/>
    <key>com.apple.developer.applesignin</key>
    <array>
        <string>Default</string>
    </array>
</dict>
</plist>

Embed a provisioning profile for the Mac App ID that includes Sign in with Apple. Restricted entitlements such as com.apple.developer.applesignin only work with such a profile.

4 · Android

No permission, activity or service has to be added to <manifestAdditions>. The Android libraries the extension uses (AndroidX Credential Manager and Google Identity) are declared inside the ANE and resolved automatically by the AIR SDK's Gradle build when you package the app; the build machine needs access to Google's Maven repository and Maven Central for that. Your app's usual network permission is enough to send the token to your server:

<android>
    <manifestAdditions><![CDATA[
<manifest>
    <!-- for your own request to your server, not for the sign-in sheet -->
    <uses-permission android:name="android.permission.INTERNET"/>
</manifest>
    ]]></manifestAdditions>
</android>

The Google console needs an Android OAuth client for your package name and signing certificate; see Guides · Google setup.

Getting started

KlugAuth is a singleton. Check what the device offers, add the listeners, create a fresh nonce and open the sheet. The call returns at once; the result arrives as a KlugAuthEvent. Send the token and the same raw nonce to your server.

import com.klug.auth.KlugAuth;
import com.klug.auth.KlugAuthEvent;

var auth:KlugAuth = KlugAuth.getInstance();
var nonce:String;

appleButton.visible = auth.isSupported;   // Sign in with Apple available here?

auth.addEventListener( KlugAuthEvent.APPLE_SUCCESS,  onAppleSuccess );
auth.addEventListener( KlugAuthEvent.APPLE_CANCELED, onCanceled );
auth.addEventListener( KlugAuthEvent.APPLE_ERROR,    onError );

function onAppleButton():void
{
    nonce = KlugAuth.generateNonce();         // new for every attempt
    if ( !auth.signInWithApple( nonce ) )
        showMessage( "Sign in with Apple could not start." );   // your app function
}

function onAppleSuccess( e:KlugAuthEvent ):void
{
    // never trust this on the device: let your server verify the token
    postToMyServer( "apple", e.identityToken, nonce, e.fullName );   // your app function
}

function onCanceled( e:KlugAuthEvent ):void { /* user closed the sheet */ }
function onError( e:KlugAuthEvent ):void { trace( e.errorCode, e.errorMessage ); }

Guides

Apple setup (Apple Developer account)

• 1. In Certificates, Identifiers & Profiles → Identifiers, open the App ID of your iOS app (com.example.yourapp) and enable Sign In with Apple (as a primary App ID). Do the same for a separate macOS App ID if you ship a native Mac build (com.example.yourapp.desktop). The iPad app on the Mac uses the iOS App ID.
• 2. Create the provisioning profiles (development and distribution) again and use the new ones for packaging. Old profiles do not contain the capability.
• 3. Add the entitlement (iOS: app descriptor; macOS: signing entitlements), see Add the extension.
• 4. For the server: create a Sign in with Apple key under Keys if your server will exchange the authorization code or revoke tokens (needed for account deletion). Note your Team ID and the key ID; the private key stays on your server.
• 5. Design the button according to Apple's Human Interface Guidelines for Sign in with Apple (black or white, Apple logo, approved wording).

If your iOS app offers Sign in with Google or another third-party login, Apple's App Review Guidelines require an equivalent privacy-friendly option, which Sign in with Apple fulfils. Apps that let users create an account must also let them delete it; with Sign in with Apple, the server should then revoke the token (see Server-side verification below).

Google setup (Google Cloud console)

Create one project for your app and, under APIs & Services, configure the OAuth consent screen (app name, support e-mail, scopes openid, email, profile). Then create these OAuth client IDs under Credentials:

SHA-1 fingerprints. Read the fingerprint of your release certificate with keytool -list -v -keystore your-release.p12 -storetype pkcs12. If Google Play signs your app (Play App Signing), add a second Android client with the SHA-1 of the app signing key shown in the Play Console under App integrity; the upload certificate alone is not enough for store installs. Add a client for your debug certificate too if you test debug builds.

While the publishing status of the consent screen is Testing, only the listed test users can sign in. Publish it before the release.

Sign in with Apple

signInWithApple(rawNonce) opens Apple's sheet. It asks for the user's name and e-mail; the user can hide the e-mail behind an Apple relay address.

• Nonce: pass a fresh value from generateNonce(). Apple places its SHA-256 (lower-case hex) in the token's nonce claim; your server hashes the raw value it receives and compares.
• First authorization only: email, givenName and familyName are filled only the first time a user authorizes your app. Send them to your server right away. Later sign-ins return empty strings; the e-mail is still inside the identity token.
• userID is Apple's stable user identifier for your team, the same on all devices of that Apple ID (and equal to the token's sub). Store it to check the credential state later.
• authorizationCode is a short-lived, single-use code. Your server can exchange it with Apple for a refresh token, which it needs to revoke the link when the account is deleted.
• Only one Apple sheet can be open at a time: a second call while one is open returns false.

import com.klug.auth.KlugAuth;
import com.klug.auth.KlugAuthEvent;

var auth:KlugAuth = KlugAuth.getInstance();
var appleNonce:String;

auth.addEventListener( KlugAuthEvent.APPLE_SUCCESS,  onAppleSuccess );
auth.addEventListener( KlugAuthEvent.APPLE_CANCELED, onAppleCanceled );
auth.addEventListener( KlugAuthEvent.APPLE_ERROR,    onAppleError );

function signInWithApple():void
{
    if ( !auth.isSupported ) return;             // Android, Windows
    appleNonce = KlugAuth.generateNonce();
    if ( !auth.signInWithApple( appleNonce ) )
        showMessage( "Please wait, sign-in is already open." );   // your app function
}

function onAppleSuccess( e:KlugAuthEvent ):void
{
    saveAppleUserID( e.userID );                        // your app function
    postToMyServer( {
        provider: "apple",
        id_token: e.identityToken,
        nonce:    appleNonce,                           // the RAW value
        code:     e.authorizationCode,                  // for refresh / revoke on the server
        name:     e.fullName,                           // "" after the first authorization
        email:    e.email                               // hint only: the server reads the token
    } );
}

function onAppleCanceled( e:KlugAuthEvent ):void
{
    // the user closed the sheet: stay on the screen, no message
}

function onAppleError( e:KlugAuthEvent ):void
{
    log( "Apple sign-in failed " + e.errorCode + ": " + e.errorMessage );   // your app function
    showMessage( "Sign in with Apple is not available right now." );
}

Sign in with Google

signInWithGoogle(clientId, rawNonce) opens Google sign-in. The client ID depends on the platform:

• Nonce: Google puts the raw value unchanged into the token's nonce claim.
• Every time: email, givenName, familyName are filled on every sign-in. userID is the account e-mail; for a stable key on your server use the token's sub claim.
• authorizationCode is always empty for Google.
• Returns false when the client ID is empty, a Google sign-in is already running, or (iOS / macOS) the client ID does not end in .apps.googleusercontent.com.

import com.klug.auth.KlugAuth;
import com.klug.auth.KlugAuthEvent;
import flash.system.Capabilities;

const GOOGLE_WEB_CLIENT_ID:String = "YOUR_WEB_CLIENT_ID.apps.googleusercontent.com";
const GOOGLE_IOS_CLIENT_ID:String = "YOUR_IOS_CLIENT_ID.apps.googleusercontent.com";

var auth:KlugAuth = KlugAuth.getInstance();
var googleNonce:String;

googleButton.visible = auth.isGoogleSupported;   // Android, iOS 13+, macOS 10.15+
auth.addEventListener( KlugAuthEvent.GOOGLE_SUCCESS,  onGoogleSuccess );
auth.addEventListener( KlugAuthEvent.GOOGLE_CANCELED, onGoogleCanceled );
auth.addEventListener( KlugAuthEvent.GOOGLE_ERROR,    onGoogleError );

function googleClientId():String
{
    return Capabilities.manufacturer.indexOf( "Android" ) >= 0
        ? GOOGLE_WEB_CLIENT_ID
        : GOOGLE_IOS_CLIENT_ID;
}

function signInWithGoogle():void
{
    googleNonce = KlugAuth.generateNonce();
    if ( !auth.signInWithGoogle( googleClientId(), googleNonce ) )
        showMessage( "Google sign-in could not start." );   // your app function
}

function onGoogleSuccess( e:KlugAuthEvent ):void
{
    postToMyServer( {
        provider: "google",
        id_token: e.identityToken,
        nonce:    googleNonce,
        name:     e.fullName
    } );
}

function onGoogleCanceled( e:KlugAuthEvent ):void { }

function onGoogleError( e:KlugAuthEvent ):void
{
    if ( e.errorCode == "NO_ACCOUNT" )             // Android: no Google account on the device
        showMessage( "Add a Google account in the device settings first." );
    else
        showMessage( "Google sign-in failed. Please try again." );
    log( "Google " + e.errorCode + ": " + e.errorMessage );
}

Send the token to your server

The app's only job after a successful sign-in is to pass the token and the raw nonce to your backend over HTTPS. The server verifies everything and answers with its own session; the app never decides on the basis of email or userID from the event alone.

import flash.events.Event;
import flash.events.IOErrorEvent;
import flash.net.URLLoader;
import flash.net.URLRequest;
import flash.net.URLRequestMethod;
import flash.net.URLVariables;

function postToMyServer( fields:Object ):void
{
    var vars:URLVariables = new URLVariables();
    for ( var key:String in fields ) vars[ key ] = fields[ key ];

    var req:URLRequest = new URLRequest( "https://api.example.com/auth/social" );
    req.method = URLRequestMethod.POST;
    req.data = vars;

    var loader:URLLoader = new URLLoader();
    loader.addEventListener( Event.COMPLETE, function( e:Event ):void {
        var answer:Object = JSON.parse( String( loader.data ) );
        if ( answer.ok ) startSession( answer.session );   // your app function
        else showMessage( answer.message );
    });
    loader.addEventListener( IOErrorEvent.IO_ERROR, function( e:IOErrorEvent ):void {
        showMessage( "No connection to the server." );
    });
    loader.load( req );
}

Server-side verification

The identity token is a signed JSON Web Token (JWT). Treat everything that comes from the app as untrusted until the token is verified on your server. Use a maintained JWT library for your server language; do not decode and trust the payload without checking the signature.

• Never trust the client: e-mail, name and user ID sent next to the token are hints for display only (for example a proposed user name).
• Replay: keep used nonces (or token IDs) for the lifetime of a token and reject repeats.
• Apple authorization code: exchange it at Apple's token endpoint with a client secret (a JWT your server signs with the Sign in with Apple key) and store the refresh token. When the user deletes the account, call Apple's revoke endpoint with it.
• Linking: if an account with the same verified e-mail already exists, decide on your server whether to link it, and ask the user when in doubt.
• Answer the app with your own session token; do not keep using the provider's identity token as a session.

Check a returning Apple user

Users can stop using Sign in with Apple for your app in their Apple ID settings. At app start, ask Apple about the stored user ID with getCredentialState(userID); the answer arrives as APPLE_CREDENTIAL_STATE. iOS and macOS only; on Android the call returns false.

auth.addEventListener( KlugAuthEvent.APPLE_CREDENTIAL_STATE, function( e:KlugAuthEvent ):void {
    if ( e.state == "revoked" || e.state == "notFound" )
        signOut();                       // your app function
});

var savedID:String = loadAppleUserID();   // your app function
if ( auth.isSupported && savedID != "" )
    auth.getCredentialState( savedID );

Show only what the device supports

Decide the visible buttons once, when the sign-in screen opens:

var auth:KlugAuth = KlugAuth.getInstance();
appleButton.visible  = auth.isSupported;        // iOS 13+, iPad on Mac, macOS 10.15+
googleButton.visible = auth.isGoogleSupported;  // Android, iOS 13+, macOS 10.15+
if ( !appleButton.visible && !googleButton.visible )
    showPasswordLogin();                        // your app function, e.g. on Windows

Background, return and errors

While a sheet is open, the system shows its own UI above your app. On Android and in the Google window on iOS / macOS, your app may receive Event.DEACTIVATE and Event.ACTIVATE around it; do not treat this as the user leaving the sign-in screen. The result event arrives when the sheet closes. Keep the nonce in a variable until then.

• Every attempt ends with exactly one success, cancel or error event of its provider.
• Cancel is never reported as an error. Show no message for it.
• A false return value means no sheet was opened and no event will follow.
• Methods never throw; on platforms without support they return false.

API reference

class KlugAuth

Package com.klug.auth · extends flash.events.EventDispatcher · singleton.

class KlugAuthEvent

Package com.klug.auth · extends flash.events.Event · does not bubble, not cancelable. Fields that do not apply to an event type are empty strings, never null.

Events

All results are KlugAuthEvents dispatched on the KlugAuth instance, asynchronously after the sheet closes.

Troubleshooting

APPLE_ERROR with code 1000 right away.

Check, in this order: Sign in with Apple is enabled on the App ID; the provisioning profile was created after that; the entitlement com.apple.developer.applesignin is in the app (iOS: <Entitlements>, macOS: signing entitlements); the device is signed in to an Apple ID with two-factor authentication.

The e-mail and name are empty after the first test.

Apple sends them only on the first authorization of the app for that Apple ID. To test again, remove your app from the list of apps using Sign in with Apple in the Apple ID settings of the device. In production, store them on the server on the first sign-in; the e-mail is always in the token.

Android: GOOGLE_ERROR after choosing an account, or no account sheet.

Almost always the Android OAuth client: the package name must match the installed app exactly (including the air. prefix if your build uses it), and the SHA-1 must be that of the certificate the installed app is signed with. Store installs with Play App Signing need the SHA-1 of the app signing key from the Play Console. Also check that you pass the web client ID, not the Android one.

Android: NO_ACCOUNT.

The device has no Google account. Ask the user to add one in the system settings, or offer another sign-in method.

iOS / macOS: signInWithGoogle returns false.

The client ID must be an iOS client ID ending in .apps.googleusercontent.com. A web client ID does not work in the system sign-in window. False is also returned while a Google sign-in is still open.

iOS / macOS: GOOGLE_ERROR "AUTH" or "TOKEN".

"AUTH": Google refused the request, typically a wrong or deleted client ID, or a consent screen in testing mode with a user who is not listed. "TOKEN": the login could not be completed, typically no network; on a sandboxed Mac app also check com.apple.security.network.client.

The server rejects the token: wrong audience.

Android tokens carry the web client ID as audience, iOS / macOS tokens the iOS client ID. Accept both on the server. Apple tokens carry the bundle ID of the app that signed in; a native Mac build with its own bundle ID needs that ID on the list too.

The server rejects the token: nonce mismatch.

Send the raw nonce. For Apple, the server must compare the token's nonce with SHA-256 (lower-case hex) of it; for Google, with the raw value itself. Create a new nonce for every attempt and keep it until the result arrives.

Sign in with Apple on Android?

isSupported is false on Android; signInWithApple() and getCredentialState() return false there. Apple offers a web-based flow for other platforms, which needs a page on your server; it is not part of this extension.

"KlugAuth is a singleton" error.

Use KlugAuth.getInstance() everywhere instead of new KlugAuth().

Changelog