What should WWW-Authenticate contain when a session has expired in an OpenID Connect setup?

Question

Scenario:

app.com has delegated authentication to openid-connect.provider.com, meaning unauthenticated users are redirected to the external provider for signing in if they don't have a valid session. Once that has happened they get a session cookie on app.com of some duration.

While the user-flow is fine, I was wondering what to do about API requests? The spec says that you if you return HTTP 401 UNAUTHORIZED it needs to be accompanied by a WWW-Authenticate header that presents an authentication scheme to the client.

So what should app.com return in case of a 401?

I see bits and pieces indicating OAuth, but I guess that pertains to the external provider of the login, not the application itself (app.com)?

Example:

 HTTP/1.1 401 Unauthorized
 WWW-Authenticate: Bearer realm="example",
                   error="invalid_token",
                   error_description="The access token expired"

The above does not seem right, since the app.com server doesn't use any access tokens in the oauth sense, just a plain session cookie for the local session.

Answer 1

Redirecting to OIDC login when session cookie expires is a practice widely used by UI fronted applications. Regarding the cookie used here, I believe it has a correlation to access token obtained by OIDC flow (ex:- cookie life time matching access token life time).

Regarding API access, I believe the mentioned API use bearer token usage as defined through RFC6750. This RFC define how to use token in subsequent protected API calls. One important part of it is The WWW-Authenticate Response Header Field section which define what to do when token is invalid or expired. The answer you found and the example you mention in the question correlates to explanation of the RFC recommendations.

I think problem boils down to how you authenticate against your API. If your API follow bearer token usage, then adhere to your example. Use HTTP status code along with WWW-Authenticate. This will bring spec-compliance.

But if there's a custom authentication mechanism (ex:- cookie), then it is out of scope for the spec. But you can have a JSON response from API with error details (ex:- Http code, cause, description and a correlation id for debugging). I would say WWW-Authenticate header is optional in such situation.