SAML Configuration
- 1. Change the application’s security provider to SAML
- 2. Use the SAML security module
- 3. Add a SAML security configuration file
- 4. Add the IdP metadata to the application
- 5. Add the IdP security certificates
- 6. Ensure the IdP is configured for integration with the SP (the Appkit application)
- Testing the SAML provided SSO
As SAML is a flexible standard supporting varied security 'architectures', it is necessary to have a clear understanding of the authentication setup against which the Appkit application will be using. This said the SAML module is highly flexible, supporting a range of configurations.
In this example, we assume a fairly straightforward configuration of authentication against an IdP providing the SSO login form. The Appkit application acts as an SP that authenticates against this IdP (requiring configuration of the IdP to accept login requests for this application).
It is also assumed that the entire Appkit application is secured by the SSO and the desired behavior is to redirect the user to the IdP’s login form if they are not authenticated. However it is very simple to modify the application to allow anonymous access where login is only required for extra features.
1. Change the application’s security provider to SAML
Simply modify the security provider type to saml in security.conf:
type: saml2. Use the SAML security module
Add this dependency to the application’s pom.xml file. If an existing security provider is configured (an artifactId starting with twigkit.security.provider), replace the existing dependency with this dependency:
<dependency>
<groupId>twigkit</groupId>
<artifactId>twigkit.security.provider.saml</artifactId>
<version>${project.parent.version}</version>
</dependency>3. Add a SAML security configuration file
-
Create a SAML configuration file at:
src/main/resources/conf/security/saml.conf. Add this content:sso-url: http://your-sso-host/idp-initiated-login-page slo-url: http://your-sso-host/idp-single-logout-page entity-id: unique-id-for-this-service-provider
-
Change the properties to relevant values as described here:
sso-url: Configure application’s login failure redirect endpoint (SSO URL).slo-url: Configure application’s logout success redirect URL (SLO URL). Typically this is the URL at the IdP which triggers 'Single Logout' (SLO), logging out the user from the IdP system entirely.entity-id: Define the SP (partner) entity ID for this application (as configured in the IdP backend). If not already defined, choose a unique identifier to use to refer to this SP and provide this to the IdP.
4. Add the IdP metadata to the application
This simply requires an export of the IdP’s metadata from the IdP itself. This file should then be saved as 'idp-metadata.xml' under the src/main/resources directory. You can if necessary also configure a custom metadata XML file location using:
idp-metadata-file: path of the IdP metadata file relative to src/main/resources (defaults to 'idp-metadata.xml').
The majority of IdPs provide this metadata export functionality. In this case, we are using PingFederate (see the screenshots below).
In the PingFederate admin UI, choose Administrative functions > Metadata Export.
5. Add the IdP security certificates
Depending on the security certificates used, different configurations are required. Often the IdP metadata XML file supplies the correct certificate - in which case, you do not need any extra configuration.
However in many cases you must import the public key for the certificate used by the IdP (for SSL encryption and to sign SAML messages) to the keystore used by the application.
By default, this keystore is configured to be located at src/main/resources/samlKeystore.jks.
In the case of SP initiated SSO, you will also must upload the keys used by the SP to sign SAML requests to the IdP system’s trusted certificate store.
6. Ensure the IdP is configured for integration with the SP (the Appkit application)
In some integration scenarios, the IdP will have already set these properties and might require you to configure the Appkit application accordingly. However, the application’s SSO consumer and SLO service URLs should be defined by the SP and provided to the IdP for them to configure within the IdP system.
It is possible to export the SP metadata as XML from a running application, however, because IdP implementations can vary, we recommend that this is configured in the IdP system manually using these settings:
SP (partner) entity ID: As configured in saml.conf.
Protocol: SAML 2.0
Browser SSO: true
IdP initiated SSO & SLO: true
Assertion consumer service endpoint URL: (POST or Artifact) http://your-twigkit-host/your-twigkit-app/saml/SSO
SLO service URL: (POST) http://your-twigkit-host/your-twigkit-app/logout/
Artifact resolver location: http://your-twigkit-host/your-twigkit-app/saml/SSO/
Testing the SAML provided SSO
-
Run the Appkit application and navigate to the root of the application context (for example,
http://localhost:8080/).You should be presented with the IdP’s login form; see the example below:
-
Enter valid credentials for a user in the IdP’s set of users.
You will be logged into Appkit and should see the main applications search page, including the user’s details:
When logout is selected, the user should be logged out using SLO and presented with the IdP’s configured 'successful logout' page:
If you navigate to the root of the application again (or any application backed by this IdP) you should then be presented with the login form.
If this authentication lifecycle behaves as shown above, then the SAML authentication is configured and working. Obviously, the IdP screens will vary between providers and many providers let you customize these pages to fit the branding of the organisation.
Removing SAML form-based authentication
If the IdP does not use form based authentication as a fallback mechanism, remove the defaultFailureUrl property from the unauthenticatedRedirectHandler bean.
<beans:property name="defaultFailureUrl" value="${slo-url:https://localhost:9031/idp/startSSO.ping?PartnerSpId=SAMMY}"/>