Configuring Federated SAML Mode

Service provider (SP)

Your application: the 3DEXPERIENCE platform, which communicates with the identity provider to obtain information about the user it interacts with. User information such as authentication state and user attributes is provided in form of security assertions.

Identity provider (IDP)

Entity able to authenticate users and provides information about their identity to service providers/relaying parties using federation protocols.

Assertion

A part of an SAML message (an XML document) which provides information about the subject of the assertion (the authenticated user). Assertions can contain information about authentication, associated attributes or authorization decisions.

Single Sign-On (SSO)

Process enabling access to multiple web sites without need to repeatedly present credentials necessary for authentication. You can use various federation protocols such as SAML, WS-Federation, OpenID or OAuth to achieve SSO use-cases. The service provider receives information such as means of authentication, user attributes, authorization decisions or security tokens as part of single sign-on.

Metadata

Document describing one or multiple identity and service providers. Metadata includes entity identifier, public keys, endpoint URLs, supported bindings and profiles, and other capabilities or requirements. Exchange of metadata between identity and service providers is the first step to establish federation.

Profile

Standardized combination of protocols, assertions, bindings and processing instructions used to achieve a particular use-case such as single sign-on, single logout, discovery, artifact resolution.

The SAML implementation is mainly provided by the Spring SAML add-on. See the following source for more information:

http://docs.spring.io/spring-security-saml/docs/1.0.x/reference/html/

The SAML filters and interfaces provide security controls as well as encryption and signature of exchanged messages.

• 1. From a client (browser, native app, …), an end user attempts to connect to a 3DEXPERIENCE platform protected service provider (SP) resource (for example, 3DDashboard). The user is not logged on to this service provider.
• 2. The request is first filtered by the service provider's CAS Assertion Consumer Service to check if any valid user assertion exists in session (authenticated session).
• 3. No assertion is found so the service provider returns an HTTP redirect to the 3DPassport CAS service for SSO challenge (it tests if any valid authentication cookie exists in the browser/client).
• 4. The request does not provide a valid authentication cookie so the CAS service returns an HTTP redirect to third party identity provider SSO service
• 5. The end user is not logged on to the identity provider, and therefore needs to provide credentials (identity and password).
• 6. User attributes are retrieved from the external user repository (database, LDAP, …).
• 7. The identity provider's SSO service returns an HTML form with a signed SAML response containing the authentication assertion and user attributes. The browser automatically posts the HTML form back to 3DPassport.
• 8. The 3DPassport SAML ACS checks the validity of the SAML message signature assertion, and then creates the remote user. The user is created only the first time.
• 9. The 3DPassport CAS SSO service automatically creates the principal from the remote user using the Trusted Authentication Handler.
• 10. 3DPassport returns an HTTP redirect to the service provider with the CASTGC (authentication cookie) set in the headers, and a service ticket as a URL parameter.
• 11. The service provider's CAS ACS validates the service ticket and retrieves the user identity and attributes from the CAS SSO service response. The service provider user session is created.
• 12. The user is authenticated on the service provider. The service provider returns the resource content to the browser with a valid authenticated SessionID in the headers.

By enabling this feature, the end user will no longer authenticate to 3DPassport via the login page, but will be redirected to the configured third party identity provider. 3DPassport will act as a service provider to the third party identity provider but will still act as the identity provider for 3DEXPERIENCE platform apps which are not impacted for the SSO process.

Here is a user scenario illustrating how the feature is enabled:

• An end user is not authenticated on the 3DEXPERIENCE platform and attempts to access it, for example by trying to log onto 3DDashboard.
• The end user is redirected to 3DPassport.
• 3DPassport redirects the end user to the configured third party identity provider with a SAML Authentication Request.
• If already authenticated on the third party provider, the end user is redirected back to 3DPassport with a SAML Assertion carrying the user identity. If not, the end user is redirected to the third party identity provider login page to provide credentials. After successful authentication, the user is redirected back to 3DPassport with the SAML assertion.
• 3DPassport intercepts and processes the SAML assertion to retrieve the user principal (user ID) and potentially its attributes.
• 3DPassport creates the user session and then redirects the end user to the 3DDashboard app with a CAS ticket.
• The 3DDashboard processes the ticket and creates the end user session.
• The end user is now authenticated on the 3DEXPERIENCE platform.

You are now ready to configure federated SAML mode.

SAML metadata is an XML document which contains information necessary for interaction with SAML-enabled identity or service providers. The document contains e.g. URLs of endpoints, information about supported bindings, identifiers and public keys. Typically one metadata document will be generated for your own service provider and sent to all identity providers you want to enable single sign-on with. Similarly, each identity provider will make its own metadata available for you to import into your service provider application.

In the Metadata, click to configure the metadata:

SAML requires you to first configure the service provider metadata.

Service provider metadata contains keys, services and URLs defining SAML endpoints of your application. Metadata can be either generated automatically upon first request to the service, or it can be pre-created. Once created, metadata needs to be provided to the identity providers with whom we want to establish trust.

<!-- Initialization of OpenSAML library -->
<bean class="com.dassault_systemes.dspassport.iamweb.saml.SAMLBootstrap">
<property name="signingAlgorithm" value="http://www.w3.org/2001/04/xmldsig-more#rsa-sha1" />
</bean>

http://www.w3.org/2000/09/xmldsig#rsa-sha1
http://www.w3.org/2001/04/xmldsig-more#rsa-sha256
http://www.w3.org/2001/04/xmldsig-more#rsa-sha512

https://www.w3.org/TR/2013/NOTE-xmlsec-algorithms-20130411

General options are:

Entity Base URL

Contains by default 3DPassport URL. Serves as the base for generating URLs for this server. For example: https://<3DPassportHostname>/<3DPassportRootPath>. The public address your server will be accessed from should be used here.

Entity ID

Contains by default 3DPassport. Entity ID is a unique identifier for an identity or service provider. The value is included in the generated metadata. For example: 3DPassport.

Entity Alias

Contains by default 3DPassport. The alias is an internal mechanism allowing collocating multiple service providers on one server. The alias must be unique. For example: 3DPassport.

Security options are:

Security Profile

Exchanges of messages between identity providers and service providers with SAML protocol involves usage of digital signatures. Signatures are typically constructed using means of asymmetric cryptography and public key infrastructure with public and private keys signed by trusted certification authorities. Signatures are applied directly to parts of XML representation of SAML messages using XML. Signatures are part of the transport layer used to deliver the message like SSL/TLS.

Verification of signatures is executed in two phases. The signature is first checked for validity by comparing digital hash included as part of the signature with values calculated from the content. Subsequently, a check is performed as to whether the party who created the signature is trusted by the recipient.

Security profiles are defined in the extended metadata of the service provider (3DPassport). Profiles can be defined separately for XML signatures using a property security profile and for SSL/TLS signatures using a SSL/TLS security profile.

Security profiles determine how trusting of digital signatures is handled. Two mechanisms are supported for defining which signatures should be accepted:

PKIX

This is the default mode. In this mode, trust of signature certificates is verified based on a certificate path between trusted CA certificates and the certificate in question. A certificate is trusted when it is possible to construct a path from a trusted certificate to the validated one. With this profile, certificate expiration and revocation can be checked. Trusted keys (anchors) for PKIX verification of signatures are combined from the following places:

• key with usage of signing or unspecified in entity metadata of a remote entity
• signing key specified in property Signing key of extended metadata of a remote entity
• all keys specified in trustedKeys set of extended metadata of a remote entity, or all keys available in the key store when the property is null (default value).

Please note that trust anchors are treated as automatically trusted and are not necessarily subject to all checks as leaf certificates are (depending on your security provider implementation). You should preferably use only your CA and intermediary CA certificates as trust anchors.

MetaIOP

Stands for metadata interoperability. In this mode, certificates are not checked for expiration or revocation and certificate paths are not verified. This means that it does not matter which certification authority issued the certificate, as the fact whether the certificate is trusted or not is conveyed using other mechanisms (e.g. by secure metadata exchange or digital signature of metadata itself). Signature is deemed trusted when the certificate used to create it is included in one of the following places:

• key with usage of signing or unspecified in entity metadata of a remote entity
• signing key specified in property Signing key of extended metadata of a remote entity.

Signing key

Key used for digital signatures of SAML messages. Public key will be included in the metadata.

Encryption key

Key used for digital encryption of SAML messages sent by 3DPassport. Public key will be included in the metadata.

SSL/TLS Security profile

The SSL/TLS Security profile determines how trusting of the peer's SSL/TLS certificate (for example, during Artifact resolution) is handled:

• in MetaIOP mode, the server's SSL/TLS certificate is trusted when it is explicitly declared in metadata or extended metadata of the peer.
• in PKIX mode (default), a check is performed of the peer's certificate against a set of trust anchors. All certificates defined in metadata, extended metadata or present in the keystore are considered as trust anchors (certification authorities) for PKIX validation.

SSL/TLS Hostname Verification

Algorithm for verification of match between hostname in the URL and hostname in the presented certificate. The options are:

Standard Hostname Verifier

This is the default option. The hostname must match either the first CN, or any of the subject-alts. A wildcard can occur in the CN, and in any of the subject-alts. The only difference between standard and strict is that a wildcard (such as *.foo.com) with DEFAULT matches all subdomains, including a.b.foo.com.

Standard Hostname Verifier (skips verification for localhost)

It works like the default Standard Hostname Verifier with one additional relaxation: a host of localhost, localhost.localdomain, 127.0.0.1, ::1 will always pass, no matter what is in the server's certificate.

Strict Hostname Verifier

This mode works the same way as java.net.URL in Sun Java 1.4, Sun Java 5, Sun Java 6. It's also close to IE6. This implementation appears to be compliant with RFC 2818 for dealing with wildcards.

The hostname must match either the first CN, or any of the subject-alts. A wildcard can occur in the CN, and in any of the subject-alts. The one divergence from IE6 is how only the first CN is checked. IE6 allows a match against any of the CNs present. As in Sun Java 1.4, only the first CN is checked.

A wildcard such as *.foo.com matches only subdomains in the same level, for example a.foo.com. It does not match deeper subdomains such as a.b.foo.com.

Disable hostname verification (allow all)

This option essentially turns hostname verification off. This implementation is a No operation, and never throws the SSLException.

SSL/TLS Client authentication

Key used to authenticate this instance for SSL/TLS connections.

Sign metadata

Specifies if generated metadata will be digitally signed using the key specified for property Signing key.

Sign sent AuthNRequests

Specifies if sent authentication requests will be signed.

Require signed authentication Assertion

Specifies if received authentication assertion needs to be signed

Require signed LogoutRequest

Flag indicating to IDP whether entity in question requires logout request to be signed.

Require signed LogoutResponse

Flag indicating to IDP whether entity in question requires logout response to be signed.

Require signed ArtifactResolve

Specifies if artifact resolution requests sent to the remote identity providers need to be signed.

Binding options: bindings are to be included in the metadata for WebSSO profile. Supported values are:

• SSO HTTP-POST
• SSO Artifact.

About supported bindings

The HTTP-Redirect binding (SAML assertion in query string) is not supported for Assertion delivery. You can only select between HTTP-POST (with Redirect) and Artifact (with Redirect).

You can enforce HTTP-POST for Authentication request:

• by enforcing HTTP-POST only for SingleSignOnService when you generate your IDP metadata. The 3DPassport SAML entrypoint will loop over all bindings listed in the IDP metadata and will choose the first one supported. The supported bindings for the authentication request are: HTTP-Redirect, HTTP-POST and Artifact.
• if you cannot enforce HTTP-POST binding only on your IDP side, you can optionally enforce this binding in 3DPassport by editing the following configuration file in 3DPassport:

  <tomee>/webapps/<3dpassport>/WEB-INF/spring-configuration/applicationContext-security.xml

  and add the lines:

  <property name="bindingsSSO">
                    <list><value>post</value></list>
              </property>
              <property name="bindingsSLO">
                    <list><value>post</value></list>
              </property>

  as shown below:

  <bean id="metadataGenerator" class="org.springframework.security.saml.metadata.MetadataGenerator">
              <property name="entityBaseURL" ref="baseURL" />
              <property name="bindingsSSO">
                    <list><value>post</value></list>
              </property>
              <property name="bindingsSLO">
                    <list><value>post</value></list>
              </property>
        </bean>

  then restart TomEE.

Click Apply to save and apply your settings.

Once the service provider configuration has been saved, it is displayed in the Metadata section, for example like this:

You can export your current metadata by clicking in the Export column.

Click in the Identity Provider section:

Metadata containing one or many identity providers can be added by providing an URL or a file.

IdP URL

Specify the identity provider URL to retrieve the identity provider metadata.

Content of your IdP metadata

Copy the content of the metadata file and paste it in the text area.

Fields to synchronize from SAML assertion

This is where you define which fields from the SAML assertion will be mapped and synchronized into 3DPassport. You can select the fields that will be retrieved from the SAML assertion and synchronized in the 3DPassport local database.

The 3DPassport requires the following fields to be valued to access the 3DEXPERIENCE platform:

• email [MANDATORY]
• username [MANDATORY]
• firstName [REQUIRED]
• lastName [REQUIRED]
• country [REQUIRED].

Email and username are MANDATORY for SAML identity federation, so it is required for both attributes provided in the SAML assertion. The email or username could be either provided through the saml:Subject entity or the saml:Attribute entities.

Other fields such as firstName, lastName, or country are required to access the 3DEXPERIENCE platform, but if they are not present in the SAML assertion, the end-user will be redirected to the update profile page to fill in the missing information.

The fields listed in the combo box must be mapped in the identity provider accordingly. For example, for the lastName to be synchronized in 3DPassport, the identity provider must map the corresponding lastName field in its user repository (LDAP, for instance) that will be retrieved after authentication, to the corresponding SAML attribute.

Note: The SAML attribute name MUST HAVE the same name, with the same case, as the field declared in 3DPassport as listed above.

Here is an example of what is expected to be provided in the SAML assertion:

<saml:Subject>
<saml:NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified">myusername</saml:NameID>
<saml:SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer">
<saml:SubjectConfirmationData Recipient="https://<myhostname>/saml/SSO/alias/<myhostname>" 
NotOnOrAfter="2016-12-20T20:45:02.191Z" InResponseTo="a2458h5i1dc6h7fhebhcig04133a5f"/>
</saml:SubjectConfirmation>
</saml:Subject>
…
<saml:AttributeStatement>
<saml:Attribute Name="email" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
<saml:AttributeValue xsi:type="xs:string" xmlns:xs="http://www.w3.org/2001/XMLSchema" 
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">myemail@somedomain.com
</saml:AttributeValue>
</saml:Attribute>
<saml:Attribute Name="username" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
<saml:AttributeValue xsi:type="xs:string" xmlns:xs="http://www.w3.org/2001/XMLSchema" 
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">myusername
</saml:AttributeValue>
</saml:Attribute>
<saml:Attribute Name="firstName" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
<saml:AttributeValue xsi:type="xs:string" xmlns:xs="http://www.w3.org/2001/XMLSchema" 
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">My FirstName
</saml:AttributeValue>
</saml:Attribute>
<saml:Attribute Name="country" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
<saml:AttributeValue xsi:type="xs:string" xmlns:xs="http://www.w3.org/2001/XMLSchema" 
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">USA
</saml:AttributeValue>
</saml:Attribute>
<saml:Attribute Name="lastName" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
<saml:AttributeValue xsi:type="xs:string" xmlns:xs="http://www.w3.org/2001/XMLSchema" 
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">My LastName
</saml:AttributeValue>
</saml:Attribute>
</saml:AttributeStatement>

The end result may look something like this:

Toggle the Enable SAML authentication to enable SAML:

Toggle the button in the Active column to disable or enable the identity provider, or click to edit.

When attempting to log onto the 3DEXPERIENCE platform, the end user is first redirected to the third party identity provider login page. After successful authentication by the identity provider, the user is redirected back to 3DEXPERIENCE platform.

If all the required attributes to access the 3DEXPERIENCE platform have been retrieved from the SAML assertion, the user is then automatically authenticated and redirected back to the 3DEXPERIENCE platform (3DDashboard service).

If certain attributes are missing from the SAML assertion, the user is redirected to the 3DPassport update page to update the end user's account. After providing the missing attributes and updated the account, the user is redirected back to the 3DEXPERIENCE platform.

By default, 3DPassport will not accept SAML assertion generated by the identity provider that is more than one day old. The value set must be equal to (recommended, or at least greater than) the equivalent property of your SAML identity provider.

By default, it is valued to 86400s = 1 day = 24h.

1. Open the following file <tomee>/webapps/3dpassport/WEB-INF/spring-configuration/applicationContext-security.xml
2. Update the maxAuthenticationAge property (specified in seconds), in the webSSOprofileConsumer bean:

   <bean id="webSSOprofileConsumer"
   
       class="org.springframework.security.saml.websso.WebSSOProfileConsumerImpl">
   
       <property name="maxAuthenticationAge" value="86400" />
   
   </bean>