Informing caller additional setup required before continuing

Need help to understand standard flow for handling additional-information-required scenario.

Context: We have a number of product implementations, all integrated with a central single sign-on server. A registered customer can opt to start using new products on-demand. But some of the products require the customer to carry out some one-off setup steps before they use the product - these steps are only needed the very first time of using the product.

Consider a customer is on the page https://product-abc.ourdomain.com. And now clicks on a link within that product something like 'do something (note, this will redirect you to product-xyz)'. At this point the customer is redirected to https://product-xyz.ourdomain.com. Here we want to detect whether the customer is using the product for the first time and if yes, redirect the user to a setup page wherein we can prompt them to supply the product-specific additional information. On the other hand, if the customer is already configured for the product, they will just navigate into the product page and continue using it.

I wanted to know if there is something similar to the 401 Unauthorized flow to handle this. With authentication flow,

A client tries accessing a protected resource.
The server checks the caller has requisite authentication and if not, returns 401 Unauthorized status code with additional details in the WWW-Authenticate header.
The client carries out authentication - say by integrating with the central single sign-on server - and then reattempts the original request, this time succeeding.

I'm wondering if there is a similar flow like,

A client tries accessing a protected resource.
The server checks whether the client is OK to use it. In our case, if its the first time a customer is accessing the product, this check will determine additional setup is required. For example, the client has to supply us with their correspondence address so that we can set up a data tenancy for the specific customer. Here I would like to return a HTTP status code, say, 4xx Setup Required with additional information in a header, say, WWW-SetupInfo.
Once the initial-setup flow is completed, the customer will be redirected to the main product and carry on using it.

The nearest status code that seems to match my usecase is 402 Payment Required, but product-xyz doesn't need any specific subscription or payment. We just need some product-specific additional information to do the initial configuration.

I can handle it by doing custom implementation using 3xx redirect but I was wondering if there is a better way of handling it.

Thanks for any pointers.

Solution

Unless you are using basic-authentication, you don't want to use a 401 Unauthorized" status code with a WWW-Authenticate` header. This built in mechanism in browsers has very limited functionality:

Always prompts for user name and password, with no mechanism to customize the process either with look and feel, or custom workflows. You say you want to use single-sign-on. 401 Unauthorized is not compatible with that.
Has no log-out mechanism
Has no session timeout mechanism

As a result, almost all websites use logins based on forms and cookies. If somebody isn't logged in, you should use a 302 Temporary redirect to the login page.

Similarly, if somebody doesn't have their initial setup completed to use a particular page, you would not use a special HTTP status. You would either present them with the a 200 OK page with the form asking for the data you need, or use a 302 Temporary redirect to take them to that form on another URL.