Breaking Changes... API URLs for online tenants
In the worst-case scenario, an application may have hardcoded a tenant API URL as "https://online.superoffice.com/[Cust00000]/api/v1," which may currently be functional. However, we have consistently advised developers to use either the WebApi_Url or NetServer_Url, which are issued as claims in the OpenID Connect id_token.
In light of upcoming infrastructure changes aimed at improving load balancing and performance, the API URLs for online tenants are becoming more dynamic. The plan is to remove the API URL claims from the id_token and now are recommending all applications use the state URL to retrieve a tenant's API URL.
The state URL follows the format:
https://[environment].superoffice.com/api/state/[Cust00000]Here, the "environment" parameter is set to either "sod," "qaonline," or "online," representing development, stage, or production environment, respectively. The "Cust00000" parameter is the unique identifier for the tenant.
How often should applications check the state URL for changes? API URLs will typically be invalided during the evening during maintenance, which is posted on status.superoffice.com, however it may also depend on how much traffic an API endpoint receives.
For more information, please refer to the documentation available at:
https://docs.superoffice.com/en/developer-portal/best-practices/tenant-status/index.html
We plan to enable these changes in the SOD environment moving forward. This will allow you to test your applications' resiliency and ensure it continues to function and operate before pushing any required changes to production. We expect to roll out these changes to production on November 17th.
Question and/or comments are welcome.
Alle Svar (12)
Hi,
Thanks for the early heads-up!
Is there any timeline about when the change for blocking requests to the wrong tenant endpoint (as announced here for SOD) will be in production? or will this be done together whis this change at the end of June?
Also how does the work for the NetServer Remote URL, currently you can get the version you should use (services88 for example) for a specific tenant from the id_token claims, the tenant state api only contains the web api endpoint. (Yes the web/rest api is the preferred api now, but we have existing custom apps)
Hi Tony, thanks for the heads-up. In all our products we currently use the claims to get the proper endpoint, so we do expect quite some impact as it's used and tunneled a bit differently in various processes and parts.
So we give priority to making this change, yesterday we've asked a SOD tenant to switch to the new mechanism. However I experience the URL still being available as part of the JWT token for normal superID callback and system user endpoint as well, also after a move of the tenant to sod2.
I imagine this might be part of the global SuperID service, but that's guessing. Can you explain a bit more on what will be effective when?
To be clear, we are aware what we need to change. But for Q&A I want to experience what could/will happen, so please break it in SOD ;)
Hi Tony,
I checked the latest commit for the AspNet.Security.OAuth.SuperOffice package and it seems that now the user info endpoint URL is built using the Web API URL that comes from the claims retrieved from the id_token.
If the URL claims are going to be removed from the id_token, shouldn't this package also retrieve the API URL from the tenant status service instead?
Hi, thanks for the info.
Like David asked, will also the NetserverURL be removed from the id_token? Two of our apps use similar code as in this DevNet example; https://github.com/SuperOffice/SuperOffice.DevNet.Online/blob/18be2408b97816af46beadf97ffaa7c5ba04ddc5/Source/SuperOffice.DevNet.Online.Login/Helpers/SuperOfficeAuthHelper.cs#L353
Hi,
Like David and Frode asked - our .NET Framework apps also uses the same solution.
Will the NetServerUrl be available in id_token claims after the flip?
For our .NET Core apps we use AspNet.Security.OAuth.SuperOffice.
Any ETA for the user info endpoint fix?
OK,
First let me state that the webapi_url and netserver_url claims will stay in the id_token - at least for the foreseeable future. The state endpoint will provide the same API URL, so if anyone has already changed their codebase, things will work as expected.
Whenever this issue comes up again, we will give everyone ample time to adapt and migrate to whatever the solution will be then.
No Gunnar, If you are referring to the fix in the AspNet.Security.OAuth.SuperOffice package, that is already posted. As for SuperOffice Online OpenIdConnect, unfortunately providing the UserInfo endpoint is again delayed.
Just noticed that when searching for the error code we return, I can't find this thread.
So, if you get HTTP status code 421 misdirected request - then this is why. The rule is currently only in effect in SOD.superoffice.com. From next week, we will enable it in Stage (qaonline.superoffice.com), then production (online.superoffice.com) shortly after
Any API call going to the wrong subdomain will return HTTP 421 Misdirected Requests: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/421
Use the tenant status to verify where your customer is located: https://docs.superoffice.com/en/apps/tenant-status
Just an update, this change is now planned to be implemented in production (online.superoffice.com) end of this week (October 20th 2023)
Latest status is that this will be implemented in production on Friday this week! Meaning November 17th after 22.00.
If you get Http status code 421 in production after this date, then make sure you check the tenant status page to see which public endpoint the customer is located on.
https://online.superoffice.com/api/state/Cust12345
like in my example here Cust6647 is currently on online3