Page Comparison

...

1. Most IDP requires https, so you may have to configure Tomcat to use https (SSL/TLS).

2. Ensure that Semarchy's Tomcat tools are available (89.50.10 3 or more). This is to permit mapping of external groups (such as Active Directory groups or OKTA groups) to Semarchy roles (referred to as "role mapping"). Semarchy's Tomcat tools file ships with Semarchy xDM (com.semarchy.tool.jee.tomcat-89.50.x.jar). 

   Code Block
   language bash title Check Tomcat tool availability
   # Is com.semarchy.tool.jee.tomcat-* present? ls -l /usr/share/tomcat8tomcat9/lib/

   If the jar file is not present, then get it from the standard Semarchy Installation files.

   Code Block
   language bash title Get Tomcat tools from standard Semarchy installation
   # Get Semarchy Install # Browser version of these steps: # 1. Download from "Server Installation" from here: https://www.semarchy.com/all-downloads/ # 2. Unzip the xDM Server Installation zip file # Command line version. (correct for 5.2.3): curl https://www.semarchy.com/downloads/products/5.2/semarchy-xdm-install-5.2.3.ga-20200807-0643.zip -O # Extract Semarchy Tomcat Tools from the .zip file unzip -j semarchy-xdm-install-5.2.3.ga-20200807-0643.zip mdm-server/additional-libraries/com.semarchy.tool.jee.tomcat-8.5.10-ga-20200807-0643.jar # Copy the jar into place sudo cp com.semarchy.tool.jee.tomcat-8.5.10-ga-20200807-0643.jar /usr/share/tomcat8/lib/

   
   

3. Download latest Fediz 1.5 connector 6 connector for tomcat (with dependencies) here :
   https://repo1.maven.org/maven2/org/apache/cxf/fediz/fediz-tomcat/1.56.1/fediz-tomcat-1.56.1-zip-with-dependencies.zip

   Code Block
   language bash title Example of getting the Fediz connector
   curl https://repo1.maven.org/maven2/org/apache/cxf/fediz/fediz-tomcat/1.56.1/fediz-tomcat-1.56.1-zip-with-dependencies.zip -O unzip fediz-tomcat-1.56.1-zip-with-dependencies.zip

   
   

4. Create sub-directory called Fediz to hold the fediz jar files in ${catalina.home}/lib

   Code Block
   language bash title Example of creating Fediz directory
   sudo mkdir /usr/share/tomcat8tomcat9/lib/fediz

   
   

5. Update catalina.properties in ${catalina.home}/conf to add the previously created directory to the common loader:

   Code Block
   language bash title Updating catalina.properties
   # original common.loader=${catalina.base}/lib,${catalina.base}/lib/*.jar,${catalina.home}/lib,${catalina.home}/lib/*.jar # modified common.loader=${catalina.base}/lib,${catalina.base}/lib/*.jar,${catalina.home}/lib,${catalina.home}/lib/*.jar,"${catalina.home}/lib/fediz/*.jar"

   
   

6. Deploy the libraries to the directory created in step 4.

   Code Block
   language bash title Deploying libraries
   sudo cp /tmp/*.jar /usr/share/tomcat8tomcat9/lib/fediz/

   
   

7. Configure Fediz Valve in semarchy.xml
   Remove (comment out) the existing FormAuthenticator and replace it with FederationAuthenticator.

   Code Block
   language xml title Configure Fediz valve in semarchy.xml with Role Mapping
   <!-- This is the default authenticator valve <Valve className="org.apache.catalina.authenticator.FormAuthenticator" landingPage="/" /> --> <!-- This Semarchy class is based on the Fediz class. It allows us to do role mapping and to do fallback for REST API authentication. --> <!-- https://www.semarchy.com/doc/semarchy-xdm/semng.html#using-the-tomcat-role-mapper --> <Valve className="com.semarchy.tool.jee.tomcat.FederationAuthenticator" rolesMappingPathName="/some/custom/path/my-roles-mapping.properties" configFile="conf/fediz_config.xml" keepMappedRoles="false" keepUnmappedRoles="false" /> <!-- Example: store credentials to be used for REST calls in tomcat-users.xml. This works because we do preemptive basic authentication. (Won't work for form login.) --> <!-- <Realm className="org.apache.catalina.realm.UserDatabaseRealm" resourceName="UserDatabase"/> -->

   
   

   Code Block
   language xml title Configure Fediz valve in semarchy.xml without Role Mapping
   <!-- This is the default authenticator valve <Valve className="org.apache.catalina.authenticator.FormAuthenticator" landingPage="/" /> --> <Valve className="org.apache.cxf.fediz.tomcat.FederationAuthenticator" configFile="conf/fediz_config.xml" /> <!-- This Semarchy class is based on the Fediz class. It allows us to do role mapping and to do fallback for REST API authentication. --> <!-- https://www.semarchy.com/doc/semarchy-xdm/semng.html#using-the-tomcat-role-mapper --> <!-- <Valve className="com.semarchy.tool.jee.tomcat.FederationAuthenticator" configFile="conf/fediz_config.xml" /> <!-- Example: store credentials to be used for REST calls in tomcat-users.xml. This works because we do preemptive basic authentication. (Won't work for form login.) <Realm className="org.apache.catalina.realm.UserDatabaseRealm" resourceName="UserDatabase"/> -->

   
   

8. You need to provide the relevant cert to Tomcat so that your authentication provider (for example OKTA) will trust Tomcat.

   Create a keystore (or use your existing keystore) and import your Identity Provider certificate for your Semarchy xDM application (Note that if your Identity Provider certificate is a PEM file you can skip keystore import and point configuration directly to it).
   For example, in OKTA when using SAML download the X.509 Certificate for your Semarchy xDM instance as "okta.cert" (you'll have different certs for each application: dev, prod, etc.)

   Code Block
   language bash
   # Sample import into a keystore keytool -import -trustcacerts -alias customer_saml_cert -file okta.cert -keystore keystore.jks

   
   

9. Configure your Identity Provider.
   For example, configure Okta as described here: https://developer.okta.com/standards/SAML/setting_up_a_saml_application_in_okta.
   Specifically it's best to set the 'Audience URI (SP Entity ID)' to the server URL including context. For example, http://example.com/semarchy/ or https://example.com/semarchy/. This is what Semarchy will expect, by default, in the response token from Okta. This should match the 'audienceItem' section of the fediz_config.xml file as described in step 10.
   If the 'Audience URI (SP Entity ID)' setting in Okta needs to be something other than the server URL, you must configure the 'audienceItem' AND add a realm in the protocol section of fediz_config.xml as described in step 10. This is due to the fact that Fediz can also be used as an IDP itself or used for relaying authentication and not just a SP.

10. Configure Fediz by creating fediz_config.xml here: ${catalina.home}/conf/fediz_config.xml
    References:
    http://cxf.apache.org/fediz-configuration.html
    https://github.com/apache/cxf-fediz/blob/master/plugins/core/src/main/resources/schemas/FedizConfig.xsd
    Additional samples in "Sample Configurations" below

    Code Block
    language bash title Create fediz_config.xml
    sudo vim /etc/tomcat8tomcat9/fediz_config.xml

    
    

    Code Block
    language xml title Configure fediz_config.xml
    <?xml version="1.0" encoding="UTF-8" standalone="yes"?> <FedizConfig> <contextConfig name="/semarchy"> <audienceUris> <audienceItem>https://mydomain:8443/semarchy/</audienceItem> <!-- This value must match the Okta 'Audience URI (SP Entity ID)' setting. If the 'Audience URI (SP Entity ID)' setting is not the server URL including context, you must also set the optional realm below in the protocol section. See step 9.--> </audienceUris> <certificateStores> <trustManager> <keyStore file="conf/keystore.jks" password="keystore_password" type="JKS" /> </trustManager> </certificateStores> <!-- maximumClockSkew sets the tolerance time between IDP and SP. It is still highly recommended to synchronize servers through NTP --> <!-- <maximumClockSkew>10</maximumClockSkew> --> <trustedIssuers> <issuer certificateValidation="PeerTrust" /> </trustedIssuers> <!-- Only one protocol may be defined. Here are two examples. --> <!-- WS-Federation protocol: --> <protocol xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="federationProtocolType" version="1.2"> <issuer><!-- Your Identity Provider Issuer. For example: https://login.customer.com/adfs/ls/ --></issuer> <roleURI><!-- Your URI to get roles. For example for ADFS: http://schemas.microsoft.com/ws/2008/06/identity/claims/role --></roleURI> </protocol> <!-- SAML protocol: --> <!-- Comments on frequently used values: doNotEnforceKnownIssuer is used when: - Fediz is expecting issuer as specified above (SSO IDP URL), Okta is sending something else disableDeflateEncoding is used when: - Fediz is expecting SAML response to be gziped, Okta is not compressing response --> <protocol xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="samlProtocolType" version="2.0"> <doNotEnforceKnownIssuer>true</doNotEnforceKnownIssuer> <disableDeflateEncoding>true</disableDeflateEncoding> <issuer> <!-- Your Identity Provider Single Sign on URL. This should link to a login screen. Examples: https://mydomain.okta.com/app/mydomaine_semarchydev_1/hsosjgkwlsjCUREU7T2p6/sso/saml https://YOUR.PINGFEDERATE.SERVER/idp/SSO.saml2 https://www.mysite.com/adfs/ls --> </issuer> <!-- Your roleURI configuration could be different, but "groups" is often the roleURI. --> <roleURI>groups</roleURI> <!-- The realm tag is not generally required. It is needed, for example, if the Okta 'Audience URI (SP Entity ID)' setting is not set to the server URL including context. See step 9 for more details. --> <!-- <realm type="String">http://10.10.10.10/semarchy/welcome</realm> --> </protocol> <!-- Uncomment logoutURL below to enable SSO logout --> <!--<logoutURL>/sem_check2</logoutURL>--> <!-- Or uncomment below to enable local logout with redirect to you have been logged out page --> <!--<logoutRedirectToConstraint>.*</logoutRedirectToConstraint>--> </contextConfig> </FedizConfig>

    
    

...