Mobile usage - Ionic / Capacitor

[javialon26]

Hey, nice initiative, it's great to have modern options because keycloak-js is heavy and will be deprecated. Thanks.

Do you consider the possibility of adding adapters to use the library in other contexts, like mobile apps? In this case, we need to open an in-app browser instead of redirecting the user. I have created an adapter for Keycloak-JS for Capacitor, using the Capacitor App plugin (listener for app URL open) and the Capacitor Browser (listener for browser closed by user) but it's something internal.

Let me know what's are your thoughts.

[garronej]

Hello @javialon26,

Thanks!

At the moment this library makes the assumption that it is being run in a browser environement and no effort has been made to support other runtime.
It is at the moment and OIDC client for Single Page Web Application.

I'm open to contribution but I don't have any experience with Ionic. I don't know exactly what would need to be abstracted away to make this work.

[javialon26]

Hi @garronej, sorry for my late response.

Supporting mobile apps like Ionic (which is essentially a web app inside a webview; everything that works on the web should work here) requires some abstraction:

Redirection Phase:
When the user is redirected to the auth server, it must open a browser using the Capacitor Browser plugin, which offers more functionality than window.open but has a simpler API.

Callback Handling:
The application is always in the background when the user is presented with the auth server in the browser (opened in the foreground). Once the authentication is completed, the browser closes, and the application comes to the foreground again. At this moment, the only option to handle the callback is using the Capacitor App plugin, which allows us to react to an incoming URL with the following listener. The main difference here is that the application never restarts; it is just waiting for the listener.

Keycloak-JS has custom adapters to cover this, but some cases can't be covered due to the lack of access to more internal APIs from the adapter, as mentioned in keycloak/keycloak#25736.

Thanks

[garronej]

Hello @javialon26,

Thanks for the details!
Right now, we’re focusing on supporting TanStack Start and Next.js.
We can look into Ionic afterward, but that would be a matter of months.

[mariomurrent-softwaresolutions]

Hi @garronej, sorry for my late response.

Supporting mobile apps like Ionic (which is essentially a web app inside a webview; everything that works on the web should work here) requires some abstraction:

Redirection Phase: When the user is redirected to the auth server, it must open a browser using the Capacitor Browser plugin, which offers more functionality than window.open but has a simpler API.

Callback Handling: The application is always in the background when the user is presented with the auth server in the browser (opened in the foreground). Once the authentication is completed, the browser closes, and the application comes to the foreground again. At this moment, the only option to handle the callback is using the Capacitor App plugin, which allows us to react to an incoming URL with the following listener. The main difference here is that the application never restarts; it is just waiting for the listener.

Keycloak-JS has custom adapters to cover this, but some cases can't be covered due to the lack of access to more internal APIs from the adapter, as mentioned in keycloak/keycloak#25736.

Thanks

Any updated on when this will be exposed?

[garronej]

Hello @mariomurrent-softwaresolutions,

Thanks for your interest!
My last message was less than a week ago. I'm still working on TanStack Start / Next.js support, and it's currently my top priority.
If you'd like to help prioritize it, consider sponsoring: https://github.com/sponsors/garronej

[topdev-spetermann]

Hello @garronej,

we also need Capacitor support and are already working on an adapter mechanism for your great library. If it’s okay with you, I would submit a pull request in the coming weeks to discuss the approach, as some changes are needed in the core functionality to fit Capacitor specifics. We will try to implement it without introducing breaking changes for existing users of the library. I would explain each change and why it’s needed, and I’d appreciate your feedback once we have a first draft.

Please let me know if submitting a pull request is an option, or if we’ll have to use a fork in our project instead.

[garronej]

Hello @topdev-spetermann,

Thank you for your willingness to contribute.
I'll review a PR of course. I can't guarantee it will be merged though.

Maybe you could describe your strategy before submitting the PR. It's easier to discuss idea than specific implementation.

[topdev-spetermann]

Hey @garronej,

essentially, besides some smaller individual adjustments, two core changes are necessary

1. Configurable async storage - localStorage can be cleared by OS updates/cache cleanup in capacitor apps, breaking session restoration. Added optional storageAdapter parameter so users can plug in Capacitor Preferences, SecureStorage, or any async storage.

2. Custom navigator - Mobile apps use in-app browser + deep links instead of redirects. Added optional navigator parameter with event-based callback handling (Capacitor uses Browser plugin + appUrlOpen event).

We hide the remaining adjustments under an optional isNativeApp parameter to adapt certain checks that aren't suitable for Capacitor apps, e.g. redirect URL as a deep link can differ from the web view origin.

Both default to browser behavior - no breaking changes.

[topdev-spetermann]

Hi @garronej,

Thank you for your willingness to review. I apologize in advance - we really need this Capacitor support for our project and didn't want to maintain a separate fork, so we've already submitted the PR. I hope that's okay. I'm happy to adjust based on your feedback or discuss any changes you'd prefer.

Best regards