Apple Identity Provider for Keycloak

Once the preview features are enabled, you must configure Keycloak permissions to allow the Apple identity provider to exchange tokens. This involves two main stages: configuring the target client and configuring the Apple Identity Provider itself.

Stage 1: Configure the target client

1. Create a client: Ensure you have a client configured in Keycloak (you can use a new one with default settings or an existing one).
2. Enable permissions: Go to your client settings and enable permissions.
3. Create token-exchange permission: Create a new permission of type token-exchange on that client.
4. Define Policies: In the Policies field of the new permission, create a policy that allows the exchange.

Stage 2: Configure the Apple Identity Provider

1. Enable permissions on Apple IDP: Navigate to the Apple Identity Provider settings and enable permissions.
2. Create token-exchange permission on Apple IDP: Create a specific token-exchange permission directly on the Apple Identity Provider to authorize the exchange process.

To run Keycloak with the Apple Identity Provider extension pre-installed, use a multi-stage Dockerfile. This approach builds an optimized Keycloak image that includes the provider, enables health and metrics endpoints, enables the token-exchange and admin-fine-grained-authz features, and configures PostgreSQL as the database.

Note that the example Dockerfile uses version 1.7.0 of the Apple Identity Provider. Ensure you update the version in the ADD command to match the version you intend to use.

FROM quay.io/keycloak/keycloak:22.0.1 as builder

ENV KC_HEALTH_ENABLED=true
ENV KC_FEATURES=token-exchange,admin-fine-grained-authz
ENV KC_DB=postgres
ENV KC_HTTP_RELATIVE_PATH="/auth"

# Install custom providers
# Apple Social Identity Provider - https://github.com/klausbetz/apple-identity-provider-keycloak
ADD --chown=keycloak:keycloak https://github.com/klausbetz/apple-identity-provider-keycloak/releases/download/1.7.0/apple-identity-provider-1.7.0.jar /opt/keycloak/providers/apple-identity-provider-1.7.0.jar

# build optimized image
RUN /opt/keycloak/bin/kc.sh build 

FROM quay.io/keycloak/keycloak:22.0.1

COPY --from=builder /opt/keycloak/ /opt/keycloak/
WORKDIR /opt/keycloak

ENTRYPOINT ["/opt/keycloak/bin/kc.sh"]

To set up the provider, log into the Keycloak admin console, add Apple as a new Identity Provider, and fill in the following configuration options:

Critical Requirement: You must add the Keycloak broker URL to your valid redirect URLs in the Apple Developer Account: https://<keycloak-url>/realms/<realm>/broker/apple/endpoint

The following parameters are used when performing a token exchange via the Keycloak /token endpoint for the Apple Identity Provider.

### Using Apple ID-Token (Recommended)

| Parameter            | Description |
|----------------------|-------------|
| `client_id`          | the client id of your Keycloak client |
| `grant_type`         | `urn:ietf:params:oauth:grant-type:token-exchange` |
| `subject_token`      | ID-Token from Apple |
| `subject_issuer`     | `apple` (the name of the social provider in keycloak) |
| `subject_token_type` | `urn:ietf:params:oauth:token-type:id_token` |
| `user_profile`       | `{ "name": { "firstName": string, "lastName": string }, "email": string }` optional. The JSON string that Apple sends on the first login |

### Using Apple `authorization_code`

| Parameter          | Description |
|--------------------|-------------|
| `client_id`        | the client id of your Keycloak client |
| `grant_type`         | `urn:ietf:params:oauth:grant-type:token-exchange` |
| `subject_token`      | `authorizationCode` from Apple |
| `subject_issuer`     | `apple` (the name of the social provider in keycloak) |
| `user_profile`       | `{ "name": { "firstName": string, "lastName": string }, "email": string }` optional. The JSON string that Apple sends on the first login |
| `app_identifier`   | the ServiceID/BundleID the authorization was invoked with. You can omit this field if the ServiceID in Keycloak is the same as the BundleID |
| `app_redirect_uri` | the Redirect URI the authorization was invoked with (since `1.16.0`) |

Because this extension implements internal Keycloak SPIs, it is sensitive to Keycloak version changes. Use the following mapping to ensure compatibility:

Important Notes:

• Keycloak v21.X.Y: The Admin UI does not display additional properties like Team ID or Key ID. You must use external configuration tools like terraform or keycloak-config-cli to configure the provider.
• Keycloak v19 and v20: You must switch to the old Admin UI to use this extension effectively.