OAM Integration Kit User Guide - Ping Identity · PDF filePingFederate OAM Integration Kit 4 User Guide Introduction The PingFederate Oracle Access Manager (OAM) Integration Kit adds

OAM Integration Kit Version 3.0

User Guide

PingFederate OAM Integration Kit 2 User Guide

©2016PingIdentity®Corporation.Allrightsreserved.

PingFederateOAMIntegrationKitUserGuideVersion3.0May,2016

PingIdentityCorporation100117thStreet,Suite100Denver,CO80202U.S.A.

Phone:877.898.2905(+1303.468.2882outsideNorthAmerica) Fax:303.468.2909WebSite:www.pingidentity.com

Trademarks

PingIdentity,thePingIdentitylogo,PingFederate,PingOne,PingConnect,andPingEnableareregisteredtrademarksofPingIdentityCorporation("PingIdentity").Allothertrademarksorregisteredtrademarksarethepropertyoftheirrespectiveowners.

Disclaimer

Theinformationprovidedinthisdocumentisprovided"asis"withoutwarrantyofanykind.PingIdentitydisclaimsallwarranties,eitherexpressorimplied,includingthewarrantiesofmerchantabilityandfitnessforaparticularpurpose.InnoeventshallPingIdentityoritssuppliersbeliableforanydamageswhatsoeverincludingdirect,indirect,incidental,consequential,lossofbusinessprofitsorspecialdamages,evenifPingIdentityoritssuppliershavebeenadvisedofthepossibilityofsuchdamages.Somestatesdonotallowtheexclusionorlimitationofliabilityforconsequentialorincidentaldamagessotheforegoinglimitationmaynotapply.

Document Lifetime

PingIdentitymayoccasionallyupdateonlinedocumentationbetweenreleasesoftherelatedsoftware.Consequently,ifthisPDFwasnotdownloadedrecently,itmaynotcontainthemostup-to-dateinformation.Pleaserefertodocumentation.pingidentity.comforthemostcurrentinformation.

FromtheWebsite,youmayalsodownloadandrefreshthisPDFifithasbeenupdated,asindicatedbyachangeinthisdate:May20,2016

http://www.pingidentity.com/

http://documentation.pingidentity.com/


ContentsIntroduction ................................................................................................................................... 4

Intended Audience .................................................................................................................... 4System Requirements .............................................................................................................. 4ZIP Manifest ............................................................................................................................. 4

IdP Implementation ....................................................................................................................... 5Process Overview ..................................................................................................................... 5OAM Configuration ................................................................................................................... 6Apache Module Installation ...................................................................................................... 6Apache Module Configuration .................................................................................................. 6PingFederate Configuration ...................................................................................................... 7Configuring an IdP Adapter Instance ........................................................................................ 8Testing the IdP Adapter ............................................................................................................ 9

SP Implementation ...................................................................................................................... 11Process Overview ................................................................................................................... 11OAM Configuration ................................................................................................................. 12PingFederate Configuration .................................................................................................... 13Configuring an SP Adapter Instance ...................................................................................... 13Testing the SP Adapter .......................................................................................................... 14


IntroductionThePingFederateOracleAccessManager(OAM)IntegrationKitaddsIdentityProvider(IdP)andServiceProvider(SP)AdapterstoPingFederate.TheOAMIdPAdapterallowsanIdPenterprisetoextendanexistingOAMinvestmentbyusingtheSAMLorWS-FederationprotocolstoexpandthereachoftheOAMdomaintopartnerapplications.TheOAMSPAdapterallowsanSPenterprisetoacceptSAMLorWS-FederationassertionsandprovideSSOtoOAM-protectedapplications.

IntendedAudience

ThisdocumentisintendedforsystemadministratorswithexperienceintheconfigurationandmaintenanceoftheOAMAccessServer.Pleaseconsultdocumentationprovidedwithyourserveroraccess-managementtoolsifyouencounteranydifficultiesinareasnotdirectlyassociatedwiththePingFederateorintegration-kitsetups.

SystemRequirements

ThefollowingsoftwaremustbeinstalledinordertoimplementtheOAMIntegrationKit:

• PingFederate8.x(orhigher)

• OAMServer11gR2

• OAMAccessSDK11.1.2.3.0(installedonthesamemachinerunningthePingFederateserver)

• OAM11gWebgaterunningonApache2.4

• Redhat6.7(ifusingtheprecompiledmoduleincludedinthisdistribution)

ZIPManifest

ThedistributionZIPfilefortheOAMIntegrationKitcontainsthefollowing:

• ReadMeFirst.pdf

• /dist–containslibrariesneededtoruntheadapter:

– pf-oam-adapter-3.0.jar–OAMAdapterJARfile– mod_pfoam.so–Apache2.4Module,compiledonRedhat6.7

– PingOpenTokenAuthPlugin.jar–OAMAuthenticationPluginPluginusedforSPusecase

• /conf–containslibrariesneededtoruntheadapter:

– httpd-pfoam.conf–Sampleapacheconfigurationfileformod_pfoam.so– jps-config.xml–OAMconfigurationfile


IdPImplementationThissectiondescribesusingtheOAMIntegrationKitasanIdP.

IdPProcessOverview

TheOAMIdPAdapterusestheAccessServerSDKtodecrypttheOAMsessioncookieandpassattributestothePingFederateserver.YoucanthenaddattributevaluestotheAttributeContractinthePingFederateadministrativeconsoleandtransferthemtoapartnerapplicationinaSAMLassertion.(Formoreinformation,see:CreatinganAttributeContractinthePingFederateAdministrator’sManual.)

ThefollowingfigureillustratestherequestflowandhowtheOAMIdPAdapterisusedtofacilitategeneratingaSAMLWS-FederationassertionfromtheObSSOCookie:

ProcessingSteps

1. UserinitiatessinglesignonthroughPingFederate.

2. TheOAMIdPAdapterredirectstheusertoanOAMProtectedResource.

3. OAMWebgateauthenticatestheuser.

4. AftersuccessfulauthenticationanOAM11gsessionisestablishedandahostlevelcookieiscreatedfortheWebgate.


5. UserisallowedaccesstotheOAMprotectedresourceatwhichpointthePingWebFilterinterceptsthisrequestandsendsthehostlevelOAMSessiontokentoPingFederate.

6. OAMIdPAdaptervalidatesthesessiontokenusingAccessServerAPIs.

7. TheuserinformationispassedtoPingFederate,whichcancreateanassertionandsendittotherequiredrelyingparty(akaserviceprovider).

OAMIdPConfiguration1. CreateanOAMApache11gWebgate(oruseanexistingone).

2. CreateanewfolderinthePingFederateServer,tostoretheWebgateconfigurationfiles.ThisfolderwillhenceforthbereferredtoastheAgent Config Location.ThispathmustbespecifiedduringthePingFederateConfiguration.

3. CopytheWebgateconfigurationfilestotheAgent Config Locationfolder.

Note: For more information on the Webgate configuration files, please refer to OAM documentation for configuring Webgates.

ApacheModuleInstallation1. InstalltheApachemoduleandconfigurationfilefromtheintegrationkitintotheApacheserver:

a. Copy dist/mod_pfoam.soto:

<apache installation>/modules

b. Copy conf/httpd-pfoam.conf to:

<apache installation>/conf/extra

2. AddthefollowingdirectivestotheApacheserverconfigurationfile,httpd.conf:

a. LoadModulepfoam_modulemodules/mod_pfoam.so

Important: This module must be loaded first, so ensure it’s above all other LoadModule directives

b. Include conf/extra/httpd-pfoam.conf

ApacheModuleConfiguration

TheconfigurationoptionsfortheApachemodulearelistedinthetablebelow.Updatethemodule’sconfigurationfileasneeded:<apache installation>/conf/extra/httpd-pfoam.conf.

Field Description Default Value

OAMCookieName Cookie name containing the OAM 11g Session Token. Example: OAMAuthnCookie_webgate.mydomain.com:80

N/A

https://docs.oracle.com/cd/E40329_01/doc.1112/e49451/webgate_apache.htm#WGINS76171

https://docs.oracle.com/cd/E40329_01/doc.1112/e49451/webgate_apache.htm#WGINS76171


PFResumePath Parameter containing the relative sso url passed from PingFederate

resumePath

SessionTokenParameterName Parameter Name used to pass OAM session token to PingFederate

OAMAuthnCookie

PFBaseUrl Base URL for PingFederate used in conjunction with resumePath. Example: https://mydomain.com:9031

N/A

Important: Restart the Apache server after making configuration changes.

PingFederateIdPConfiguration1. UnzipthedistributionZIPfileandcopythefollowingfilestotheserver/default/deploy

folderinyourPingFederateserverinstallation:dist/pf-oam-adapter-3.0.jar

2. CopythefollowingfiletotheAgent Config Locationfolder,whichwascreatedinStep2ofOAMConfiguration:conf/jps-config.xml

3. Addthefollowingtorun.propertieswithin<PF_HOME>/binfolder:oracle.security.jps.config=<AGENT_CONFIG_LOCATION>/jps-config.xml

Important: Ensure that the Agent Config Location path uses forward slashes (/), as shown above.

4. InstallandconfiguretheOAMAccessServerSDK.ForinformationontheAccessServerSDK,refertoyourOAMdocumentation.

Note: The Access Server SDK functions as a gate to the OAM Access Server and some files will need to be copied to the server where PingFederate is running.

5. CopythefollowingfilesfromtheAccessServerSDKtotheserver/default/deployfolderinyourPingFederateinstallation:

§ oamasdk-api.jar

§ opss_standalone/modules/

–oracle.idm_11.1.1/identitystore.jar

–oracle.pki_11.1.1/oraclepki.jar

–oracle.jps_11.1.1/jps-ee.jar

–oracle.jps_11.1.1/jps-api.jar

–oracle.jps_11.1.1/jps-unsupported-api.jar

–oracle.jps_11.1.1/jps-common.jar


–oracle.jps_11.1.1/jps-internal.jar

–oracle.osdt_11.1.1/osdt_cert.jar

–oracle.osdt_11.1.1/osdt_core.jar

–oracle.osdt_11.1.1/osdt_xmlsec.jar

Note: The files listed above pertain to the specified version of the OAM SDK in the System Requirements. Other versions may require different files.

6. StartorrestartthePingFederateserver.

ConfiguringanIdPAdapterInstance

AfterinstallingtheOAMIntegrationKitandtheAccessServerSDKlibrary,youcanconfigureyourSPconnectiontouseaninstanceoftheOAMAdapter.Thefirstpartofthisprocessisconfiguringtheadapterinstance.

ToconfigureaninstanceoftheIdPadapter:

1. LogontothePingFederateadministrativeconsoleandclickAdaptersunderIdPConfigurationontheMainMenuscreen.

2. OntheManageIdPAdapterInstancesscreen,clickCreateNewInstance.

3. EntertheAdapterNameandAdapterID.SelectOAM11gIdPAdapter3.0astheAdapterTypeandclickNext.

4. OntheIdPAdapterscreen,enterthevaluesforadapterconfigurationasdescribedonthescreenandclickNext.


Note: The Authentication Level Identifier is taken from the user’s session token. The default/recommended value is authLevel. For the user’s Authentication Level to be sent in the assertion, you must add the Authentication Level Identifier to the Adapter Contract (see step 5, below).

5. Optionally,ontheExtendedAdapterContractscreen,youcanconfigureadditionalattributesfortheadapter.(SeetheExtendinganAdapterContractinthePingFederateAdministrator’sManual.)

Forinstance,youcanusetheextendedadaptercontractforPolicyServerresponse-objectattributes.

6. ClickNext.

7. SelectuserIdastheuniqueid.Youmayalsoselectanyextendedattributesspecifiedinthepreviousscreen.

8. OntheSummaryscreen,verifythattheinformationiscorrectandclickDone.

9. OntheManageAdapterInstancesscreen,clickSavetocompletetheadapterconfiguration.

YoucannowusethisadapterinstanceforanSPconnection.Forinformationonsettingupormodifyingaconnection,seeManagingSPConnectionsinthePingFederateAdministrator’sManual.

TestingtheIdPAdapter

YoucantestthisadapterusingtheSPsampleapplicationthatshipswithPingFederate.Followthisproceduretoverifyadapterfunctions:

1. SetupPingFederatetoruntheSPsampleapplicationaccordingtoinstructionsintheSampleApplicationQuickStartGuide.

2. ConfigureaninstanceoftheOAMAdapter(seeOAMConfigurationonpage6).

3. ReconfiguretheSPconnectiontothesampleapplicationtousetheOAMAdapterInstance.

DeletetheexistingadapterinstanceandmaptheOAMAdapterinstanceinitsplace(seeIdPAdapterMappingthePingFederateAdministrator’sManual).

Note:Use the default setting on the Assertion Mapping screen. On the Attribute Contract Fulfillment screen, map SAML_SUBJECT to the Adapter value userId. If you have extended the Adapter Contract and wish to send the extended-attribute value to the SP during SSO, you will need to add a corresponding attribute to the AttributeContract for the SP connection. Then map this attribute to the additional adapter attribute value (for example, authLevel). For any attributes in the Attribute Contract for which there are no related Adapter attributes, select Text in the Source drop-down list for each attribute and enter “test” (or any other text) in the associated text boxes.


4. OnawebpageprotectedbytheOAMAccessGate,createan“SSO”linktothePingFederatestartSSOendpoint,includingthesampleSP’sconnectionID,inthefollowingformat:

http[s]://<PF_host>:<port>/IdP/startSSO.ping?PartnerIdPId=<connection_id>

<PF_host>isthemachinerunningthePingFederateserver,<port>isthePingFederateport,<connection_id>istheConnectionIDoftheSPconnectiontothesampleapplication.

5. AccesstheprotectedwebpagebyauthenticatingthroughOAMWebgate,andclicktheSSOlink.

YouwillbeloggedontothesampleSPapplication.IfyouhavemodifiedtheconnectionAttributeContracttoincludeAuthenticationLevelandextendedtheAdapterContract,youshouldseetheauthLeveldisplayedinthe“UserAttributes”table.


SPImplementationThissectiondescribesusingtheOAMIntegrationKitasanSP.

SPProcessOverview

TheOAMSPAdapterusesanauthenticationschemedeployedwithinOracleAccessManagertocreateasessionfortheuser.

ThefollowingfigureillustratestherequestflowandhowtheOAMSPAdapterisusedtofacilitateusingaSAMLWS-FederationassertiontocreateanOAMsession:

ProcessingSteps1. An SSO assertion is sent to PingFederate acting as an SP. 2. The OAM Sp Adapter redirects the user to an OAM Protected Resource secured with a

PingFederate custom authentication scheme. 3. OAM Webgate sends a request to authenticate the user. 4. OAM Server redirects the authentication request to PingFederate. 5. OAM SP Adapter sends the required credentials back to the OAM Server. 6. The OAM Server validates the credentials and an 11g session is established.


OAMSPConfiguration1. Deploytheincludedauthenticationplug-injar(PingOpenTokenAuthPlugin.jar)withinOAM11g

andcreateanAuthenticationModule.ForinformationonauthenticationpluginspleaserefertoOAMDocumentationforAuthenticationPlug-ins.

2. Theauthenticationpluginrequirestheopentokenconfigurationfile(agent-config.txt)whichcanbeobtainedthroughtheSPadapterconfigurationasdescribedinthesectionbelow.SpecifythelocationofthisfilefortheauthenticationpluginpropertyopentokenConfigFile.

3. Createorupdateanauthenticationschemetousetheplug-indeployedinStep1.Usethefollowingvaluesfortheauthenticationschemeparameters.

Parameter Value

Challenge Method Form

Challenge Redirect URL /oam/server/

Authentication Module Select the authentication module from Step 1.

Challenge URL http(s)://<PF_HOST:PF_PORT>/ext/pf-oam-authn/sso.ping

Context Type external

4. ConfigureanOAMWebgatetousetheupdatedauthenticationscheme.

http://docs.oracle.com/cd/E27559_01/dev.1112/e27134/authnapi.htm#AIDEV191


PingFederateSPConfiguration1. UnzipthedistributionZIPfileandcopythefollowingfiletotheserver/default/deploy

folderinyourPingFederateserverinstallation:dist/pf-oam-adapter-3.0.jar

2. Addthefollowingtorun.propertieswithin<PF_HOME>/binfolder:

pf.oam.ik.ssoUrl=<PF_SSO_URL>

wherePF_SSO_URListheSp-initiatedSinglesignonURL.Forexample:https://<PF_HOST>:<PF_PORT>/sp/startSSO.ping?PartnerIdpId=<PARTNER_ID>&TargetResource=<TARGET_RESOURCE_URL>

3. StartorrestartthePingFederateServer

ConfiguringanSPAdapterInstance

AfterinstallingtheOAMIntegrationKit,youcanconfigureyourSPconnectiontouseaninstanceoftheOAMSPAdapter.Thefirstpartofthisprocessisconfiguringtheadapterinstance.

ToconfigureaninstanceoftheSPadapter:

1. LogontothePingFederateadministrativeconsoleandclickAdaptersunderSPConfigurationontheMainMenuscreen.

2. OntheManageSPAdapterInstancesscreen,clickCreateNewInstance.

3. EntertheAdapterNameandAdapterID.SelectOAM11gSPAdapter3.0astheAdapterTypeandclickNext.


4. OntheSPAdapterscreen,enterthevaluesforadapterconfigurationasdescribedonthescreenandclickNext.

5. Downloadtheopentokenconfigurationfile(agent-config.txt).Thiswillbeusedduringauthenticationpluginconfigurationforoamserver.ClickNext.

6. Optionally,ontheExtendedAdapterContractscreen,youcanconfigureadditionalattributesfortheadapter.(SeetheExtendinganAdapterContractinthePingFederateAdministrator’sManual.)

Note:ExtendedattributesarenotsupportedinthisversionofOAMIntegrationKit.

7. ClickNext.

8. OntheSummaryscreen,verifythattheinformationiscorrectandclickDone.

9. OntheManageAdapterInstancesscreen,clickSavetocompletetheadapterconfiguration.

YoucannowusethisadapterinstanceforanIdPconnection.Forinformationonsettingupormodifyingaconnection,seeManagingIdPConnectionsinthePingFederateAdministrator’sManual.

TestingtheSPAdapter

YoucantestthisadapterusingtheIdPsampleapplicationthatshipswithPingFederate.Followthisproceduretoverifyadapterfunctions:

1. SetupPingFederatetoruntheIdPsampleapplicationaccordingtoinstructionsintheSampleApplicationQuickStartGuide.

2. ConfigureaninstanceoftheOAMSPAdapter(seeConfiguringtheSPAdapter).

3. ReconfiguretheIdPconnectiontothesampleapplicationtousetheOAMAdapterinstance.

DeletetheexistingadapterinstancefortheconnectionandmaptheOAMAdapterinstanceinitsplace(seeConfiguringAdapterMappingandUserLookupinthePingFederateAdministrator’sManual).

4. FromtheMainMenu,clickAdaptersunderMySPConfigurationontheMainMenuscreen.


5. DeletetheAdapterInstancethatwaspreviouslyusedbythesample-applicationconnection.

6. ConfigureanOAM11gWebgatetousethecustomauthenticationplug-in.

7. AccessamOAMprotectedresourcewithintheOAM11gWebgatefromStep6.

YoushouldarriveattheIdPsampleapplication’sloginpage.

8. Addatleastoneoftheusersintheusernamedrop-downlisttotheOAMIdentityManager.

RefertoyourOAMdocumentationformoreinformation.

Alternatively,youcanaddusersalreadyinOAMIdentityManagertothesampleapplication’suser-propertiesfile(seetheQuickStartGuideforthelocationofthisfile).

9. Addthesameuser(s)totheAuthorizationRuleinthePolicyDomaingoverningtheprotectedWebpage.

10. OntheIdPsampleapplication’sloginpage,loginwithausernamemanagedbyOAM.

YoushouldbeallowedaccesstoOAM-protectedWebpage.

Documents

OAM Integration Kit User Guide - Ping Identity · PDF filePingFederate OAM Integration Kit 4 User Guide Introduction The PingFederate Oracle Access Manager (OAM) Integration Kit adds