IBM Security Access Manager for Enterprise Single Sign-On, Version 8.2.2

Signatures for frames

A frame displays multiple HTML documents in the same browser window. An iframe or inline frame, is an HTML document that is embedded inside another HTML document.

About frames

Each HTML document is called a frame. Each frame is independent of each other. The tags <frameset> and <frame> defines frames in a web page. An iframe HTML element is often used to insert content from another source, such as an advertisement, into a Web page. Use the tag <iframe> to embed another HTML document.

Frame and iframe are similar except that iframe is more flexible because you can embed another HTML document in the web page like embedding an image or any other HTML element. In a frame, you must define the structure of the framesets in a main web page. However, they are treated the same way in generating signatures.

Understand the following frame concepts before you generate web signatures for HTML elements inside another frame:

Each frame in a web page has its own instance of state engine. These different state engines can be instantiated from the same AccessProfile or different AccessProfiles depending on the URL you specified in the site signature. However, you typically group all different frame URLs into one single AccessProfile.
In your signature, root segment /child::html always refers to the document where the current state engine resides. If your state engine is loaded in an HTML page that resides in a frame, /child::html does not refer to the top-most document, but the HTML document that your state engine is in.
/child::html/parent::frame/parent::frame points you to the top-most frame. Remember that you must use two parent or frame.
To navigate to a particular document from the top-most frame, use the following signature:
```
/descendent::document[@url#...#]
```

One-level nested frame

For an ordinary one level nested frame, the main.html consists of two frame web pages, page_a.html and page_b.html

The following table provides the example signatures for a one-level nested frame:

Frame Signature

Frame	Signature
`main.html`	`<frameset cols="25%,75%"> <frame src="page_a.html"> <frame src="page_b.html"></frameset>`
`page_a.html`	`<html><body><form name="f_a"> <input name="i_a" type= "text" value="Text here"></form></body></html>`
`page_b.html`	`<html><body><form name="f_b"> <input name="i_b" type= "text" value="Text here"></form></body></html>`

main.html

<frameset cols="25%,75%">  <frame src="page_a.html">  
<frame src="page_b.html"></frameset>

page_a.html

<html><body><form name="f_a"> <input name="i_a" type=
"text" value="Text here"></form></body></html>

page_b.html

<html><body><form name="f_b"> <input name="i_b" type=
"text" value="Text here"></form></body></html>

From anywhere in the page, use the following signature to navigate to the text box in page_a.html:

/child::html/parent::frame/parent::frame/descendent::document[@url#".*page_a.*"]
/descendent::html[@tag_name="form"]/descendent::html[@tag_name="input"]

Multi-nested frame

You might experience a complicated scenario where frame page contains another frameset, such as a multi-nested frame.

In the following example, the main page contains two frames, the first frame contains page_a.html, the second frame contains page_b.html. The frame page_b.html contains a frameset with two pages: page_c.html and page_d.html.

Frame	Signature
`main page`	`<frameset cols="25%,75%"> <frame src="page_a.html"> <frame src="page_b.html"></frameset>`
`page_a.html`	`<html><body><form name="f_a"> <input name="i_a" type= "text" value="Text here"></form></body></html>`
`page_b.html`	`<frameset rows="25%,75%"> <frame src="page_c.html"> <frame src="page_d.html"></frameset>`
`page_c.html`	`<html><body><form name="f_c"> <input name="i_c" type= "text" value="Text here"></form></body></html>`
`page_d.html`	`<html><body><form name="f_d"> <input name="i_d" type= "text" value="Text here"></form></body></html>`

If you are sure that your state engine is loaded only in page_c.html, use the following signature to refer to an HTML element in page_c.html:

/descendent::html[@tag_name="input" and @name="i_c"]

If you are not sure about the frame your state engine is going to load, use the following signature:

/child::html/parent::frame/parent::frame/descendent::document[@url#".*page_c.*"]
/descendent::html[@tag_name="form"]/descendent::html[@tag_name="input"]

Note: The preceding signature is similar to the signature you use in the one-level nested signature. The parent::frame points to the top-level frame and irrespective of the depth you are in, you are going to navigate to the top-most frame.

Embedding another frame inside a web document using an iframe tag

The following table provides the example signatures. when you want to embed a main.html into another page page_a.html:

Frame Signature

Frame	Signature
`main page`	`<html><body><div>some text here</div> <iframe src= "page_a.html" height="200"></iframe></body></html>`
`page_a.html`	`<html><body><form name="f_a"> <input name="i_a" type= "text" value="Text here"></form></body></html>`

main page

<html><body><div>some text here</div> <iframe src=
"page_a.html" height="200"></iframe></body></html>

page_a.html

<html><body><form name="f_a"> <input name="i_a" type=
"text" value="Text here"></form></body></html>

In this scenario, two state engines loads, one in the top-level document, the other loaded by the page_a.html. If your state engine is at the top level on the document, use the following signature to reference to the input element:

/descendent::html[@tag_name="form" and @name="f_a"]/child::html[@tag_name="input" 
and @name="i_a" and @type="text"]

If your state engine is in the page_a.html, and if you want to reference to the HTML elements in page_a.html, do it as if there is no frame. But if you want to reference to an element in the top-level document, do the same thing as you did in frame. For example, from page_a.html, if we want to identify the div element, use the following signature:

/child::html/parent::frame/parent::frame/child::document[@url#".*main.*]
/descendent::html[@tag_name="div"]

Cross-domain sites

A cross-domain web page is when an HTML document from one frame belongs to a different domain from the HTML document from another frame.

From Web script language (such as a JavaScript embedded inside an HTML source), you cannot access another cross-domain frame document for some security reasons. However, for the AccessStudio signature framework, cross-domain site signatures work because the signature evaluation algorithm uses a different approach that bypasses this security barrier. You do not have to worry about cross-domain sites when writing frame-related signatures.

Feedback