Page Comparison

...

1. modify the caller authentication workflow in BSN.cloud API and resolve Person Claims Identity based on Person Access Tokens issued by KeyCloak;

2. modify the request authorization workflow in BSN.cloud API and replace the OAuth2 Scope-based authorization by the identical custom check based on Authorization Scope calculated in the same way;

   • in result of these changes the updated client applications will get the ability to retrieve the Person membership information using the existing GET ~/2022/06/REST/Self/Networks/ and GET ~/2022/06/REST/Self/Users/ methods of BSN.cloud Self API;

3. implement the new /2022/06/REST/Self/Session/ resource in BSN.cloud Self API, which has the following methods:

   1. OPTIONS: for handling the pre-flight requests from browsers;

   2. GET: for retrieval of the complete set of attributes defined in the context of the current Person Session. It must provide at least the following kinds of responses:

      1. having the 200 HTTP Status Code and application/json representation of the Session Context Structure instance which includes at least the [Nullable<NetworkInfo>] Network, [string] AuthorizationScope, [DateTime] ExpirationDate, [DateTime] LastModifiedDate properties;

      2. having the 401 HTTP Status Code when the provided Person Access Token is invalid and Session ID cannot be retrieved;

      3. having the 410 HTTP Status Code when the provided Person Access Token is valid but the Session with resolved ID has been invalidated;

      4. having the 5xx HTTP Status Code and the optional Retry-After HTTP header in case of transient server-side errors;

4. implement the new /2022/06/REST/Self/Session/{key}/ resource in BSN.cloud Self API, which has the following methods:

   1. OPTIONS: for handling the pre-flight requests from browsers;

   2. GET: for retrieval of the single attribute value defined in the context of the current Person Session and addressed by a Key. The available Keys are defined statically on BSN.cloud Self API side and limited to Network and AuthorizationScope. It must provide at least the following kinds of responses:

      1. having the 200 HTTP Status Code and application/json representation of the requested attribute value, which is either [Nullable<NetworkInfo>] for Network attribute or [string] for AuthorizationCode attribute. It is also desirable to provide the Last-Modified HTTP header value equal to the timestamp of the current attribute value assignment;

      2. (desirable) having the 304 HTTP Status Code when the provided If-Modified-Since HTTP header value matches the timestamp of the current attribute value assignment;

      3. having the 401 HTTP Status Code when the provided Person Access Token is invalid and Session ID cannot be retrieved;

      4. having the 410 HTTP Status Code when the provided Person Access Token is valid but the Session with resolved ID has been invalidated;

      5. having the 5xx HTTP Status Codes and the optional Retry-After HTTP header in case of transient server-side errors;

   3. PUT: for new values assignment to the attribute addressed by a Key. It must provide at least the following kinds of responses:

      1. having the 204 HTTP Status Code and no payload in case of successful execution. It is also desirable to provide the Last-Modified HTTP header value equal to the timestamp of this operation execution on BSN.cloud Self API side;

      2. having the 400 HTTP Status Code and application/problem+json error representation in case of invalid request and any of business rules violation, including the following:

         1. a Network having the specified Id or Name does not exist;

         2. a Network having the specified Id or Name has the Status property set to "Suspended";

         3. a Person who owns the provided Access Token is not a member of a Network having the specified Id or Name;

         4. the Status of a Person in a Network having the specified Id or Name is set to "Disabled";

      3. having the 401 HTTP Status Code when the provided Person Access Token is invalid and Session ID cannot be retrieved;

      4. having the 410 HTTP Status Code when the provided Person Access Token is valid but the Session with resolved ID has been invalidated;

      5. (desirable) having the 412 HTTP Status Code when the provided If-Unmodified-Since HTTP header value does not match the timestamp of the current attribute value assignment;

      6. having the 5xx HTTP Status Codes and the optional Retry-After HTTP header in case of transient server-side errors.

According to the fact that Session ID claim value is retrieved from the Person Access Token metadata it does not make sense to call the GET ~/2022/06/REST/Self/Session/ and GET ~/2022/06/REST/Self/Session/{key}/ methods multiple times providing the same Person Access Token. In order to indicate and reduce the chance of that these methods may also set the Cache-Control HTTP header with public; max-age={TTL} value based on the remaining validity period of the provided Person Access Token. In addition to that BSN.cloud Self API may maintain an in-memory cache of these method responses. Given the fact that these methods are expected to be invoked only as a part of existing Person/User-driven workflows their invocation rate must be not higher than any other BSN.cloud Admin/Main/Self API method.

The OAuth2 Tokens and Session invalidation on user sign out must be performed only by KeyCloak as the owner and maintainer of this information, so the implementation of that endpoint is not a part of this task. BA:con and other client applications will be authorized to call KeyCloak API for this purpose and it fire an integration event for other services in case of success.