Configuring single sign-on

Antavo’s single sign-on (SSO) solution is implemented through the communication of three different servers.

First, the connection between the identity provider (IdP) and Keycloak server needs to be established. The client’s IdP stores the login data of their users. SAML 2.0 / OIDC protocol is used for connecting this information with the Keycloak server.

The following table defines the attributes that are configurable at the integration of SSO.

Config Name	Should be filled out by	Description
Service Provider Entity ID	Client	The SAML Entity ID that the remote Identity Provider (IdP) uses to identify requests from this Service Provider. By default, this setting is set to the realms base URL `<root>/realms/{realm-name}`.
Single Sign-On Service URL	Client	The SAML endpoint that starts the authentication process. If your SAML IdP publishes an IDP entity descriptor, the value of this field is specified there.
Single Logout Service URL	Client	The SAML logout endpoint. If your SAML IdP publishes an IdP entity descriptor, the value of this field is specified there.
Backchannel Logout	Antavo/Client	The SAML logout endpoint. If your SAML IDP publishes an IDP entity descriptor, the value of this field is specified there.
Backchannel Logout	Client	Toggle this switch to ON if your SAML IDP supports back channel logout.
NameID Policy Format	Client	The URI reference corresponding to a name identifier format. By default, Keycloak sets it to `urn:oasis:names:tc:SAML:2.0:nameid-format:persistent`.
Principal Type	Client	This attribute specifies which part of the SAML assertion will be used to identify and track external user identities. It can be either Subject NameID or SAML attribute (either by name or by friendly name). Subject NameID value can not be set together with `urn:oasis:names:tc:SAML:2.0:nameid-format:transient` NameID Policy Format value.
Principal Attribute	Client	If a Principal type is non-blank, this field specifies the name ("Attribute [Name]") or the friendly name ("Attribute [Friendly Name]") of the identifying attribute.
Allow create	Client	Allow the external identity provider to create a new identifier to represent the principal.
HTTP-POST Binding Response	Antavo/Client	Controls the SAML binding in response to any SAML requests sent by an external IDP. When OFF, Keycloak uses Redirect Binding.
HTTP-POST Binding for AuthnRequest	Antavo/Client	Controls the SAML binding when requesting authentication from an external IDP. When OFF, Keycloak uses Redirect Binding.
Want AuthnRequests Signed	Antavo	When ON, Keycloak uses the realm’s keypair to sign requests sent to the external SAML IDP.
Signature Algorithm	Client	If Want AuthnRequests Signed is ON, the signature algorithm to use.
SAML Signature Key Name	Antavo	Signed SAML documents sent using POST binding contain the identification of signing key in `KeyName` element, which, by default, contains the Keycloak key ID. External SAML IDPs can expect a different key name. This switch controls whether `KeyName` contains: * `KEY_ID` - Key ID. * `CERT_SUBJECT` - the subject from the certificate corresponding to the realm key. Microsoft Active Directory Federation Services expect `CERT_SUBJECT`. * `NONE` - Keycloak omits the key name hint from the SAML message.
Force Authentication	Antavo	The user must enter their credentials at the external IDP even when the user is already logged in.
Validate Signature	Antavo	When ON, the realm expects SAML requests and responses from the external IDP to be digitally signed.
Validating X509 Certificate	Antavo	The public certificate Keycloak uses to validate the signatures of SAML requests and responses from the external IDP.
Sign Service Provider Metadata	Antavo/Client	When ON, Keycloak uses the realm’s key pair to sign the SAML Service Provider Metadata descriptor.
Pass subject	Client	Controls if Keycloak forwards a `login_hint` query parameter to the IDP. Keycloak adds this field’s value to the login_hint parameter in the AuthnRequest’s Subject so destination providers can pre-fill their login form.
Attribute Consuming Service Index	Client	Identifies the attribute set to request to the remote IDP. Keycloak automatically adds the attributes mapped in the identity provider configuration to the autogenerated SP metadata document.
Attribute Consuming Service Name	Client	A descriptive name for the set of attributes that are advertised in the autogenerated SP metadata document.

SAML 2.0 metadata configuration

The following is an example of metadata for a SAML 2.0 system entity acting as a service provider. This xml is exportable from the IdP side and these data need to be sent over to Antavo’s administrator – they will import it to Keycloak’s server.

<EntityDescriptor
    xmlns="urn:oasis:names:tc:SAML:2.0:metadata"
    entityID="loadbalancer-3.example.com">
    <IDPSSODescriptor
        WantAuthnRequestsSigned="false"
        protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
        <KeyDescriptor use="signing">
            <KeyInfo xmlns="http://www.w3.org/2000/09/xmldsig#">
                <X509Data>
                    <X509Certificate>
MIICZDCCAg6gAwIBAgICBr8wDQYJKoZIhvcNAQEEBQAwgZIxCzAJBgNVBAYTAlVTMRMwEQYDVQQI
EwpDYWxpZm9ybmlhMRQwEgYDVQQHEwtTYW50YSBDbGFyYTEeMBwGA1UEChMVU3VuIE1pY3Jvc3lz
dGVtcyBJbmMuMRowGAYDVQQLExFJZGVudGl0eSBTZXJ2aWNlczEcMBoGA1UEAxMTQ2VydGlmaWNh
dGUgTWFuYWdlcjAeFw0wNzAzMDcyMTUwMDVaFw0xMDEyMDEyMTUwMDVaMDsxFDASBgNVBAoTC2V4
YW1wbGUuY29tMSMwIQYDVQQDExpMb2FkQmFsYW5jZXItMy5leGFtcGxlLmNvbTCBnzANBgkqhkiG
9w0BAQEFAAOBjQAwgYkCgYEAlOhN9HddLMpE3kCjkPSOFpCkDxTNuhMhcgBkYmSEF/iJcQsLX/ga
pO+W1SIpwqfsjzR5ZvEdtc/8hGumRHqcX3r6XrU0dESM6MW5AbNNJsBnwIV6xZ5QozB4wL4zREhw
zwwYejDVQ/x+8NRESI3ym17tDLEuAKyQBueubgjfic0CAwEAAaNgMF4wEQYJYIZIAYb4QgEBBAQD
AgZAMA4GA1UdDwEB/wQEAwIE8DAfBgNVHSMEGDAWgBQ7oCE35Uwn7FsjS01w5e3DA1CrrjAYBgNV
HREEETAPgQ1tYWxsYUBzdW4uY29tMA0GCSqGSIb3DQEBBAUAA0EAGhJhep7X2hqWJWQoXFcdU7eQ
        </KeyDescriptor>
        <KeyDescriptor use="encryption">
            <KeyInfo xmlns="http://www.w3.org/2000/09/xmldsig#">
                <X509Data>
EwpDYWxpZm9ybmlhMRQwEgYDVQQHEwtTYW50YSBDbGFyYTEeMBwGA1UEChMVU3VuIE1pY3Jvc3lz
dGVtcyBJbmMuMRowGAYDVQQLExFJZGVudGl0eSBTZXJ2aWNlczEcMBoGA1UEAxMTQ2VydGlmaWNh
dGUgTWFuYWdlcjAeFw0wNzAzMDcyMjAxMTVaFw0xMDEyMDEyMjAxMTVaMDsxFDASBgNVBAoTC2V4
YW1wbGUuY29tMSMwIQYDVQQDExpMb2FkQmFsYW5jZXItMy5leGFtcGxlLmNvbTCBnzANBgkqhkiG
HREEETAPgQ1tYWxsYUBzdW4uY29tMA0GCSqGSIb3DQEBBAUAA0EAEgbmnOz2Rvpj9bludb9lEeVa
OA46zRiyt4BPlbgIaFyG6P7GWSddMi/14EimQjjDbr4ZfvlEdPJmimHExZY3KQ==
            </KeyInfo>
            </EncryptionMethod>
        </KeyDescriptor>
        <ArtifactResolutionService
            index="0"
            isDefault="1"/>
        <SingleLogoutService
            Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect"
        <SingleLogoutService
            Binding="urn:oasis:names:tc:SAML:2.0:bindings:SOAP"
        <ManageNameIDService
            Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect"
            ResponseLocation="https://LoadBalancer-3.example.com:9443/
               amserver/IDPMniRedirect/metaAlias/idp"/>
        <ManageNameIDService
            Binding="urn:oasis:names:tc:SAML:2.0:bindings:SOAP"
            Location="https://LoadBalancer-3.example.com:9443/amserver/
               IDPMniSoap/metaAlias/idp"/>
        <NameIDFormat>
            urn:oasis:names:tc:SAML:2.0:nameid-format:persistent
        </NameIDFormat>
        <NameIDFormat>
            urn:oasis:names:tc:SAML:2.0:nameid-format:transient
        </NameIDFormat>
        <SingleSignOnService
            Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect"
            Location="https://LoadBalancer-3.example.com:9443/amserver/
                SSORedirect/metaAlias/idp"/>
        <SingleSignOnService
            Binding="urn:oasis:names:tc:SAML:2.0:bindings:SOAP"
            Location="https://LoadBalancer-3.example.com:9443/amserver/
                SSOSoap/metaAlias/idp"/>
    </IDPSSODescriptor>
</EntityDescriptor>

SAML 2’s metadata specification’s Chapter 2 offers details on the nature of these metadata.

SSO loyalty module

Next, a connection needs to be established between the Antavo platform and the Keycloak server.
The platform and the Keycloak are connected through the SSO module in the Backoffice. This can be accessed from the Backoffice’s Module page by typing Single Sign-On or SSO into the search field.

The following use case illustrates setting up the SSO provider on a demonstration account. This is configured by the Antavo administrators.

URL
Realm
Client ID: platform
Client secret: this is generated during the Keycloak configuration
Federation field: uid (default)
Scopes: openid profile email

Single sign-on

Configuring single sign-on

SAML 2.0 metadata configuration

SSO loyalty module