User Consent Plug-ins

DirX Access supports user consent for SAML assertion exchanges (at the SAML IdP FEP Web application) and allows for the deployment of solution-specific user consent applications through a plug-in interface. This design allows conducting user consent dialogs in external applications, especially in Web applications. This chapter describes the steps needed to employ the user consent plug-in and its subsequent use.

About the Callout for User Consent

The DirX Access user consent plug-in allows callout from the SAML IdP FEP to an external user consent Web application that conducts a user consent dialog with the user to determine whether the user agrees with sending the SAML assertion created for them to the SP.

This functionality is based on the following components:

  • The DirX Access SAML IdP FEP Web application externalizing user consent decisions to an external Web application[1]

  • A custom user consent handler plug-in mounted to DirX Access SAML IdP FEP. This handler needs to implement the externalization interface com.siemens.dxa.common.callout.federation.UserConsentCallout. It invokes an external application conducting the user consent dialog.

  • An external user consent application conducting the user consent dialog and (re-)invoking the SAML SingleSignOnService on the DirX Access SAML IdP FEP Web application by (re-)sending the samlp:AuthnRequest element in an HTTP request. The user consent decision is expressed in the form of DirX Access-defined keywords and values exchanged in the HTTP request:

    • If the user agrees to send the SAML assertion to the SP, the decision must be indicated via the DirX Access-defined keywords and values[2] and the samlp:AuthnRequest must be resent to the SAML SingleSignOnService on the DirX Access SAML IdP FEP Web application. This task must be performed in unmodified form and with the same binding as originally received at the SAML SingleSignOnService.

    • If the user does not agree with sending the SAML assertion to the SP, this decision must be indicated via the DirX Access-defined keywords and values[3].

The saml:Assertion object sent to the external user consent Web application is created with the DirX Access SAML assertion creation testing functionality; that is, the saml:Assertion object sent to the external user consent Web application does not appear in auditing, etc.:

  • If the user agrees to send the SAML assertion to the SP, then an actual saml:Assertion object is generated and sent to the SP.

  • If the user does not agree to send the SAML assertion to the SP, then an exception is thrown and a SAML error is sent to the SP.

Note that the external user consent application should solve only the action of user consent decision, as it can be bypassed by a straightforward directive inclusion.

Developing a User Consent Handler Plug-in

This section describes the tasks necessary for developing a custom user consent handler plug-in.

Externalizing User Consent Handling from the DirX Access SAML IdP FEP

The DirX Access SAML IdP FEP Web application allows externalizing user consent dialog handling through a plug-in interface. This method requires creating a user consent handler that implements the UserConsentCallout interface (com.siemens.dxa.common.callout.federation.UserConsentCallout). The implementing class must be contained within an exported package of an OSGi bundle.

Employing a User Consent Handler

The steps needed to employ the custom user consent handler are outlined in the section Employing External Plug-in Modules .

Using the Custom User Consent Handler

The following tasks need to be performed to use the custom user consent handler. Before starting to configure the DirX Access Server, make sure to run through all the steps in the section Employing External Plug-in Modules.

Prerequisites

To successfully employ the custom user consent handler, the OSGi bundle exporting the package containing the callout implementation must be installed on the DirX Access Server. To accomplish this task, make sure you have performed all of the steps described in the section Employing External Plug-in Modules.

Configuring the Custom User Consent Plug-in at the DirX Access Server

To configure the custom user consent plug-in at the DirX Access Server:

  • In DirX Access Manager, go to Configuration | Extension modules.

  • Create the callout handler <CalloutIdentifier>:

    • Go to Callout handlers and then click the “add” icon to create a new callout handler.

    • Identifier: <CalloutIdentifier>.

    • Description: arbitrary.

    • Type: select UserConsentEvents.

    • Class name: enter the fully-qualified Java class name of the callout implementation.

    • Click Save.

  • In DirX Access Manager, go to Configuration | Federation | SAML | Identity provider endpoints.

    • Select a SAML IdP FEP identifier for which the custom user consent handler shall be added.

    • In the drop-down menu User consent callout handler identifier, select <CalloutIdentifier>.

    • Click Save or Update.

1. Note: in contrast to the other DirX Access callout methods, the user consent callout is mounted at the DirX Access SAML IdP FEP Web application, not at the actual DirX Access Server.
2. Keyword: DXAUserConsentDirective (= name of the HTTP request parameter containing the directive on user consent), value: EstablishedAsPermitted
3. Keyword: DXAUserConsentDirective (= name of the HTTP request parameter containing the directive on user consent), value: EstablishedAsRejected