# `apple_sign_in`

| Package | Kind | Provides the role | Needs | Choose with |
| --- | --- | --- | --- | --- |
| [`smf_apple_sign_in`](https://pub.dev/packages/smf_apple_sign_in) | infrastructure | none | a provider of the authentication, such as [`firebase_auth`](https://doc.saymyframe.com/modules/firebase-auth.md) | `-m apple_sign_in` |

`apple_sign_in` lets the users of the app sign in with their Apple Account on iOS, with [Sign in with Apple](https://developer.apple.com/sign-in-with-apple/) through the [sign_in_with_apple](https://pub.dev/packages/sign_in_with_apple) package. It is a way to sign in next to the email address and the password: the module asks Apple for a credential, and the module that provides the authentication signs the user in with it. On Android the app has no Sign in with Apple.

The module has no screen. A screen of sign-in, such as those of [`sign_in`](https://doc.saymyframe.com/modules/sign-in.md), shows its button, and code of your own can use it too. [Sign-in](https://doc.saymyframe.com/guides/sign-in.md#ways-to-sign-in) describes the ways to sign in of an app and what `appSession` does with their credentials.

## What it adds to the app

| In the app | What it is |
| --- | --- |
| `sign_in_with_apple: ^8.2.0` and `crypto: ^3.0.7` in the dependencies | The package of Sign in with Apple, and the package that hashes the nonce of a request. |
| `lib/core/apple_sign_in/apple_sign_in.dart` | `appleCredential()`, which asks Apple for a credential, and `AppleSignInIcon`, the icon of its button. |
| `com.apple.developer.applesignin` in `ios/Runner/Runner.entitlements` | The entitlement of the capability Sign in with Apple, with the step by hand `app_entry.ios_app_id`; see [the capability](#the-capability). |
| The section "Sign in with Apple" of the README | What the capability needs of the team that signs the app, what Apple gives only at the first sign-in, what a deletion asks of Apple and of the backend, and that App Review checks the logo of the button. |

The module signs the iOS app with the entitlement through a socket of the app entry, whichever module provides the app entry; see [the sockets of the app entry](https://doc.saymyframe.com/concepts/sockets.md#the-sockets-of-the-app-entry):

```xml title="ios/Runner/Runner.entitlements"
<dict>
	<key>com.apple.developer.applesignin</key>
	<array>
		<string>Default</string>
	</array>
</dict>
```

The module gives the auth role its way to sign in. Whichever module provides the role, the role lists it in `appSignInMethods` of `lib/core/auth/sign_in_methods.dart`. In an app with this module alone:

```dart title="lib/core/auth/sign_in_methods.dart"
const List<SignInMethod> appSignInMethods = [
  SignInMethod(
    label: _appleSignInLabel,
    icon: method0.AppleSignInIcon(),
    platforms: {TargetPlatform.iOS},
    credential: method0.appleCredential,
    issuer: 'https://appleid.apple.com',
    revokesOnDeletion: true,
  ),
];
```

| | The way to sign in with Apple |
| --- | --- |
| Label | Continue with Apple, one of the titles that Apple allows a custom button of Sign in with Apple, and Продовжити з Apple in Ukrainian. In an app without a module that provides the localization, the label is in English. |
| Icon | `AppleSignInIcon`, the Apple logo of the Material icons, `Icons.apple`, in the color of the label; see [the button](#the-button). |
| Platforms | iOS. A screen of sign-in shows its button on no other. |
| Issuer | `https://appleid.apple.com`. `AccountSession.issuers` names Apple by it. |
| For the App Store | The equivalent of a login service of a third party; see [the App Store](#the-app-store). |
| What it needs of the backend | Nothing that the module states. Deleting an account needs a key of Apple at the provider of the authentication; see [deleting an account](#deleting-an-account). |
| Deleting an account | Asks Apple again first: `revokesOnDeletion` is `true`. |

In the [guide for coding agents](https://doc.saymyframe.com/guides/coding-agents.md) of the app, the module writes the section "Sign in with Apple": which file asks Apple and what it returns, that Apple gives the name only at the first sign-in, which errors become which reason, the entitlement, and what a test sets to sign in with Apple.

## Signing in with it

`appleCredential()` shows the sheet of Sign in with Apple. It asks for the email address and the full name of the user, with the SHA-256 hash of a new random nonce of `generateNonce()`, which Apple writes into the ID token. It returns an `IdTokenCredential` of the issuer of Apple with:

- the ID token of Apple;
- the raw nonce itself, against which the provider of the authentication checks the token;
- the authorization code of the request, with which the provider can revoke the tokens that Apple gave the app;
- the given name and the family name of the user.

A screen of sign-in calls it as `credential()` of the way to sign in, from its state, and gives the credential to `appSession.signInWith`. Here `method` is the way to sign in from `appSignInMethods`:

```dart
final credential = await method.credential();
if (credential == null) return; // The user closed the sheet of Apple.
await appSession.signInWith(credential);
```

Call it from the state of a screen, never within a call of `appSession`. An anonymous user who signs in with Apple gets the identity and keeps the id, or signs in to the account that has it already; see [ways to sign in](https://doc.saymyframe.com/guides/sign-in.md#ways-to-sign-in).

Apple gives the name of the user only the first time that the user signs in to the app. The credential has it then, and a later one has none, so do not expect it there. The user may also hide the email address. The account then gets an address of the private relay of Apple, which forwards messages to the user.

| What happens | What `appleCredential()` does |
| --- | --- |
| The app runs on a platform other than iOS | It fails with `notConfigured` without asking Apple. On Android, the hint is `Sign in with Apple works on iOS only, and the app runs on android.` |
| The user closed the sheet, `canceled` | It returns `null`. That is no failure: the screen goes back to how it was. |
| Apple answers with an unknown error, `unknown` | It fails with `notConfigured`. Apple answers so when the app is not signed with the capability, and may do so on a device without an Apple Account. |
| Any other error, or a credential without an identity token | It fails with `unknown`, with the error in the `developerHint`. |

The `developerHint` of the unknown error names the capability and the section of the README:

```text
AuthFailure: notConfigured (Apple answered with an unknown error (<the message of Apple>). It does so when the app is not signed with the capability Sign in with Apple, which needs a team of the paid Apple Developer Program, and may do so on a device without an Apple Account. See the section "Sign in with Apple" of the README of the app.)
```

The provider of the authentication has to take Apple too. With `firebase_auth`, Apple is enabled in the Firebase console, under Authentication > Sign-in method, since the Firebase CLI cannot enable it. Until then, signing in with Apple fails with `notConfigured`, and the hint tells how to enable it.

## The capability

Sign in with Apple is a capability of the app. The key `com.apple.developer.applesignin` in `ios/Runner/Runner.entitlements` asks for it, and every build configuration of the Runner target signs with that file. The App ID of the app needs the capability too: when Xcode manages the signing of the app, it adds the capability to the App ID. Signing with the capability needs a team of the paid Apple Developer Program.

So the app lists the step by hand `app_entry.ios_app_id`, in which you sign the app once in Xcode with your paid team, which registers the App ID with the capability. The README of the app has it under "Finish the setup", and the [click-by-click guide](https://doc.saymyframe.com/setup/app-entry-ios-app-id.md) shows each screen.

A free personal team cannot sign the app for an iPhone. To run the app there, remove the key from `ios/Runner/Runner.entitlements`. Signing in with Apple then fails with `notConfigured`, as in any app without the capability.

## Deleting an account

App Store Review Guideline 5.1.1(v) asks an app with Sign in with Apple to revoke the tokens that Apple gave it when the user deletes the account. So on iOS, for an account that signs in with Apple, `appSession.deleteAccount()` first calls `appleCredential()` itself, and the sheet of Apple shows again. The provider of the authentication then signs the user in again with the new credential, revokes the tokens of Apple with its authorization code, and deletes the account. If the user closes the sheet, nothing is deleted, and that is no failure.

The backend needs a key of Apple to revoke the tokens. With `firebase_auth`, the settings of the Apple provider in the Firebase console take the Services ID and the OAuth code flow configuration: your Apple team ID, and the Key ID and the private key of a key for Sign in with Apple. The private key is a secret: enter it in the console yourself, and never put it into the app or its repository. Until they are set, deleting an account that signs in with Apple fails with `notConfigured`, and the account stays. See [`firebase_auth`](https://doc.saymyframe.com/modules/firebase-auth.md#google-and-apple). Adding Apple in the Firebase console and entering the key there are steps by hand of an app with `firebase_auth`, and the click-by-click guides of [the provider](https://doc.saymyframe.com/setup/firebase-auth-apple-provider.md) and of [the key](https://doc.saymyframe.com/setup/firebase-auth-apple-revocation.md) show each screen.

The screen of the account of [`sign_in`](https://doc.saymyframe.com/modules/sign-in.md) has a text of its own for such a failure. It has one too for a confirmation with another Apple Account, which the provider refuses with `invalidCredentials`, deleting nothing.

## The button

![The sign-in of sign_in in the light theme: the title Sign in with the line Choose how to sign in to your account. below it, the white buttons Continue with Google, with the colored G, and Continue with Apple, with the Apple logo, then or and the form for an email address and a password.](https://doc.saymyframe.com/demo/0.8/app_sign_in.png)
![The same sign-in in the dark theme: the two buttons stay white, with a black label and icon.](https://doc.saymyframe.com/demo/0.8/app_sign_in_dark.png)

`AppleSignInIcon` is `Icon(Icons.apple)`, the Apple logo of the Material icons. It takes the color and the size of the `IconTheme` around it, so it has the color of the label of its button. SMF does not ship the logo artwork of Apple, whose license does not allow it.

Apple asks a custom button of Sign in with Apple to use the logo artwork of [Apple Design Resources](https://developer.apple.com/design/resources/), and App Review checks every such button. Before you submit the app, download that logo and show it in `AppleSignInIcon` of `lib/core/apple_sign_in/apple_sign_in.dart`. In this sketch the logo is an image of your own, which `pubspec.yaml` declares among the assets of the app, at the size of the icons of the button:

```dart title="lib/core/apple_sign_in/apple_sign_in.dart"
class AppleSignInIcon extends StatelessWidget {
  const AppleSignInIcon({super.key});

  @override
  Widget build(BuildContext context) {
    final size = IconTheme.of(context).size;
    // The label of the button names Apple.
    return Image.asset(
      'assets/apple_logo.png',
      width: size,
      height: size,
      excludeFromSemantics: true,
    );
  }
}
```

Keep the constructor `const` and without arguments: the list of the ways to sign in creates the icon as a constant.

[`sign_in`](https://doc.saymyframe.com/modules/sign-in.md#other-ways-to-sign-in) shows the button above the form of the sign-in and of the sign-up, on iOS only. It draws the button white with a grey hairline, with the label and the icon in black, in the light theme and in the dark one. The icon is 20 logical pixels and keeps that size at a large text size.

## The App Store

App Store Review Guideline 4.8 asks an app on iOS that offers a login service of a third party, such as Google sign-in, to offer an equivalent way to sign in too: one that asks for no more than the name and the email address of the user and lets the user keep the address private. The App Store takes Sign in with Apple as such a way.

An app with [`google_sign_in`](https://doc.saymyframe.com/modules/google-sign-in.md) and without this module gets the warning `auth.no_equivalent_sign_in` from `smf create`, which stops a run with `--strict`. With this module next to it, the warning goes away:

```bash
smf create my_app -m google_sign_in,apple_sign_in
```

See [the App Store](https://doc.saymyframe.com/modules/google-sign-in.md#the-app-store) of `google_sign_in`, and [Lenient and strict](https://doc.saymyframe.com/guides/smf-create.md#lenient-and-strict).

## In tests

`appleCredential()` asks Apple only while `debugDefaultTargetPlatformOverride` is `TargetPlatform.iOS`, so a test that calls it, as a tap on the button does, sets that first. The package asks the platform on the method channel `com.aboutyou.dart_packages.sign_in_with_apple`. A test answers its method `performAuthorizationRequest` with a map whose `type` is `appleid`, with `identityToken`, `authorizationCode`, `givenName` and `familyName`.

SMF's CI tests the module in every app with it, in each mode of the auth role, on the real sign_in_with_apple package. A stand-in answers its method channel as the plugin does on iOS, for one user of Apple. Each request gets an ID token and a new authorization code, and only the first request of a test file gets the name and the email address, as at the first sign-in in an app. The ID tokens are test tokens: JSON Web Tokens without a signature whose payload has the issuer of Apple, the user, the address of the private relay, and the nonce of the request, which is the SHA-256 hash of the raw nonce, as Apple writes it. The mocks of the provider of the authentication take such tokens.

The test checks the request with a new raw nonce each time, the credential, the name at the first sign-in only, the outcome of each answer of Apple, the failure on every platform but iOS, that the app lists the way to sign in on iOS with `revokesOnDeletion`, and the color and the size of the icon. The test of the ways to sign in of the auth role then signs in with the credential on `firebase_auth`, and deletes the account after the session asked for a new credential. Nobody can sign in on a device, so the start check of CI has no probe for the module. See [Contributing](https://doc.saymyframe.com/contributing.md#the-roles-at-run-time).

## Choosing it

After the features, `smf create` asks "Infrastructure: which do you want?" and offers the module there:

```text
apple_sign_in — Sign in with Apple on iOS with sign_in_with_apple
```

The module requires sign-in, and `firebase_auth` is the only module that provides it, so it comes without a question, and `firebase_core` with it:

```text
Adding firebase_auth: the only provider of the authentication role, which apple_sign_in requires.
Adding firebase_core: a dependency of firebase_auth.
```

The run then asks who may use the app without an account, as for every app with sign-in. To choose the modules without the questions, here with the screens of sign-in, BLoC and tabs at the bottom:

```bash
smf create my_app -m home,sign_in,bloc,bottom_tabs,apple_sign_in
```

After generation, `firebase_core` asks whether to configure the flavor `dev`, and `firebase_auth` then asks whether to run the script that enables the ways to sign in. The script cannot enable Apple, which you enable in the Firebase console with the key of Apple; see [deleting an account](#deleting-an-account) and [Firebase](https://doc.saymyframe.com/guides/firebase.md#sign-in-methods-of-firebase-authentication). The run ends with the link to the guide of these [steps by hand](https://doc.saymyframe.com/guides/smf-create.md#steps-by-hand) and of the App ID.
