Access Manager Authentication Module and UI 102


由於自動中翻英的平台對我寫的中文不太"友善",我決定改以英文來分享較技術性的內容。

Hope you have read the 101 article regarding Access Manager (OpenSSO) Authentication Module and UI. This article go further to dig into the Callback XML and corresponding HTML display. The information here is purely from my own test, if anything incorrect, please drop me a comment or send email to me directly (You should know how to get my email from my PGP Key ID).

Authentication Module Callback XML and coressponding HTML display

Take a look at a Authentication Module Callback XML file such as LDAP.xml. You can see a few <Callbacks> elements in the <Module> root element. Each <Callbacks> element represents a HTTP response to user browser and can have various number and type of callback elements. Rendered by a template JSP, the NameCallback, PasswordCallback, ChoiceCallback, and ConfirmationCallback in a Callbacks element will result in HTML elements in one page; Other callbacks such as HttpCallback and RedirectCallback will result in non-200 HTTP response. Out of box, HttpCallback is used by HTTPBasic and Windows Desktop Authentication Module which send HTTP 401 (Unauthorized) to browser to trigger HTTP Basic/Challenge-Response authentication interaction. The RedirectCallback ....is still a mystery to me.

According to the DTD file Auth_Module_Properties.dtd, a <Callbacks> element may have the following attributes:

  • length: integer, should be the number of callback elements in this <Callbacks> element. ie the number of chidren.
  • order: integer, the order number of this <Callbacks> element in the authentication module. The one with order=1 will be automatically picked and displayed by Access Manager when a login request hit the module first time.
  • timeout: "Callback" means server needs "feedback" from user to continue the login process. But what if the user never reply to Access Manager ? How long should we keep his authentication context on server ? A default 120 seconds count down starts at each <Callbacks> UI display. So when a lazy end user submit his callbacks 2 minutes after the page shown, he will be told the session was expired. This is not the SSO Session because he's not login yet. During an authentication process, there is an Authentication Context object created on server side and being kept traced by AMAuth cookie.
  • header: this is the text title on the <Callbacks> page. Like the message "This Server uses LDAP Authentication" on LDAP login page. It is not necessary a static text. In default LDAP module, this header message is altered on the fly to show how mucht time left before password expiration (see source code LDAP.java). AM replaces #REPLACE# string in the LDAP.xml. This attribute will be insert into HTML content, so you can use HTML tag in it and remember to escape "<" and ">".
  • template: a JSP template file name. If not assigned, AM will try to use "Login.jsp" in the same file directory.
  • error: true or false, optional. Default is false. Set this attribute to true when you want to show error message to end user and DO NOT NEED his feedback. Similar to throw LoginException in process( ), the subsequence <Callbacks> will not execute.

Let's dig into the six type of callback elements and what they will be rendered by the default Login.jsp template. Auth_Module_Properties.dtd tells us all the information.

Type Allowed Attributes Allowed Elements
NameCallback

isRequired (true|false)

Prompt
PasswordCallback

isRequired (true|false)
echoPassword (true|false)

Prompt
ChoiceCallback isRequired (true|false)
multipleSelectionsAllowed (true|false)
( Prompt
, ChoiceValues)
ConfirmationCallback None OptionValues
HttpCallback None

( HttpHeader
, Negotiation
, HttpErrorCode)

RedirectCallback method (get|post)

( RedirectUrl
| RedirectData\*
| RedirectStatusParam
| RedirectBackUrlCookie)


Remember, Callback XML file only specifies the skeleton of callback field set, not the HTML presentation. It is Callback UI template's (JSP's) job to produce the final HTML tags. You certainly can create and assign your own template JSP (by using template attribute) for each <Callbacks>, but I don't think many people do so. In all my deployments, template is not customized and default Login.jsp is used everywhere. Once there is a need to change template, I suggest you not to modify Login.jsp directly but create a new one with different name. Login.jsp is too generic to be hacked without side-effect.

The following tables show the callback xml and the corresponding HTML display rendered by Login.jsp.


NameCallback (rendered to INPUT type=textbox)

<NameCallback>
<Prompt>First callback:</Prompt>
</NameCallback>

<NameCallback isRequired="true">
<Prompt>Second callback:</Prompt>
</NameCallback>

NOTE: The slight difference between isRequired=true or false is a leading \* symbol.


PasswordCallback (rendered to INPUT type=password)

<PasswordCallback>
<Prompt>Third callback:</Prompt>
</NameCallback>

20070912-1-3.JPG

<PasswordCallback isRequired="true">
<Prompt>Fourth callback:</Prompt>
</NameCallback>

20070912-1-4.JPG

<PasswordCallback isRequired="true"
echoPassword="true"
>
<Prompt>Sixth callback:</Prompt>
</NameCallback>

20070912-1-6.JPG

NOTE: Login.jsp does NOT recognize echoPassword, it always render a PasswordCallback to
<INPUT type="password"..>. Is it a bug ??

ChoiceCallback (rendered to RADIO)

<ChoiceCallback order="1">
<Prompt>Seventh callback:</Prompt>
<ChoiceValues>
<ChoiceValue>
<Value>Choice 1</Value>
</ChoiceValue>
<ChoiceValue isDefault="true">
<Value>Choice 2</Value>
</ChoiceValue>
<ChoiceValue>
<Value>Choice 3</Value>
</ChoiceValue>
</ChoiceValues>

</ChoiceCallback>

20070912-1-7.JPG

<ChoiceCallback order="1"
multipleSelectionsAllowed="true">
<Prompt>Eighth callback:</Prompt>
<ChoiceValues>
<ChoiceValue>
<Value>Choice 1</Value>
</ChoiceValue>
<ChoiceValue isDefault="true">
<Value>Choice 2</Value>
</ChoiceValue>
<ChoiceValue>
<Value>Choice 3</Value>
</ChoiceValue>
</ChoiceValues>

</ChoiceCallback>

20070912-1-8.JPG

NOTE: Login.jsp does NOT recognize multipleSelectionsAllowed, it always render a ChoiceCallback
to Radio box (Single Selection). Is it a bug ??

ConfirmationCallback (rendered to java script, run onLoad at client side to create HTML button)

<ConfirmationCallback order="1">
<OptionValues>
<OptionValue>
<Value>Option 1</Value>
</OptionValue>
<OptionValue>
<Value>Option 2</Value>
</OptionValue>
</OptionValues>
</NameCallback>

20070912-1-9.JPG


The following tables show the callback xml and the corresponding HTTP response. Login.jsp do nothing with HttpCallback and RedirectCallback.

HttpCallback

<HttpCallback>
<HttpHeader>Authorization</HttpHeader>
<Negotiation>WWW-Authenticate:BASIC realm="basic_realm"</Negotiation>
<HttpErrorCode>401</HttpErrorCode>
</HttpCallback>

Response HTTP 401 (Unauthrozied) with the following headers:

WWW-Authenticate:BASIC realm="basic_realm"

starts Http basic authentication handshake, the AM HTTP Basic Module uses this callback

<HttpCallback>
<HttpHeader>Authorization</HttpHeader>
<Negotiation>WWW-Authenticate:Negotiate
</Negotiation>
<HttpErrorCode>401</HttpErrorCode>
</NameCallback>

Response HTTP 401 (Unauthrozied) with the following headers:

WWW-Authenticate:Negotiate

starts Http chanllenge-response authentication handshake, the AM Windows Desktop Module uses this callback.

RedirectCallback

RedirectCallback is actually a black box to me and nothing can put here. If you know how it could be used, please let me know.


About Localization

AM leverage Java internationalization feature and allow appropriate message display according to browser's language setting. Please take a look at the webapp root directory on your deployment, you may see:

config/auth/default
config/auth/default/Login.jsp
config/auth/default/LDAP.xml
config/auth/default_en/
config/auth/default_en/LDAP.xml
config/auth/default_zh_TW/
config/auth/default_zh_TW/LDAP.xml

My browser language is zh-tw. when I access AM LDAP login page, AM will first look for "config/auth/default_zh_TW/LDAP.xml", if not found, then try to look for "config/auth/default/LDAP.xml". Similar lookup procedure applys to JSP template. Such mechanism allow you to only override the file you need. In addition to localization file lookup, you can even have separate XML and JSP template per Organization(Realm) per Device Type... it is too far away for me.

There are also lots of amXXXXX.properties file in /opt/SUNWam/locale (for AM) or in /WEB-INF/classes (for OpenSSO). You can also localize them by creating amXXXXX_zh_TW.properties file. A handy Java Developer should know what I'm saying.


迴響:

發表迴響:
迴響功能已被關閉
About

純粹個人經驗分享,並非官方立場。

Search

Archives
« 四月 2014
星期日星期一星期二星期三星期四星期五星期六
  
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
   
       
今日