← Back to plugin index

MS-OFBA One-Shot Target Application
Description
Microsoft Office Forms Based Authentication (MS-OFBA) One-Shot Target Application
Note: This target application allows to authenticate HTTP requests based on the original HTTP request sent by the client to Airlock WAF. Therefore, this plugin only works with Airlock Gateway (WAF) Settings being configured.

MS-OFBA Protocol
The MS-OFBA protocol provides a mechanism by which Microsoft Office clients (e.g. Word, Excel, ...) can establish an authenticated session with a server or gateway like Airlock WAF. The three steps for establishing an identity using forms based authentication between a protocol client and a protocol server are as follows:

  1. Initialization: Prior to opening the document on the remote server, the client sends a so called protocol discovery request, which is a HTTP OPTIONS request allowing the server to determine whether the client is a browser or not, based on the headers sent (see Browser vs. Nonbrowser Clients below). In the case of an nonbrowser client, this target application responds that its authentication method is forms based authentication, by returning a 403 HTTP response including a X-FORMS_BASED_AUTH_REQUIRED header with a URL, pointing to the location to which the client should navigate to authenticate. The response also includes a X-FORMS_BASED_AUTH_RETURN_URL header, which is the location to which the protocol server will redirect the user after a successful authentication.
  2. Negotiation: Having determined that the protocol server is capable of establishing an identity by using forms based authentication, the protocol client renders the HTML returned from the request to the remote location provided by the server in step 1 (X-FORMS_BASED_AUTH_REQUIRED header). Note that the duration of this step is neither deterministic nor specified by this protocol. The reason is that the client will continue to follow as many redirects and refreshes as necessary to successfully establish the identity, until the server redirects to the return URI provided by the server in step 1 (X-FORMS_BASED_AUTH_RETURN_URL header)
  3. Finalization: After the protocol server redirects the protocol client to the return URI, the protocol client assumes that the identity has been successfully established and reissues the original request from step 1. Note that the process for actually establishing the user's identity is not specified by this protocol.

Browser vs. Nonbrowser Clients
If the request from the client contains a X-FORMS_BASED_AUTH_ACCEPTED HTTP header or the User-Agent header matches the configured user agent regular expression, the client is considered to be a nonbrowser client. In this case, a forms based authentication required response is returned as described in the Initialization step of the protocol.
In the other case, where the client is considered to be a browser, a 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 WAF. Therefore, the effect of accessing this target application with a browser is the same as if the Authentication Flow on the WAF mapping would have been set to Redirect instead of One-Shot.

Type name
MsOfbaOneShotTargetApplication
Class
com.airlock.iam.authentication.application.configuration.oneshot.MsOfbaOneShotTargetApplication
May be used by
One-Shot Authentication Settings One-Shot Authentication Settings
Properties
URL Pattern (urlPattern)
Description
The URL pattern (regular expression pattern) to identify this target application.

The first pattern (in the list of target applications) that matches the forward URL is used.
The matching is case-insensitive.

The URL pattern is ignored for the default target application.

Attributes
RegEx
Mandatory
User Agent HTTP Header Pattern (userAgentPattern)
Description
To be recognized as a nonbrowser client that supports the MS-OFBA protocol, the protocol client MUST specify either a X-FORMS_BASED_AUTH_ACCEPTED header or a user agent string in an HTTP OPTIONS request.

IAM responds with a Forms Based Authentication Required response, as specified in the plugin description, iff

  • The X-FORMS_BASED_AUTH_ACCEPTED header field is present with a value of "t" or "f" (otherwise it is ignored) or
  • The request contains a User-Agent HTTP header that matches this regular expression pattern.
Attributes
RegEx
Optional
Default value
Microsoft Office(.*)
Browser Redirect URL (redirectUrl)
Description
In case the client is considered to be a browser, the MS-OFBA One-Shot Target Application redirects the client to this URL. In addition, a location parameter, which corresponds to the initially accessed URL on the WAF, is added to the redirect location. Therefore, the effect of accessing this target application with a browser is the same as if the Authentication Flow on the WAF mapping would have been set to Redirect instead of One-Shot.
Attributes
String
Optional
Default value
/auth/check-login
Example
/auth/check-login
Example
https://myhost.com/iamPath/check-login
MS-OFBA Authentication URL (msofbaAuthUrl)
Description
The URL which will be returned to the client as X-FORMS_BASED_AUTH_REQUIRED HTTP header value in the MS-OFBA response. It MUST point to an HTTP-based server. A Location URL parameter, that points to the configured MS-OFBA Success URL will be added to this URL automatically. Therefore, the final MS-OFBA Authentication URL as received by the client wil look similar to https://myhost.com/iamPath/check-login?Location=https%3A%2F%2Fmyhost.com%2Fauth%2Fsuccess.
Attributes
String
Mandatory
Example
https://myhost.com/iamPath/check-login
MS-OFBA Success URL (msofbaSuccessUrl)
Description
The URL which will be returned to the client as X-FORMS_BASED_AUTH_RETURN_URL HTTP header value in the MS-OFBA response. It MUST point to an HTTP-based server and accessing the URL has to result in a HTTP 200 response. For this, the IAM Success Servlet, deployed under /<iam-deployment-path>/msofba-success can be used.
Attributes
String
Mandatory
Example
https://myhost.com/auth/msofba-success
MS-OFBA Display Size (msofbaDialogSize)
Description
Optional value of the X-FORMS_BASED_AUTH_DIALOG_SIZE HTTP header as returned to the client in the MS-OFBA response. This value determines the size of the window which is opened by the client when accessing the MS-OFBA Authentication URL. It must follow the format <width in pixels>x<height in pixels>. If the size of the dialog box is not specified, the value "660x495" is used by the protocol client.
Attributes
String
Optional
Example
800x600
Location Parameter Name (locationParameterName)
Description
The name of the request parameter telling the authentication application what page the user requested when he/she was redirected to the authentication application.
Attributes
String
Optional
Default value
Location
YAML Template (with default values) 

type: MsOfbaOneShotTargetApplication
id: MsOfbaOneShotTargetApplication-xxxxxx
displayName: 
comment: 
properties:
  locationParameterName: Location
  msofbaAuthUrl:
  msofbaDialogSize:
  msofbaSuccessUrl:
  redirectUrl: /auth/check-login
  urlPattern:
  userAgentPattern: Microsoft Office(.*)