docs: improved troubleshooting and upgrading guide; got rid of NullPo…

README.md

@@ -25,10 +25,14 @@ compatible to Keycloak. Differences are as follows:
 
 See a [`Dockerfile` example](docs/README_docker_installation.md).
 
+## Upgrading your existing installation
+
+Please refer to [UPGRADE.md](UPGRADE.md). In rare cases, you are required to perform some steps to make the extension work again after an upgrade. 
+
 ## Compatibility
 
 Since this package implements internal Keycloak SPIs, there's a chance this extension breaks with a new major version of Keycloak.  
-See compatibility list below to find the version that suits your Keycloak version.
+See the compatibility list below to find the version that suits your Keycloak version.
 
 | Keycloak Version                        | Extension Version                 |
 |-----------------------------------------|-----------------------------------|
@@ -70,6 +74,10 @@ this [guide](https://github.com/klausbetz/apple-identity-provider-keycloak/wiki/
 :warning: Make sure to add the keycloak broker-URL (`https://<keycloak-url>/realms/<realm>/broker/apple/endpoint`) to your valid redirect
 URLs in your Apple Developer Account.
 
+## Troubleshooting
+
+Please refer to the [wiki](https://github.com/klausbetz/apple-identity-provider-keycloak/wiki/Troubleshooting-the-configuration-from-Apple) to figure out what's wrong.
+
 ## Token exchange
 
 :point_right: If you are unsure whether you need token-exchange or not, check out the [wiki](https://github.com/klausbetz/apple-identity-provider-keycloak/wiki/Do-you-need-token%E2%80%90exchange%3F).

UPGRADE.md

@@ -0,0 +1,6 @@
+# Upgrading Apple Identity Provider for Keycloak
+
+Since breaking changes not only occur within Keycloak, but also in this extension, it is necessary to migrate data in rare cases after an extension upgrade.
+
+### Upgrade from <1.14.0 to 1.14.0 or later
+- The field p8-Key got dropped in favor of the field Client-Secret in the Admin-UI in version 1.14.0. Please paste the p8-Key into Client-Secret instead. Otherwise you will get the error `"invalid_client"` from Apple and login does not work.

build.gradle

@@ -4,7 +4,7 @@ plugins {
 }
 
 group 'at.klausbetz'
-version '1.14.0'
+version '1.15.0'
 java.sourceCompatibility = JavaVersion.VERSION_17
 
 ext {

src/main/java/at/klausbetz/provider/AppleIdentityProvider.java

@@ -158,7 +158,7 @@ public BrokeredIdentityContext sendTokenRequest(String authorizationCode, String
         SimpleHttp.Response response = generateTokenRequest(authorizationCode, clientId).asResponse();
 
         if (response.getStatus() > 299) {
-            logger.warn("Error response from apple: status=" + response.getStatus() + ", body=" + response.asString());
+            logger.warn("Error response from apple: status=" + response.getStatus() + ", body=" + response.asString() + " Please consult the docs at https://github.com/klausbetz/apple-identity-provider-keycloak for troubleshooting");
             return null;
         }
 

src/main/java/at/klausbetz/provider/AppleIdentityProviderEndpoint.java

@@ -78,7 +78,9 @@ public Response authResponse(@FormParam(OAUTH2_PARAMETER_STATE) String state, @F
             if (authorizationCode != null) {
                 appleIdentityProvider.prepareClientSecret(appleIdentityProvider.getConfig().getClientId());
                 BrokeredIdentityContext federatedIdentity = appleIdentityProvider.sendTokenRequest(authorizationCode, appleIdentityProvider.getConfig().getClientId(), user, authSession);
-                return callback.authenticated(federatedIdentity);
+                if (federatedIdentity != null) {
+                    return callback.authenticated(federatedIdentity);
+                }
             }
         } catch (WebApplicationException e) {
             return e.getResponse();