About the MS-OFBA protocol

MS-OFBA Protocol

When using a setup of an Airlock Gateway and Airlock IAM, these components take over the complete handling of the MS-OFBA protocol. The target MS-SharePoint back-end is only accessible through the Gateway after successfully being authenticated by IAM.

MSOFBA protocol path

There are three steps required for establishing an identity using forms-based authentication between an MS-Office application as protocol client. In our case, the request is filtered through Airlock Gateway, with authentication and MS-OFBA protocol handled by Airlock IAM.

The three steps are as follows:

  • Initialization:
  • Prior to opening the document on SharePoint, the client sends a so-called protocol discovery request. This is an HTTP OPTIONS request which allows IAM to determine whether the client is a browser or an MS-Office application. This detection is header-based.
  • In the case the request is sent by an MS-Office application, IAM responds that its authentication method is forms-based authentication.
    • -IAM returns a 403 HTTP response including an X-FORMS_BASED_AUTH_REQUIRED header with an URL, which points to the authentication location.
    • -The response also includes an X-FORMS_BASED_AUTH_RETURN_URL header, with the SharePoint back-end location.
  • Negotiation:
  • As determined via MS-OFBA, IAM is capable to establish an identity via forms-based authentication. As we remember, the URL to the authentication server has been returned with the X-FORMS_BASED_AUTH_REQUIRED request during initialization.
  • Following the URL to the authentication server, the protocol client renders the returned HTML of the Loginapp.

    • Note that the duration of this step is neither deterministic nor specified by the MS-OFBA protocol. The MS-Office application will continue to follow as many redirects and refreshes to the X-FORMS_BASED_AUTH_RETURN_URL as necessary to successfully establish the identity.

  • Negotiation is successful when IAM redirects to the return-URI of the X-FORMS_BASED_AUTH_RETURN_URL header.
    • -At that time, the MS-Office application has the required role to pass Gateway mapping to the SharePoint back-end.
  • Finalization:
  • With the redirection of the MS-Office application to the return-URI, the MS-Office application assumes that the identity has been successfully established.
  • Subsequently, the MS-Office application proceeds with accessing and opening the document from the SharePoint back-end.

    • Note that the process for actually establishing the user’s identity is not specified by the MS-OFBA protocol.

Client-type detection by User Agent HTTP Header Pattern

The User Agent HTTP Header Pattern detects non-browser types of clients such as MS-Office applications.

  • This can be achieved by:
  • X-FORMS_BASED_AUTH_ACCEPTED HTTP header.
  • other configured user agent regular expression.
  • If the request from the client has been detected as a non-browser type:
  • The forms-based authentication required response of the IAM is returned as part of the above Initialization step.
  • If the client is considered to be a browser:
  • An HTTP 302 redirect to the configured redirect url is returned.
  • In addition, a location parameter is added to the redirect location, pointing to the initially accessed URL on the Gateway.

    • Therefore, the effect of accessing this target application with a browser is the same as if the authentication flow on the Gateway mapping would have been set to Redirect instead of One-Shot.