Custom scheme for native mobile apps


We are currently developing the integration of Keycloak within our native mobile applications. In the documentation we can see a section regarding Cordova apps, but not native. Is it properly supported ?

Saying that, we are able to login with an already registered user without a problem ; the problem comes with Registration workflow and especially Email Validation. To make it work, we are using custom scheme for redirectURI but we are not able to do it for baseURL and rootURL (Invalid URL error in the admin console). Why is that ?

Regarding the email validation:
When the user clicks on the email validation link from his mobile and he uses the same browser than the mobile app ; everything works fine. How does it work by the way ? The redirect uri doesn’t seem to be propagated on the validation link?
However, if he uses a different browser or validates his account from another device, on the app, the user is blocked on the “validate your email” page; and if he does refresh the page, there isn’t the “back to application” link (probably because baseURL is not set).

How is it supposed to work ?
Thanks for your advice.


I would really appreciate some help please…

We have managed to set in order to be redirected to the app . That’s good. The problem is that the response does not contains the authorisation code ! So we can’t continue the login process.

Thank you so much for any help.

Mabe this helps -> How to secure mobile apps? or

I have read in details the documentation you are pointing me to and I am actually using the AppAuth Android Library.
The problem I am having is very specific to email validation and redirect URL after validating the email in a different browser than the one I used to initialize the registration.

When I refresh the “please verify your email” page in my app browser, I get a page that say that I am connected. The back to Application link points to be to my baseURL instead of the redirectURL with the authorisation code.

How is it supposed to work please ?

After working all day on it , it seems :

1/ if we are using custom scheme in the redirect URI, after refreshing the “please verify your email” page in my app browser, I get a “back to application” link pointing to BASE URL without authorisation code. Moreover, Base URL cannot use custom scheme.

2/ if we are using https redirect URI instead of custom scheme, after refreshing the “please verify your email” page in my app browser, I get redirected directly with the correct redirect URI (with parameters) but it doesn’t open the app (but browser). It works fine when we do a normal login however. Where is the code that is called when I refresh the page ? how do you handle the redirect ?

And also : is custom scheme supported ? It is the recommanded method in the openid documentation.


We ended up setting a redirect url to a website that redirect to the mobile app with custom scheme… it is not very elegant but it works.

So my guess is that custom scheme is not supported ?

What do you mean with supported?
A custom protocol and scheme for a native app is on the OS level and has nothing to do with Keycloak.
Your native app should intercept a call made to that custom scheme.
Take a look at and especially the PKCE parts and

As you mentioned, the native app should intercept a call made to the custom scheme ; based on the fact that the redirectURI should point to that custom scheme.

It works fine with Keycloak in cases like : log in with existing user or validating email with mobile device with the same browser.
It doesn’t work if you register a new user with email validation + you open the email validation on a different device than the mobile (for example from your computer).

If redirect url is set to a scheme custom (i.e different from HTTP/HTTPS), info.ftl will not have pageRedirectUri and it will be redirected to baseUrl (which cannot use a custom scheme either) .

If redirect url is set to HTTP scheme, the redirection works fine.

That’s why we found the (durty) workaround to set in our mobile app “redirectURI” to a HTTPS webpage that redirect us to our custom scheme page…

Is it a bug or something I am not doing correctly ?

If I may ask, I have added the html file to my custom theme, under a html folder. I can access it via

Could you tell me what i3cfu refers to ? Is it subject to change ?


What version of Keycloak are you working with?
I have no idea what i3cfu is, neither does the keycloak source code.

I am working with the latest version 9.0.2.

i3cfu is probably a generated value. My company uses generated values for realm names so we get things like I don’t think Keycloak generates any values by default though, so someone must have specified that somewhere in your installation. That’s my guess.

You might find better search results if you re-frame your thinking about this. Keycloak implements the OpenID Connect specification. I see people coming on these forums and asking if they can do this or that with Keycloak. Keycloak supports OIDC, and that’s that. If you can do it with OIDC, you can do it with Keycloak. And if you ever come to the determination that “Keycloak doesn’t support X”, what you’ve really determined is that “X doesn’t support OIDC”, which these days is becoming rarer.

TL;DR: You might get better results if you expand your internet searches for OIDC help. Your problems are not specific to Keycloak.

Thank you for your response ; and thank you for taking the time.

1/ regarding i3cfu : ic3fu is not a realm name. It is part of the path for the resources that I have added in my custom theme. To be clear, in your custom scheme, you may have added css files for example in your resource folder . This resource will be made accessible on the web by Keycloak on a url that content a code . In my case it is ic3cfu . (I have made myself the installation via helm chart. ) . When running on a local docker container, I have another code ; so my assumption was that it was a generated string. But, based on which criteria? I want to understand if this code is subject to change.

2/ I probably don’t explain correctly my problem. I have no doubt that Keycloak is supporting . Our problem is on a specific case: sso with native app using redirectUrl with custom scheme + if you register a new user with email validation ; and if that user doesn’t validate his email on the mobile device. I assume it is a bug in Keycloak. I wanted to make sure that it was not a misunderstanding on our side first.