oam integration kit user guide - ping identity · pdf filepingfederate oam integration kit 4...
TRANSCRIPT
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
PingFederate OAM Integration Kit 3 User Guide
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
PingFederate OAM Integration Kit 4 User Guide
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
PingFederate OAM Integration Kit 5 User Guide
IdPImplementationThissectiondescribesusingtheOAMIntegrationKitasanIdP.
IdPProcessOverview
TheOAMIdPAdapterusestheAccessServerSDKtodecrypttheOAMsessioncookieandpassattributestothePingFederateserver.YoucanthenaddattributevaluestotheAttributeContractinthePingFederateadministrativeconsoleandtransferthemtoapartnerapplicationinaSAMLassertion.(Formoreinformation,see:CreatinganAttributeContractinthePingFederateAdministrator’sManual.)
ThefollowingfigureillustratestherequestflowandhowtheOAMIdPAdapterisusedtofacilitategeneratingaSAMLWS-FederationassertionfromtheObSSOCookie:
ProcessingSteps
1. UserinitiatessinglesignonthroughPingFederate.
2. TheOAMIdPAdapterredirectstheusertoanOAMProtectedResource.
3. OAMWebgateauthenticatestheuser.
4. AftersuccessfulauthenticationanOAM11gsessionisestablishedandahostlevelcookieiscreatedfortheWebgate.
PingFederate OAM Integration Kit 6 User Guide
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
PingFederate OAM Integration Kit 7 User Guide
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
PingFederate OAM Integration Kit 8 User Guide
–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.
PingFederate OAM Integration Kit 9 User Guide
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.
PingFederate OAM Integration Kit 10 User Guide
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.
PingFederate OAM Integration Kit 11 User Guide
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.
PingFederate OAM Integration Kit 12 User Guide
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.
PingFederate OAM Integration Kit 13 User Guide
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.
PingFederate OAM Integration Kit 14 User Guide
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.
PingFederate OAM Integration Kit 15 User Guide
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.