OAM 和 SP 中的自訂後續認證模組

本文說明如何實行自訂認證 Plugin，此 Plugin 將會在聯合 SSO 完成之後呼叫，並且將會：

如需如何設計自訂「認證 Plugin」的詳細資訊，請參閱 OAM Developer's Guide (第 3 章)，其中說明如何開發這類模組：http://docs.oracle.com/cd/E40329_01/dev.1112/e27134/authnapi.htm。讓我們專注於如何：

同盟認證模組

重要注意事項：使用「聯合測試 SP」應用程式時，會略過「認證模組」，因此不會執行此類模組中定義的 Plugin。

「OAM 認證模組」為：

OOTB Federation Authentication Module (稱為 FederationPlugin) 由兩個 Plugin 組成：

協調流程可由下列項目查看：

  1. 移至「OAM 管理主控台」：http(s)://oam-adminhost:oam-admin-port/oamconsole。
  2. 瀏覽至 Access Manager 、 Authentication Modules 。
  3. 開啟 FederationScheme 。
  4. 按一下步驟頁籤即可查看 Plugin。
  5. 按一下步驟協調流程頁籤，即可查看不同 Plugin 與用來啟動作業之 Plugin 之間的協調流程。

Federation_Plugin_Screen.png 圖解說明

AssertionProcessing 外掛程式

AssertionProcessing Plugin 負責驗證及使用內送「SSO 宣告」，以將「宣告」對應至本機 LDAP 使用者記錄，並傳回使用者的識別以及「宣告」與 OAM 的內容。「認證 Plugin」之間共用的 AuthenticationContext 執行處理包含 CredentialParam 物件，可讓各種 Plugin 在程式實際執行時進行通訊，以及認證作業的結果。

認證相關資訊環境資料

成功認證後，「OAM 認證 Plugin」會在 AuthenticationContext 中傳回下列資料：

AuthenticationContext 的「證明資料」物件中包含下列 CredentialParam 執行處理

AuthenticationContext 中包含下列 PluginResponse 執行處理：

使用者記錄所在之「識別存放區」的名稱

「認證層次」(如果在「聯合 SP」處理期間被覆寫) (如需詳細資訊，請參閱此文章：Art 27 Mapping Fed Authn Method to Authn Levels in OAM SP)

宣告資料，每個元素都是獨立的 PluginResponse 執行處理：

OAM 會使用 AuthenticationContext 中包含的資料進一步處理。

「宣告」資料由下列元素組成：

範例

讓我們採用下列範例來檢查流程結尾的 AssertionProcessing 外掛程式所傳回的資料：

OAM/SP 中的 IdP 夥伴連結至僅有一個項目 (將「SAML 屬性名稱」UID 對應至「OAM 階段作業屬性名稱」使用者 ID) 的 IdP 屬性設定檔。在此範例中，測試使用者將會是：

「SAML 2.0 宣告」的範例如下：

<samlp:Response ..>
     <saml:Issuer ...>hLp://acme.com/idp</saml:Issuer>
     <samlp:Status>
         <samlp:StatusCode
 Value="urn:oasis:names:tc:SAML:2.0:status:Success"/>
     </samlp:Status>
     <saml:Assertion ...>
         <saml:Issuer ...>hLp://acme.com/idp</saml:Issuer>
         <dsig:Signature ...>
         ...
         </dsig:Signature>
         <saml:Subject>
 <saml:NameID ...>alice@oracle.com</saml:NameID>
             ...
         </saml:Subject>         <saml:Conditions ...>
          ...
         </saml:Conditions>         <saml:AuthnStatement ...>
         ...
         </saml:AuthnStatement>
         <saml:AttributeStatement ...>
             <saml:Attribute Name="userid" ...>
                 <saml:AttributeValue ...>alice</saml:AttributeValue>
             </saml:Attribute>
             <saml:Attribute Name="lastname" ...>
                 <saml:AttributeValue ...>Appleton</saml:AttributeValue>             </saml:Attribute>
             <saml:Attribute Name="firstname" ...>
                 <saml:AttributeValue ...>Alice</saml:AttributeValue>
             </saml:Attribute>
         </saml:AttributeStatement>
     </saml:Assertion>
 </samlp:Response>

順利處理 SAML 2.0 宣告以及將內送 SSO 回應對應至本機使用者記錄之後，AssertionProcessing 外掛程式會傳回 OAM AuthenticationContext，其中包含下列資料：主旨包含：

AuthenticationContext 的「證明資料」物件中包含下列 CredentialParam 執行處理

AuthenticationContext 中包含下列 PluginResponse 執行處理：

自訂認證 Plugin

概觀

在此文章中，我們假設 OAM/SP 部署需要支援：

使用支援 #1 的即時使用者佈建模組。為了能夠滿足 #2 的需求，需要有自訂驗證外掛程式：

在此範例中，環境由下列項目組成：

自訂驗證外掛程式由下列項目組成：

這三個元素會隨附在 JAR 檔案中，然後透過「OAM 管理主控台」上傳至 OAM 伺服器。上傳並啟用之後，請修改「聯合認證模組」。

Java 類別

實行自訂認證外掛程式的類別必須符合下列條件：

下列程式碼是自訂外掛程式的範例。

package postsp;
 import java.util.Hashtable;
 import java.util.Map;
 import java.util.Set;
 import javax.naming.Context;
 import javax.naming.NamingException;
 import javax.naming.directory.Attributes;
 import javax.naming.directory.BasicAttribute;
 import javax.naming.directory.BasicAttributes;
 import javax.naming.directory.DirContext;
 import javax.naming.directory.InitialDirContext;
 import javax.security.auth.Subject;
 import oracle.security.am.common.utilities.principal.OAMUserDNPrincipal;
 import oracle.security.am.common.utilities.principal.OAMUserPrincipal;
 import oracle.security.am.plugin.ExecutionStatus;
 import oracle.security.am.plugin.MonitoringData;
 import oracle.security.am.plugin.PluginAttributeContextType;
 import oracle.security.am.plugin.PluginResponse;
 import oracle.security.am.plugin.authn.AbstractAuthenticationPlugIn;
 import oracle.security.am.plugin.authn.AuthenticationContext;
 import oracle.security.am.plugin.authn.AuthenticationException;
 public class CustomAttributesUpdatePlugin extends
 AbstractAuthenticationPlugIn
 {
   public ExecutionStatus process(AuthenticationContext context)
               throws AuthenticationException {
     // user's ID and DN. Note: we are not making necessary checks for size/null to
     // keep the sample code minimal.
     Subject subject = context.getSubject();
     Set<OAMUserPrincipal> principalsUserID =
               subject.getPrincipals(OAMUserPrincipal.class);
     Set<OAMUserDNPrincipal> principalsDN =
               subject.getPrincipals(OAMUserDNPrincipal.class);
     String localUserID =
 (String)principalsUserID.iterator().next().getName();
     String localUserDN = (String)principalsDN.iterator().next().getName();
     // get the assertion data. Note: We are not making necessary checks for size/null to
     // keep the sample code minimal.
     PluginResponse partnerResponse = context.getResponse(               PluginAttributeContextType.SESSION, "fed.partner");
     String partnerName = (String)partnerResponse.getValue();     PluginResponse nameIDResponse = context.getResponse(
               PluginAttributeContextType.SESSION, "fed.nameidvalue");
     String nameID = (String)nameIDResponse.getValue();
     PluginResponse uidResponse = context.getResponse(
               PluginAttributeContextType.SESSION, "fed.aLr.uid");
     String uid = (String)uidResponse.getValue();
     PluginResponse firstnameResponse = context.getResponse(
               PluginAttributeContextType.SESSION, "fed.aLr.firstname");
     String firstname = (String)firstnameResponse.getValue();     PluginResponse lastnameResponse = context.getResponse(
               PluginAttributeContextType.SESSION, "fed.aLr.lastname");
     String lastname = (String)lastnameResponse.getValue();
     try {
       // open ldap connection
       Hashtable env = new Hashtable();
       env.put(Context.INITIAL_CONTEXT_FACTORY,
 "com.sun.jndi.ldap.LdapCtxFactory");
       env.put(Context.PROVIDER_URL, "ldap://host:port");
       env.put(Context.SECURITY_PRINCIPAL, "admin");
       env.put(Context.SECURITY_CREDENTIALS, "password");       DirContext ldapContext = new InitialDirContext(env);
       // modify user ldap record. Note: We are not making the necessary checks to
       // keep the sample code minimal.
       Attributes attributes = new BasicAttributes();
       attributes.put(new BasicAttribute("givenname", firstname));
       attributes.put(new BasicAttribute("sn", lastname));
       attributes.put(new BasicAttribute("mail", nameID));
       attributes.put(new BasicAttribute("uid", uid));
       ldapContext.modifyAttributes(localUserDN,
                          DirContext.REPLACE_ATTRIBUTE, attributes);
     }
     catch (NamingException ex) {
       throw new AuthenticationException(ex);
     }
     // return success, so that OAM can resume the flow
     return ExecutionStatus.SUCCESS;
   }
   public String getPluginName() {
     return "CustomAttributesUpdatePlugin";
   }
   public String getDescription() {
     return "Custom Attributes Update Plugin";
   }
   public Map<String, MonitoringData> getMonitoringData() {
     return null;
   }
   public boolean getMonitoringStatus() {
     return false;
   }
   public int getRevision() {
     return 10;
   }
   public void setMonitoringStatus(boolean arg0) {
   } }

外掛程式註冊檔案

必須在 Plugin XML 檔案中定義自訂認證 Plugin，例如：

<Plugin type="Authentication">
<author>uid=admin</author>
<email>admin@example</email>
<creationDate>08:00:00,2014-01-15</creationDate>
<description>Custom Attributes Update Plugin</description>
<conhguration>
</conhguration>
</Plugin>

重要注意事項：XML 檔案的名稱必須與實行 Plugin 的類別相同，在此情況下為 CustomAttributesUpdatePlugin.xml

請參閱 OAM 開發人員手冊瞭解詳細資訊

資訊清單檔案

Before packaging the custom Authentication plugin in a JAR file, a MANIFEST.MF must be defined such as: Manifest-Version: 1.0 Bundle-ManifestVersion: 2 Bundle-Name: CustomAttributesUpdatePlugin Bundle-SymbolicName: CustomAttributesUpdatePlugin Bundle-Version: 10 Bundle-Activator: postsp.CustomAttributesUpdatePlugin Import-Package: org.osgi.framework;version=”1.3.0”,oracle.security.am.plugin,oracle.security.am.plugin.authn,oracle.security.am.common.utilities.principal,javax.naming,javax.naming.directory,javax.security.auth Bundle-RequiredExecutionEnvironment: JavaSE-1.6

請參閱 OAM 開發人員手冊瞭解詳細資訊

注意：資訊清單檔案必須包含 Import-Package 特性，其中列出外掛程式使用的所有套裝軟體

建立外掛程式

編譯中

OAM 部署的下列 JAR 檔案需要用於編譯：

在下列位置找到這些檔案：

在此範例中，我們會將 CustomAttributesUpdatePlugin.java 檔案放在 src/postsp 資料夾中：

bash-4.1$ ls -l src/postsp/ total 4
-rw-r--r-- 1 root root 4377 Oct 1 09:54 CustomAttributesUpdatePlugin.java

若要編譯，請執行下列命令：

$JDK_HOME/bin/javac -cp $IAM_HOME/oam/server/lib/plugin /felix.jar:$IAM_HOME/oam/server/lib/plugin/oam-
plugin.jar:$IAM_HOME/oam/server/lib/plugin/utilities.jar src/postsp /\*.java

封裝自訂 Plugin

我們根據上一節列出的內容，在目前的目錄中建立 MANIFEST.MF，在 src 目錄中建立 CustomAttributesUpdatePlugin.xml，其中包含上一節列出的外掛程式定義。

find
.
./MANIFEST.MF
./src
./src/userauthn
./src/userauthn/CustomAttributesUpdatePlugin.class
./src/userauthn/CustomAttributesUpdatePlugin.java
./src/CustomAttributesUpdatePlugin.xml

若要建立包含 Plugin 和必要檔案的 CustomAttributesUpdatePlugin.jar JAR 檔案，請執行下列命令：

jar cfvm CustomAttributesUpdatePlugin.jar MANIFEST.MF -C src/ . added manifest adding: CustomAttributesUpdatePlugin.xml(in = 238) (out= 158)(deflated 33%) adding: postsp/(in = 0) (out= 0)(stored 0%) adding: postsp/CustomAttributesUpdatePlugin.java(in = 4377) (out= 1206)(deflated 72%) adding: postsp/CustomAttributesUpdatePlugin.class(in = 3726) (out= 1667)(deflated 55%)

這會建立 CustomAttributesUpdatePlugin.jar。檢視檔案的內容：

unzip -l CustomAttributesUpdatePlugin.jar Archive: CustomAttributesUpdatePlugin.jar
長度 日期 時間 名稱
0 10-01-2014 10:04 後設通知 /
542 10-01-2014 10:04 中繼資訊 /MANIFEST.MF
238 10-01-2014 09:11 CustomAttributesUpdatePlugin.xml
0 10-01-2014 09:59 後 sp/
4377 10-01-2014 09:54 postsp/CustomAttributesUpdatePlugin.java
3726 10-01-2014 09:54 postsp/CustomAttributesUpdatePlugin.class
8883   6  

重要注意事項：JAR 檔案的名稱必須與實行 Plugin 的類別相同，在此情況下為 CustomAttributesUpdatePlugin.jar

部署自訂驗證 Plugin

請執行下列步驟，在 OAM 中部署自訂認證 Plugin：

  1. 移至「OAM 管理主控台」：http(s)://oam-adminhost:oam-admin-port/oamconsole
  2. 瀏覽至 Access Manager 、 Plugins
  3. 按一下匯入 Plug-In
  4. 選取 Plugin JAR 檔案 (此範例中的 CustomAttributesUpdatePlugin.jar)

Specifying_Plug-in_JAR_file.png 圖解描述

外掛程式會處於已上傳狀態：

Plug-in_loaded_Screen.png 圖解描述

您必須將 Plugin 分配給程式實際執行 OAM 伺服器並加以啟動：

  1. 選取 Plugin
  2. 按一下「分送選取的項目」Plugin 的「啟動狀態」頁籤會顯示 Plugin 的狀態

Plug-in_Screen_with_Status.png 圖解描述

您需要啟用外掛程式：

  1. 選取 Plugin
  2. 按一下「啟動已選取項目」外掛程式的「啟動狀態」頁籤顯示外掛程式的狀態

Plug-in_Screen_with_Status_Activated.png 圖解描述

建立認證模組

根據現有的 FederationPlugin 認證模組 (與現有的模組不同) 建立新的「同盟認證模組」：

執行下列步驟以建立新的「認證模組」：

  1. 移至「OAM 管理主控台」：http(s)://oam-adminhost: oam-admin-port/oamconsole
  2. 瀏覽至 Access Manager 、 Authentication Modules
  3. 按一下建立認證模組
  4. 選取建立自訂認證模組
  5. 輸入名稱 (例如 CustomFedModule)

Creating_Authentication_Module.png 圖解說明

執行下列步驟以新增步驟至新的「認證模組」：

  1. 按一下「步驟」頁標
  2. 按一下新增以新增 FedAuthnRequestPlugin 步驟：
  3. 按一下確定

    4. Add_Authentication_Module.png 圖解說明

  4. 按一下新增以新增 AssertionProcessing 步驟：
  5. 按一下確定

    6. Add_Assertion_Processing_Screen.png 圖解說明

  6. 按一下新增以新增 AttributesUpdate 步驟：
  7. 按一下確定

Attributes_Update_Screen.png 圖解說明

「步驟」頁籤顯示：

Steps_Screen.png 圖解說明

請執行下列步驟來定義新「認證模組」的步驟協調流程：

  1. 按一下「步驟協調流程」頁籤，選取 FedAuthnRequestPlugin 作為 FedAuthnRequestPlugin 的起始步驟：
  2. 成功時選取成功
  3. 選取 AssertionProcessing 以取得「失敗時選取失敗」
  4. 按一下套用

Define_Orchestration_Screen.png 圖解說明

認證配置

使用使用新「認證模組」的「認證原則」保護資源之前，必須先建立新的「認證配置」，參照該新自訂模組。這是必要的，因為「認證原則」連結至「認證配置」，而不是「認證模組」。若要為該自訂模組建立新的「認證配置」，請執行下列步驟：

  1. 移至「OAM 管理主控台」：http(s)://oam-adminhost:oam-admin-port/oamconsole
  2. 瀏覽至 Access Manager 、 Authentication Schemes
  3. 按一下「建立認證配置 (Create Authentication Scheme)」。
  4. 輸入名稱 (例如 CustomFedScheme) 和描述 將「認證層次」設為可接受的值 (在此範例中為 2)
  5. 選取 FORM 作為查問方法
  6. 設定挑戰重新導向 URL (在此範例中，我們將其設為 /oam/server/)
  7. 選取新建立的自訂認證模組 (範例中的 CustomFedModule)
  8. 設定查問 URL (此範例中的 /pages/servererror.jsp)
  9. 設定內容類型 (例如 customWar)
  10. 設定內容值 (/oam，因為我們不使用任何頁面)
  11. 請至少輸入下列「查問參數」：
  12. 按一下套用

Authentication_Schemes_Screen.png 圖解說明

測試

使用新建立的「認證配置」，使用「認證原則」保護資源。這會呼叫自訂「認證模組」。在聯合 SSO 之前，OAM/SP 的 LDAP 使用者記錄為：

dn: cn=alice,ou=users,dc=us,dc=oracle,dc=com
objectClass: person
objectClass: organizationalPerson
objectClass: inetOrgPerson
objectClass: top
givenName: al
title: manager
uid: alice
cn: alice
sn: APPLETON
userPassword:: e1NTSEE1MTJ9TXp0R2d0Si9GT1NzYUxvRXJqZW0rM1Q2eU5QMW9ZZmZ2Y3FkVWpaS1o1OFNGMy95ZDBueUxUbnllRi83SFRtS2JmOTJ0anY4TFd6di9UanliOGw4WFNQV1BxSnF3N mail: alice@oracle.com

認證之後，IdP 會傳送下列資訊給 SAML 2.0 宣告中的使用者別名：

聯合 SSO 之後，CustomAttributesUpdatePlugin 必須更新 alice 的 LDAP 記錄，以便將 sn、assname、uid 及 mail 設為「SAML 宣告」的值。OAM/SP 之「聯合 SSO」作業後的 LDAP 使用者記錄現在為：

dn: cn=alice,ou=users,dc=us,dc=oracle,dc=com
objectClass: person
objectClass: inetOrgPerson
objectClass: organizationalPerson
objectClass: top
givenName: Alice
title: manager
uid: alice
cn: alice
sn: Appleton
userPassword:: e1NTSEE1MTJ9TXp0R2d0Si9GT1NzYUxvRXJqZW0rM1Q2eU5QMW9ZZmZ2Y3FkVWpaS1o1OFNGMy95ZDBueUxUbnllRi83SFRtS2JmOTJ0anY4TFd6di9UanliOGw4WFNQV1BxSnF3N
mail: alice@oracle.com

其他學習資源

探索 docs.oracle.com/learn 上的其他實驗室，或存取 Oracle Learning YouTube 頻道上的更多免費學習內容。此外，瀏覽 education.oracle.com/learning-explorer 成為 Oracle Learning Explorer。

如需產品文件，請造訪 Oracle Help Center 。