--- title: "Single sign-on" slug: "single-sign-on" description: "The user manual provides comprehensive guidance on using the Antavo Management UI for managing loyalty programs." updated: 2024-07-08T18:10:36Z published: 2024-07-08T18:10:36Z canonical: "docs.antavo.com/single-sign-on" --- > ## Documentation Index > Fetch the complete documentation index at: https://docs.antavo.com/llms.txt > Use this file to discover all available pages before exploring further. # Single sign-on ## Establishing connection Antavo’s single sign-on (SSO) solution is implemented through communication between three different servers. Firstly, the connection between the **identity provider (IdP)**and the [**Keycloak**server](https://www.keycloak.org/documentation.html) needs to be established. Your IdP stores user’s login data, and the **SAML** **2**.**0** / OIDC protocol is used to connect this information with the Keycloak server. The following table defines the attributes that are configurable during the integration of SSO. | **Config Name** | **Required** | **Should be filled out by** | **Description** | | --- | --- | --- | --- | | Service Provider Entity ID | ![:check_mark:](https://pf-emoji-service--cdn.us-east-1.prod.public.atl-paas.net/atlassian/check_mark_32.png) | User | 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 | ![:check_mark:](https://pf-emoji-service--cdn.us-east-1.prod.public.atl-paas.net/atlassian/check_mark_32.png) | User | 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 | ![:cross_mark:](https://pf-emoji-service--cdn.us-east-1.prod.public.atl-paas.net/atlassian/cross_mark_32.png) | User | The SAML logout endpoint. If your SAML IdP publishes an IdP entity descriptor, the value of this field is specified there. | | Backchannel Logout | ![:cross_mark:](https://pf-emoji-service--cdn.us-east-1.prod.public.atl-paas.net/atlassian/cross_mark_32.png) | Antavo/User | The SAML logout endpoint. If your SAML IDP publishes an IDP entity descriptor, the value of this field is specified there. | | Backchannel Logout | ![:cross_mark:](https://pf-emoji-service--cdn.us-east-1.prod.public.atl-paas.net/atlassian/cross_mark_32.png) | User | Toggle this switch to **ON** if your SAML IDP supports back channel logout. | | NameID Policy Format | ![:cross_mark:](https://pf-emoji-service--cdn.us-east-1.prod.public.atl-paas.net/atlassian/cross_mark_32.png) | User | The URI reference corresponds to a name identifier format. By default, Keycloak sets it to `urn:oasis:names:tc:SAML:2.0:nameid-format:persistent`. | | Principal Type | ![:cross_mark:](https://pf-emoji-service--cdn.us-east-1.prod.public.atl-paas.net/atlassian/cross_mark_32.png) | User | 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 | ![:cross_mark:](https://pf-emoji-service--cdn.us-east-1.prod.public.atl-paas.net/atlassian/cross_mark_32.png) | User | 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 | ![:cross_mark:](https://pf-emoji-service--cdn.us-east-1.prod.public.atl-paas.net/atlassian/cross_mark_32.png) | User | Allow the external identity provider to create a new identifier to represent the principal. | | HTTP-POST Binding Response | ![:cross_mark:](https://pf-emoji-service--cdn.us-east-1.prod.public.atl-paas.net/atlassian/cross_mark_32.png) | Antavo/User | 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 | ![:cross_mark:](https://pf-emoji-service--cdn.us-east-1.prod.public.atl-paas.net/atlassian/cross_mark_32.png) | Antavo/User | Controls the SAML binding when requesting authentication from an external IDP. When **OFF**, Keycloak uses Redirect Binding. | | Want AuthnRequests Signed | ![:cross_mark:](https://pf-emoji-service--cdn.us-east-1.prod.public.atl-paas.net/atlassian/cross_mark_32.png) | Antavo | When **ON**, Keycloak uses the realm’s keypair to sign requests sent to the external SAML IDP. | | Signature Algorithm | ![:cross_mark:](https://pf-emoji-service--cdn.us-east-1.prod.public.atl-paas.net/atlassian/cross_mark_32.png) | User | If **Want AuthnRequests Signed** is **ON**, the signature algorithm to use. | | SAML Signature Key Name | ![:cross_mark:](https://pf-emoji-service--cdn.us-east-1.prod.public.atl-paas.net/atlassian/cross_mark_32.png) | 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 | ![:cross_mark:](https://pf-emoji-service--cdn.us-east-1.prod.public.atl-paas.net/atlassian/cross_mark_32.png) | Antavo | The user must enter their credentials at the external IDP even when the user is already logged in. | | Validate Signature | ![:cross_mark:](https://pf-emoji-service--cdn.us-east-1.prod.public.atl-paas.net/atlassian/cross_mark_32.png) | Antavo | When **ON**, the realm expects SAML requests and responses from the external IDP to be digitally signed. | | Validating X509 Certificate | ![:cross_mark:](https://pf-emoji-service--cdn.us-east-1.prod.public.atl-paas.net/atlassian/cross_mark_32.png) | Antavo | The public certificate Keycloak uses to validate the signatures of SAML requests and responses from the external IDP. | | Sign Service Provider Metadata | ![:cross_mark:](https://pf-emoji-service--cdn.us-east-1.prod.public.atl-paas.net/atlassian/cross_mark_32.png) | Antavo/User | When **ON**, Keycloak uses the realm’s key pair to sign the [SAML Service Provider Metadata descriptor](https://www.keycloak.org/docs/latest/server_admin/#_identity_broker_saml_sp_descriptor). | | Pass subject | ![:cross_mark:](https://pf-emoji-service--cdn.us-east-1.prod.public.atl-paas.net/atlassian/cross_mark_32.png) | User | 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 | ![:cross_mark:](https://pf-emoji-service--cdn.us-east-1.prod.public.atl-paas.net/atlassian/cross_mark_32.png) | User | 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 | ![:cross_mark:](https://pf-emoji-service--cdn.us-east-1.prod.public.atl-paas.net/atlassian/cross_mark_32.png) | User | A descriptive name for the set of attributes that are advertised in the autogenerated SP metadata document. | ## SAML 2.0 metadata configuration The following XML example represents the metadata for a SAML 2.0 system entity serving as a service provider. This XML file can be exported from the IdP side, and the data contained within need to be transmitted to Antavo to import it to Keycloak’s server. ```xml                                                             MIICZDCCAg6gAwIBAgICBr8wDQYJKoZIhvcNAQEEBQAwgZIxCzAJBgNVBAYTAlVTMRMwEQYDVQQI EwpDYWxpZm9ybmlhMRQwEgYDVQQHEwtTYW50YSBDbGFyYTEeMBwGA1UEChMVU3VuIE1pY3Jvc3lz dGVtcyBJbmMuMRowGAYDVQQLExFJZGVudGl0eSBTZXJ2aWNlczEcMBoGA1UEAxMTQ2VydGlmaWNh dGUgTWFuYWdlcjAeFw0wNzAzMDcyMTUwMDVaFw0xMDEyMDEyMTUwMDVaMDsxFDASBgNVBAoTC2V4 YW1wbGUuY29tMSMwIQYDVQQDExpMb2FkQmFsYW5jZXItMy5leGFtcGxlLmNvbTCBnzANBgkqhkiG 9w0BAQEFAAOBjQAwgYkCgYEAlOhN9HddLMpE3kCjkPSOFpCkDxTNuhMhcgBkYmSEF/iJcQsLX/ga pO+W1SIpwqfsjzR5ZvEdtc/8hGumRHqcX3r6XrU0dESM6MW5AbNNJsBnwIV6xZ5QozB4wL4zREhw zwwYejDVQ/x+8NRESI3ym17tDLEuAKyQBueubgjfic0CAwEAAaNgMF4wEQYJYIZIAYb4QgEBBAQD AgZAMA4GA1UdDwEB/wQEAwIE8DAfBgNVHSMEGDAWgBQ7oCE35Uwn7FsjS01w5e3DA1CrrjAYBgNV HREEETAPgQ1tYWxsYUBzdW4uY29tMA0GCSqGSIb3DQEBBAUAA0EAGhJhep7X2hqWJWQoXFcdU7eQ                                             EwpDYWxpZm9ybmlhMRQwEgYDVQQHEwtTYW50YSBDbGFyYTEeMBwGA1UEChMVU3VuIE1pY3Jvc3lz dGVtcyBJbmMuMRowGAYDVQQLExFJZGVudGl0eSBTZXJ2aWNlczEcMBoGA1UEAxMTQ2VydGlmaWNh dGUgTWFuYWdlcjAeFw0wNzAzMDcyMjAxMTVaFw0xMDEyMDEyMjAxMTVaMDsxFDASBgNVBAoTC2V4 YW1wbGUuY29tMSMwIQYDVQQDExpMb2FkQmFsYW5jZXItMy5leGFtcGxlLmNvbTCBnzANBgkqhkiG HREEETAPgQ1tYWxsYUBzdW4uY29tMA0GCSqGSIb3DQEBBAUAA0EAEgbmnOz2Rvpj9bludb9lEeVa OA46zRiyt4BPlbgIaFyG6P7GWSddMi/14EimQjjDbr4ZfvlEdPJmimHExZY3KQ==                                                                            urn:oasis:names:tc:SAML:2.0:nameid-format:persistent                            urn:oasis:names:tc:SAML:2.0:nameid-format:transient                             ``` [SAML 2’s metadata specification’s Chapter 2](https://www.oasis-open.org/committees/download.php/35391/sstc-saml-metadata-errata-2.0-wd-04-diff.pdf) offers details on the nature of this metadata. # Configuring the SSO module The next step is to establish the connection between the Antavo and the Keycloak server by configuring the **SSO module** in the Management UI. To access the configuration page of the SSO module, navigate to the Modules menu and search for the SSO module in the list. ![](https://cdn.document360.io/08a474ca-8fb4-4c3c-9cd8-665242086cd3/Images/Documentation/loyalty.rc.antavo.com_5161_extensions.png) The page provides an interface to set up the connection with the following fields: - URL - Realm - User ID - User secret (generated during the Keycloak configuration) - Federation field (default value is *uid)* - Scopes 📓 Please contact the [Antavo Service Desk](https://antavo.atlassian.net/servicedesk/customer/portals) before you start configuring the module or want to make changes in the settings. ![](https://cdn.document360.io/08a474ca-8fb4-4c3c-9cd8-665242086cd3/Images/Documentation/loyalty.rc_.antavo.com_2650_extensions_sso-2-1-1024x505.png) # Setting up SSO login for Management UI users The SSO Source and SSO ID of Management UI users have to be added on the [user editor interface](/v1/docs/users#single-sign-on-(sso)) to enable SSO login. Please note that SSO login is enforced for all users by default, allowing them to log in to the Management UI through SSO. You can [turn off this restriction](/v1/docs/users#single-sign-on-(sso)) if needed.