Configure SSO with SAML

Introduction

This page explains how to configure the Axway SSO agent to use SAML protocol. The feature is based on the SAML (Security Assertion Markup Language) 2.0 specification, which defines an XML-based protocol that uses security tokens containing assertions to pass information about a principal – usually an end user – between a SAML authority (called an identity provider) and a SAML consumer (named a service provider).

Concepts

Service provider

A Service Provider (SP) protects access to requested resources, such as web sites and applications by applying a security policy. For example, the SP blocks all access to an unauthenticated user and routes the request to the Identity Provider. Axway Decision Insight (DI) acts as an SP. 

Identity provider

An Identity Provider (IdP) is a system that creates, maintains, and manages identity information for users, services, or systems, and provides authentication to other service providers (applications) within a network. An IdP is a trusted entity that users and servers can rely on when they are establishing a dialog that must be authenticated. The IdP sends an attribute assertion containing trusted information about the user to the SP. In an Axway deployment, the IdP is a third-party product.

Examples of IdP: KeycloakOKTAWSO2Shibboleth, etc.

User Agent

A user agent is usually a Web browser. The person who uses the browser can be referred to as a user or as a principal.  

Login process with SSO SAML

Configuration

To activate SSO with SAML:

  1. Create the SSO configuration file. It describes service provider configuration and additional properties for identity providers.

  2. Create SAML metadata file. It describes identity provider configuration.

  3. Activate the SSO agent SAML configuration byreferencing it into platform.properties:

    reference set SSO config file into platform.properties
    # SSO configuration
    axway.sso.config.file=${com.systar.platform.conf.dir}/axway-sso-service-provider.xml
    # logout URL that will be used after local ADI session will be closed (check logoutUri of ServiceProvider configuration)
    com.systar.photon.application.auth.ssoDisconnectedPageUrl=/logoutSso

SSO configuration file

Here are full examples of SSO configuration file related to SAML usage.

Purpose Configuration example

Basic sample. Works with standard use cases.

Only entityId , metadataUrl and logoutUri should be modified depending of the specificity of the environment.

Metadata signature validation and certicate validation features are disabled.

Sample SSO configuration file (i.e axway-sso-service-provider.xml)
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<SSOConfiguration>
    <CertificateValidation pathValidation="false"/>
    <ServiceProvider entityId="samlSpAxwayTest" useAppSessions="true" filteredUri="/login" logoutUri="/logoutSso">
        <AssertionConsumerService binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" location="/saml"/>
        <SingleLogoutService binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" location="/samlout"/>
    </ServiceProvider>
    <IdentityProviders>
        <SamlIdentityProvider entityId="https://idp.example.axway.int:9443/auth/realms/master" metadataUrl="./metadata.xml"
            verifyAssertionExpiration="false" sign="false">
            <Mappings>
                <RenameMapping source="firstName" target="com.systar.userPrincipal.firstName"/>
                <RenameMapping source="lastName" target="com.systar.userPrincipal.lastName"/>
                <RenameMapping source="email" target="com.systar.userPrincipal.email"/>
            </Mappings>
            <Features>
                <Feature key="saml-verify-metadata-signature" value="false"/>
            </Features>
        </SamlIdentityProvider>
    </IdentityProviders>
</SSOConfiguration>

Basic sample with checks on assertions. Same sample but with more checks on assertions:

  • keystore added (sign feature set to "true", the default value) for:

    • assertion signatures
    • encrypting assertions
  • verifyAssertionExpiration activated (uses the default value)
Sample SSO configuration file (i.e axway-sso-service-provider.xml) with checks on assertions
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<SSOConfiguration>
    <CertificateValidation pathValidation="false"/>
    <ServiceProvider entityId="samlSpAxwayTest" useAppSessions="true" filteredUri="/login" logoutUri="/logoutSso"
                     keystore="/PATH/TO/KEYSTORE/samlSpAxwayLocalhost.jks" keystorePassphrase="changeit" keyAlias="samlSpAxwayLocalhost">
        <AssertionConsumerService binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" location="/saml"/>
        <SingleLogoutService binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" location="/samlout"/>
    </ServiceProvider>
    <IdentityProviders>
        <SamlIdentityProvider entityId="https://localhost:8443/auth/realms/master" metadataUrl="./metadata.xml">
            <Mappings>
                <RenameMapping source="firstName" target="com.systar.userPrincipal.firstName"/>
                <RenameMapping source="lastName" target="com.systar.userPrincipal.lastName"/>
                <RenameMapping source="email" target="com.systar.userPrincipal.email"/>
            </Mappings>
            <Features>
                <Feature key="saml-verify-metadata-signature" value="false"/>
            </Features>
        </SamlIdentityProvider>
    </IdentityProviders>
</SSOConfiguration>

<CertificateValidation> element

This feature is used to validate on startup  the specified service provider and identity providers certificates.

Attribute Description

pathValidation

Activate path validation for provided certificates.

(question) this feature is not activated. Value must be false

<ServiceProvider> element

Describes the service provider. Mandatory attributes:

Attribute Description
entityId

Sets the unique identifier of the service provider. This identifier is sent to the IdP so it can know who is requesting an authentication or a logout.

Note: Use this exact same value for the entityID property in the SAML metadatafile .

useAppSessions

Delegates the session management to the application. See Session management for more information.

Value must be true

filteredUri

Specifies the URI of the SSO filter entry point for authentication. If the user is not authenticated, a SAML authentication request is built and sent to the IdP. Otherwise, the security token is forwarded to the application.

Value must be "/login"

logoutUri

Specifies the URI of the SSO filter entry point for the logout process. The SSO filter generates a logout request and sends it to the IdP.

(warning) If SSO mode permissive is activated, com.systar.photon.application.auth.ssoDisconnectedPageUrl must match this value in order to work correctly.

<AssertionConsumerService> element

Specifies an entry point for receiving SAML Assertions from the IdP.

Attribute Description
location

Entry point for receiving Saml Assertions from the IdP.

Example of value: "/saml"

binding

Defines how SAML protocol messages can be transported. Nowadays only HTTP-POST binding is managed.

Value must be "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"

<SingleLogoutService> element

Specifies the identity provider URL where the logout responses are sent.

Attribute Description
location

Specifies the identity provider URL where the logout responses are sent.

Example of value: "/samlout"

binding

Defines how SAML protocol messages can be transported. Currently, only HTTP-POST binding is managed.

Value must be "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"

<SamlIdentityProvider> element

Describes the entity that exchanges SAML messages with the SSO module. Mandatory attributes:

Attribute Description
entityId

The entityId and format attributes are used to uniquely identify the idP configuration. These values must match the entityId and format values of the Issuer element in the SAML assertions.

If format is not set in the assertion, the format element must be omitted in the IdP configuration.

metadataUrl

Specify the path of the metadata file.

userNameAttribute

Sets the name of the identity provider attribute that provides the username property on DI side. Default value is the Subject element in the assertions of an authentication response message.

verifyAssertionExpiration

Verifies the validity period of an assertion. Default value is "true".

Make sure that there is not conflict in server time between the IdP server and  DI; otherwise authentication will fail because of expired SAML assertions.

sign

Sign SAML messages provided by SSO agent. Default value is " true ".

keystore

Specifies the name of a keystore where the private key of the service provider is stored.

The private key is used when the service provider needs to decrypt messages that the identity provider has previously encrypted with the service provider public key. If messages are not configured to be encrypted on the identity provider side, the keystore can be omitted.

If this attribute is set, the keystorePassphrase attribute and the keyAlias attribute must also be set. The keystore must be in the classpath of the application or in its working directory. The keystore format must be JKS.

keystorePassphrase

Specifies the password of the keystore if one is set.

keyAlias

Specified the alias of the service provider private key in the keystore if one is set.


<Mappings> and <RenameMapping> elements

This element contains the mappings to apply to the IdP attributes. For DI, map the relevant attribute from the IdP to its DI counterpart, so you can keep the attribute value.

Attribute Description

source

name of identity provider attribute

target

Possible values that will match user property on DI side:

  • com.systar.userPrincipal.firstName
  • com.systar.userPrincipal.lastName
  • com.systar.userPrincipal.email
  • com.systar.userPrincipal.description

<Features> and <Feature> elements

The SP and the IdPs can be fine-tuned by setting extra features in the configuration file.

Currently, we want to deactivate the metadata file signature verification feature:

mandatory
<Features>
    <Feature key="saml-verify-metadata-signature" value="false"/>
</Features>

SAML metadata file

The SAML metadata file is an XML document which contains information necessary for interaction with SAML-enabled identity or service providers. The document contains, for example, URLs of endpoints, information about supported bindings, identifiers and public keys.

The file of this file is standard and compliant with Saml metadata. Here's a full example:

Sample SAML metadata file (i.e metadata.xml)
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<EntitiesDescriptor xmlns="urn:oasis:names:tc:SAML:2.0:metadata" xmlns:dsig="http://www.w3.org/2000/09/xmldsig#">
    <EntityDescriptor entityID="https://idp.example.axway.int:9443/auth/realms/master">
        <IDPSSODescriptor protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
            <KeyDescriptor use="signing">
                <dsig:KeyInfo>
                    <dsig:X509Data>
                        <dsig:X509Certificate>MIICmzCCAYMCB(...)</dsig:X509Certificate>
                    </dsig:X509Data>
                </dsig:KeyInfo>
            </KeyDescriptor>
            <SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://idp.example.axway.int:9443/auth/realms/master/protocol/saml"/>
            <SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://idp.example.axway.int:9443/auth/realms/master/protocol/saml"/>
        </IDPSSODescriptor>
    </EntityDescriptor>
</EntitiesDescriptor>

<EntitiesDescriptor>, <EntityDescriptor> and <IDPSSODescriptor> elements

entityID

It is the same value as the entityId of IdP in the SSO configuration. See <ServiceProvider>element.

<SingleSignOnService> element

Specifies the IdP URL where the authentication requests are sent. Currently, only HTTP-POST binding is managed.

<SingleLogoutService> element

Specifies the IdP URL where the logout responses are sent. Currently, only HTTP-POST binding is managed.

<X509Certificate> element

Specifies the certificate of the IdP. This corresponds to the base64 encoded value between the "BEGIN CERTIFICATE" and "END CERTIFICATE" of a PEM format certificate.

Related Links