星期五 九月 21, 2007

A short test on Policy Agent's Session Attribute

Good article on Idira's blog regarding attribute passing feature in Policy Agent. But there are some attributes new to me so I'd like to take a try on possible attribute name, here is my configuration

com.sun.am.policy.agents.config.session.attribute.map=UserToken|AM_SES_USERTOKEN
,UserId|AM_SES_USERID,Principal|AM_SES_PRINCIPAL,Organization|AM_SES_ORGANIZATIO
N,Realm|AM_SES_REALM,AuthType|AM_SES_AUTHTYPE,AuthLevel|AM_SES_AUTHLEVEL,HostNam
e|AM_SES_HOSTNAME,Principal|AM_SES_PRINCIPAL,AMCtxId|AM_SES_CONTEXTID,sun.am.Uni
versalIdentifier|AM_SES_SUN.AM.UNIVERSALIDENTIFIER

And the result is (PA2.2 for SJSWS7)

  • am_ses_authlevel =

    0

  • am_ses_authtype =

    LDAP

  • am_ses_contextid =

    4b35f325f9d3c1de01

  • am_ses_hostname =

    192.168.159.1

  • am_ses_organization =

    dc=testdomain,dc=com

  • am_ses_principal =

    uid=budhead,ou=People,dc=testdomain,dc=com

  • am_ses_sun.am.universalidentifier =

    id=budhead,ou=user,dc=testdomain,dc=com

  • am_ses_userid =

    budhead

  • am_ses_usertoken =

    budhead

星期三 九月 12, 2007

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.


星期一 九月 10, 2007

Access Manager Authentication Module and UI 101

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

Many people who deploy SJS Access Manager first time often want to customize the default login page. It could be piece of cake if you only need to change the UI Layout or swap some canned image file. However, most real-life deployment are not so straightforward. I wish this blog provides you more knowledge on such tasks. Well, SJS Access Manager now is open sourced as OpenSSO Project and the move makes thing easier because we can look into Login Module source.

Let's talk about some basic thing, in case you don't know yet.

Authentication Module and Chainning

SJS Access Manager (AM) is designed to be able to support multiple authentication modules. When a user login against AM, he in fact authenticate against an Authentication Chain. An authentication chain consists of one or more than one Authentication Modules. To setup an authentication chain, you need to select a few modules, define their processing order, and assign each module's significance to entire authentication result. The "significance" I mentioned is called Condition. There are four Condition options you can assign to an authentication module:

  • SUFFICIENT : A successful authentication to this module means successful authentication to the chain. Follow-up authentication modules in the chain WILL NOT be proceed. A failed authentication attempt to this module doesn't mean failure of chain and AM WILL process the follow-up modules to determine the final result.
  • REQUIRED : An attempt to authenticate this module MUST be successful. However, AM WILL STILL process the follow-up modules even a failed authentication attempt occurs. In addition, although this module is required to pass, a user MAY NOT need to authenticate to this module if he already successfully authenticate to a SUFFICIENT module earlier.
  • REQUISITE : An attempt to authenticate this module MUST be successful. If a failure authentication attempt to this module occurs, AM WILL NOT process the follow-up modules and the chain result is failed. In addition, although this module is required to pass, a user MAY NOT need to authenticate to this module if he already successfully authenticate to a SUFFICIENT module earlier.
  • OPTIONAL : I don't know how to describe this type of condition. AM always process the follow-up modules no matter the authentication result to this module.

Let's create an authentication chain like this :




The snapshot from AM console shows an authentication chain having three authentication modules: LDAP, LocalMySQL, and LocalSolaris. They are a instance of built-in LDAP, JDBC, and Unix authentication module respectively. When a user try to authenticate to this chain, he will see LDAP login page first. He is lucky to pass this LDAP authentication, then go straight into the amconsole (or a welcome page). AM won't show him MySQL and Solaris credentials because LDAP is configured as SUFFICIENT. On the other hand, if he failed to login to LDAP, he will be prompt by LocalMySQL login page. He has to pass LocalMySQL authentication because it is a REQUISITE module, otherwise the login to chain will fail.

OK, assume he pass LocalMySQL login, he will see LocalSolaris login page and he has to pass it as well. At this point, the result of LocalSolaris authentication will determine the result of the entire authentication chain.

What is the very first authentication chain you need to login to before creating any other authentication chain ? The Access Manager installer create a default authentication chain called "ldapService" for the use. This default chain only contains one authentication module -- LDAP (or DataStore if you install OpenSSO with local file repository). That's what you usually authenticate to. One important thing is AM separates the login handler for admin console from the one for /UI/Login. As the following picture shown, the Administrator Authentication Chain configuration is for admin console access (/amserver/console); the Default Authentication Chain configuration is for access Login servlet (/amserver/UI/Login). AM installer assigns both to ldapService chain and I altered the upper one to my own chain. My advice is to leave Administrator Authentication Chain unchanged. A bad assignment will result amadmin lockout, be careful.


Login process for a single Module

Now we're going to see how AM navigate login page and the process flow for credential validation.

The diagram on the bottom tells the trick. Before talking about the diagram, you should understand the nut & bolt of AM Authentication Module : Authentication Module Class, UI Callback XML, and UI Callback Template. Here are the details.

Authentication Module Class

It is a Java program. One authentication module typically has 2-3 java classes. The am_services.jar file contains the classes of all built-in Authentication Modules. We usually don't need to touch them (and better not to). It execute the logic to validate credentials given by user, and also callback to UI component when more information needed from user. An authentication module class is a subclass of com.sun.identity.authentication.spi.AMLoginModule, and certainly need to implements the necessary methods such as init( ), process( ), and getPrintcipal( ). AM creates a instance of the module class for each authentication request to this module.

UI Callback XML

Every authentication module should have its own UI Callback XML file, even though it is a zero size file (like Certificate login module). Callback is the fundamental concept brought in by JAAS (Java Authentication Authorization Service). It assume the authentication process may be complex and involve multiple client-server interaction. Server can use callback to request more credential input from client when necessary and the callback question may change on the fly by server due to the result from previous callback. OK, it is just...complex...but flexible.

A UI Callback XML file defines the "questions" AM may ask to user during a authentication process. For better mapping to web interface, AM pre-define several types of callback for your use, such as Text-like, Password-like, or HTTPResponse-like callback. You can find the UI Callback XML files for the built-in authentication module at (assume you install AM on SJSWS7)

/var/opt/SUNWwbsvr/https-yourinstance/web-app/
yourinstance/amserver/config/auth/default/\*.xml

Check out LDAP.xml, AD.xml, and JDBC.xml for reference.

UI Callback Template

A UI Callback Template is a JSP file. Typically it contains HTML tag and AM UI specific tag. It is referred and used by the Callbacks element in UI Callback XML file to render the Callback XML to actual HTML page. You can find the UI Callback Template files at

/var/opt/SUNWwbsvr/https-yourinstance/web-app/
yourinstance/amserver/config/auth/default/\*.jsp

Each <Callbacks> element in Callback XML has an attribute "template" indicating the template JSP for this <Callbacks>. But you may hardly to find a <Callbacks> with template value from all built-in Callback XML files. In fact, AM will use "Login.jsp" as the template JSP for this case. Out of box, the Login.jsp is used by almost all modules for all login page. So be careful of the side effect results from a hacked Login.jsp. My advice is to create your own template JSP.

Be aware that the template JSP is just a template used by AM authentication service. The service utilize JATO framework (a Sun's own MVC framework, like struts), so don't expect you can access the Login.jsp by put its name in URL. It just won't work !!!



OK, let's take a look at the Login Flow Chart step by step :

  1. User bring up browser and access http://yourhost.yourdomain.com/amserver/UI/Login (or via a URL link, or redirect by Policy Agent). Then AM check the domain name and parameters in this request to determine which Authentication Chain should be used. Assume the chain was found and its first login module is "XModule" (maybe somebody else made it), then a instance (Left block in the diagram) of XModule class is created by AM, its init( ) get called for initialization work. After this, AM check XModule's UI Callback XML file "XModule.xml", pick the first <Callbacks> element -- Callbacks Order 1。
  2. Access Manager parse Callbacks Order 1 (2 callbacks and no template assigned). Then it use default Login.jsp as HTML template to render the UI page. The outcome page will contain two HTML input fields. One is for NameCallback; the other is for PasswordCallback. AM also assign IDTokenN as the filed identifier to them. N is the position in <Callbacks> element. For NameCallback and PasswordCallback, their <Prompt> sub-element value will also be shown as leading label text.
  3. User then see the login page with two input fileds, key in the ID & Password.
  4. Then he click "Submit" button, an HTTP POST send the credential (in IDToken1=theid&IDToken2=thepass in body) back to /amserver/UI/Login servlet.
  5. Now it is the show time for module class. Its process( ) method is called with two arguments : a Callback[ ] array containing what user just key in and a Callbacks order number, currently should be 1 telling process( ) to validate credential for <Callbacks order="1"..>. At this point, the control is in XModule program. It should now verify the credentials and return a order number for next <Callbacks> if new question need to ask to user. For most case, the ID & Password pair is sufficient to determine the authenticaiton result and module class can simply return -1 for valid credentials to finish the module. The built-in LDAP module does so, that's why we usually see only one page before LDAP login. However, sometimes you get another page asking you to Change Password because your current password is going to expired. Under the hood, LDAP Server tells LDAP module the password is expiring in xxx days and the module process( ) return 2 to ask for password change. Let's assume our XModule need to ask more and return 2.
  6. Then AM internal found that process( ) returns 2, then check the Callback Order 2 XML-- one PasswordCallback, no template.
  7. AM then use Login.jsp as HTML tempate again, render a HTML page with only one input box for password (IDToken1).
  8. User see the 2nd page, then type in the password as requested.
  9. Then he click "Submit" button again. an HTTP POST send the credential back to /amserver/UI/Login again. The same XModule instance's process( ) get called again, but with new callback[ ] and State argument values. This time the State =2. You surely know why.
  10. The process( ) run different logic according to different State value (You should code it so). But the basic rule doesn't change:
    > return -1 if the credentail is valid and no more question for user OR
    > throws AuthLoginException if you're sure the login attempt is failed OR
    > return another order number if you need to ask more
    To complete my long diagram, we assume the picky XModule still need to ask more, and return 3.
  11. AM get 3 as return, similar to step 7, callback to user, and then get back... the interaction keep going.
  12. Finally, during processing Callback Order 4, module class can determine it is a successful login (Thanks God), return -1.

Above is a perfect scenario, but what if an error occurs in module class and you need to terminate the process immediately? You just need to throws a AuthLoginException anywhere anytime in process( ) method. When AM caught such exception, the follow-up order will not be executed and usually user get authentication failed or server internal error message. Depends on the severity of the error and module Condition, sometimes AM will forward user to next module.



星期二 十二月 27, 2005

Access Manager 版本命名釋疑

Sun 的軟體產品命名最近幾年改動的很頻繁,除了 iPlanet 改為 Sun ONE 並再改為 Sun Java System之外,在Java Enterprise System (JES)推出之後,每個個別產品都要以 YYYYQX (年季) 的方式做版本編號,並統一由 JES 的 CD 來安裝。但目前內部個別產品仍保有自己的版本命規則。 這裡是 Access Manager 產品的名稱對照表。

系列名 產品名稱 

內部版本 

JES版本  JES# 
 iPlanet

Directory Server Access

Management Edition (DSAME)

 5.0     
 iPlanet

Directory Server Access

Management Edition  (DSAME)

 5.1    
 "iPlanet" 改名為 "Sun ONE"
 Sun ONE Identity Server   6.0     
 Java Enterprise System (JES) 問事
 Sun ONE Identity Server   6.1 2003Q4 JES1 
 "Sun ONE" 改名為 "Sun Java System"
 Sun Java System Identity Server   6.2 2004Q2  JES2
 "Identity Server" 改名為 "Access Manager"
 Sun Java System Access Manager  6.3 2005Q1 JES3
 Sun Java System Access Manager   7.0 Patch1  2005Q4 

JES4

 

 附帶說明一下,以下二個產品是不一樣的:

  • Sun Java System Identity Server
  • Sun Java System Identity Manager

前者是指舊版的 Identity Server (6.0,6.1),現在已經不用這個名字了,而後者是 Sun 的另一個產品(把 Waveset 公司併掉之後將其 lighthouse 產品更名)。請勿混淆。

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
   
       
今日