Single Sign-On Authentication using SAML 2.0

Identity Portal supports the
Security Assertion Markup Language (SAML)
federation protocol for single sign-on.
142
Most enterprises are embracing Security Assertion Markup Language (SAML 2.0) standard for secure single sign-on access to applications in their environment as it offers a range of benefits such as,
  • Improved user experience
  • Increased security
  • Reduced costs
  • Supports seamless interoperability between systems, independent of implementations
In our endeavour to help customers adopt SAML for fast, simple, and secure access to applications in their environment, we have enabled Identity Portal to be SAML 2.0 compliant. Enterprise users can now seamlessly access the Identity Portal application with SAML based secure single sign-on authentication.
SAML is an XML based federation protocol for exchanging authentication and authorization data between security domains. It uses security tokens containing assertions to pass end-user information between a SAML authority (Identity Provider) and a SAML consumer (Service Provider).
To facilitate SAML authentication with Identity Portal as the Service Provider and any SAML compliant Identity Provider of your choice, you must configure the following SAML settings in your environment in the given order:
Upload a Certificate to Identity Portal
Upload a certificate to Identity Portal for signing SAML request and decrypting the SAML response from Identity Provider.
When users access the Identity Portal URL, Identity Portal generates and signs the SAML authentication request with a private key. When Identity Provider receives the SAML request, it validates the digital signature with the public key of the Identity Portal certificate that is uploaded to the Identity Provider. Identity Provider encrypts SAML response with the public key from the certificate selected for encrypting SAML response and forwards to the Identity Portal. Identity Portal decrypts the SAML response with the corresponding private key.
Follow these steps:
  1. In the Identity Portal Admin UI, navigate to
    ELEMENTS,
    SECURITY,
    Keys and Certificates.
  2. Click
    CREATE.
  3. In the
    Create Key and Certificate
    screen, enter a value for Keystore Name, Keystore Password and PrivateKey Password.
    The supported keystore formats are JKS and PKCS12. Each keystore file is expected to have only one pair of public certificate and private key represented by an alias.
    The recommendation is to use the Certificate Authority
    (CA) signed certificate and keys.
  4. Click
    Import KeyStore
    to select a keystore file. Once selected, the certificate persists in the system.
  5. Click on the certificate to view its details.
Configure Identity Portal for SAML Authentication
For Identity Portal to serve as a Service Provider for SAML single sign-on authentication, the following configuration must be carried out in the Identity Portal Admin UI.
You cannot enable both SAML and Second Factor authentication at the same time. To disable Second Factor authentication, follow the given steps:
  1. In the Identity Portal Admin UI, navigate to
    SETUP,
    General Configuration,
    Second Factor.
  2. Uncheck the following parameters:
    • Require Second Factor On Login
    • Second Factor Enabled
If there is a need, the Second Factor authentication can be configured on the Identity Provider side.
  1. Prerequisites
  2. Navigate to
    SETUP,
    General Configuration,
    Single Sign On.
  3. Complete the following configuration:
    1. Import IDP Metadata:
      To establish a baseline of trust and interoperability between the Identity Provider and Identity Portal for SAML flow, you must download metadata from Identity Provider and import the same into Identity Portal. The Identity Provider metadata XML file contains information such as Identity Provider certificate, entity ID, redirect URL, logout URL and so on.
      Follow your Identity Provider's SAML documentation for instructions to download the metadata.
      Import Identity Provider's metadata into Identity Portal by clicking
      Import IDP Metadata.
      The import action parses the metadata file and populates the Identity Provider certificate and login URL details in the following fields:
      • IDP Certificate Details
      • IDP Login URL - HTTP Post Binding
      • IDP Login URL - HTTP Redirect Binding
    2. Auth Type:
      Select the authentication type as
      SAML
      from the
      Auth Type
      drop-down.
    3. Identity Location:
      Identity Provider passes SAML attributes in the SAML assertion to provide information about a user that is getting authenticated. Generally, Identity Providers use
      NameID
      as the username to identity a user in SAML assertions.
      Example:
      <samlp:Response> ... <saml:Assertion> <saml:Subject> <saml:NameID>test_user</saml:NameID> ...
      For some Identity Providers, the username can be contained in the Attributes element of the SAML assertion instead of NameID. In such a case, change the Identity Location to the attribute name defined in the SAML assertion.
      Example:
      <samlp:Response> <saml:Assertion> ... <saml:AttributeStatement> <saml:Attribute Name="username"> <saml:AttributeValue>test_user</saml:AttributeValue> </saml:Attribute> ...
    4. IDP Reset Password Link:
      This parameter allows you to reset user password for Identity Provider or Identity Portal application.
      • To reset the Identity Provider user password, enter a reset password link in this field. When a user initiates reset password from the
        Settings
        page of the Identity Portal User Console, the reset password link that you enter in this field is displayed on the screen. The user can navigate to this link and reset password.
      • To reset the Identity Manager user password, leave this field blank. When a user initiates reset password from the
        Settings
        page of the Identity Portal User Console, the user is prompted to reset password by providing the current and new password on the screen.
    5. IP Proxy Base URL:
      Represents the address of the proxy configured for Identity Portal in a cluster setup. The part of the Identity Portal URL before /sigma/app is the Proxy Base URL. Example: https://<hostname>.<domain_name>
      If a Proxy is not configured for Identity Portal, enter the Identity Portal User Console URL until its port number.
      Example: https://<hostname>.<domain_name>:<port_number>
      If you leave this field blank, SAML authentication fails.
    6. Request Decryption Key:
      Select the private key to decrypt SAML assertions. In case, certificates are not uploaded to Identity Portal, follow section Upload a Certificate to Identity Portal. If the SAML response is not encrypted, select the
      Disabled
      option.
    7. Request Signing Algorithm:
      Select the algorithm for signing the SAML authentication request. Identity Portal supports RSA-SHA1 and RSA-SHA256.
    8. Request Signing Key:
      Select the private key to sign the SAML request. In case, certificates are not uploaded to Identity Portal, follow section Upload a Certificate to Identity Portal. If the SAML request does not require a signature, select the
      Disabled
      option.
    9. SAML Break Glass URL:
      When SAML federation breaks, system administrators can bypass SAML authentication and directly log in to the Identity Portal application. Administrators must provide their local login password to log in to the application. This URL is auto-generated by the application after saving the single sign-on SAML configurations and cannot be changed. In case of a proxy, the URL is auto-generated based on the proxy base URL.
      The format of the BreakGlass URL is https://<hostname>:<portnumber>/sigma/app?breakGlass=true
    10. Service Provider Initiated Request Binding:
      Defines the binding (HTTP-POST, HTTP-Redirect) that Identity Portal uses to send SAML authentication request to the Identity Provider. Depending on the binding option that you select, the Identity Provider Login URL is selected as defined in the following fields:
      • IDP Login URL - HTTP Redirect Binding
      • IDP Login URL - HTTP Post Binding
    11. User Attribute Mapping Disambiguate User:
      This field lists the Identity Portal user attributes. Select the attribute that you need to map to the SAML subject extracted from the SAML assertion. The UserId attribute is generally used to disambiguate the user in the user store.
      The attribute that you select must be unique in the user store.
  4. Click
    Save.
  5. Export SP Metadata:
    Identity Portal publishes a metadata file that an Identity Provider can import to fetch Identity Portal related metadata (ACS URL, signing and encryption certificates, entity ID) for SAML flow. To export Identity Portal metadata file, click
    Export SP Metadata.
    • The URLs in the metadata file depend on the Identity Portal Proxy Base URL.
    • Download the metadata file
      after saving
      the Identity Portal single sign-on SAML configurations.
Configure Identity Provider for SAML Authentication
Your organization’s Identity Provider must be SAML compliant to authenticate and authorize single sign-on access to Identity Portal. To accomplish this, you must define Identity Portal as a SAML enabled connected app in Identity Provider.
If Identity Provider supports import functionality, you can upload the Identity Portal metadata. Else, you need to manually configure Identity Portal details in the Service Provider app section of the Identity Provider.
For example, if you are using Salesforce as the Identity Provider, you must configure the following settings in Salesforce to define Identity Portal as a SAML enabled connected app.
  • Enable SAML:
    Select this option to enable SAML for your Identity Provider.
  • Entity ID:
    A unique URL identifier for Identity Portal. Salesforce identifies Identity Portal with this identifier.
  • ACS URL:
    Specifies the Identity Portal application URL. Salesforce redirects SAML authentication response to this URL.
  • Enable Single Logout:
    Identity Portal does
    not
    support single logout service. This means that when a user logs out of the Identity Portal application, the Identity Provider user session is still active. The user can still access the other service providers (applications) in the system.
  • Subject Type:
    Specifies the field that defines the user’s identity for the app. Options include the user's Username, Federation ID, User ID, Custom Attribute, and Persistent ID.
  • Name ID Format:
    Specifies the user format attribute sent in SAML messages. You can set this parameter to any attribute (email address, persistent, or transient) that is uniquely identified in the User Store.
  • Issuer:
    A unique URL identifier for Salesforce. Identity Portal identifies Salesforce with this identifier.
  • Idp Certificate:
    Represents the self-signed or CA signed certificate generated by Salesforce.
  • Optional
    • Start URL:
      Directs users to a specific location after they are authenticated. Enter the Identity Portal's start URL.
    • Verify Request Signatures:
      Select the security certificate that Identity Portal shared with Salesforce. Use this option only when Identity Portal signs the SAML authentication request.
    • Encrypt SAML Response:
      Select Encrypt SAML Response to upload a certificate and select an encryption method for encrypting the assertion.
Access Identity Portal User Console
In a web browser, type in the Identity Portal User Console URL. You will be redirected to the Identity Provider's login page. After the successful SAML authentication, user is redirected to the Home (default module) page of the Identity Portal User Console.
If the user session is already active in the Identity Provider, the user will gain access to the Identity Portal User Console with single sign-on access.
Troubleshooting
Symptom:
When you enter the Identity Portal user console URL in a browser, either the Identity Provider login page does not appear or the login page appears but fails after the credentials are provided.
Solution:
  • If user login fails with "Unauthorized User Access" or "Internal Error", recheck the Identity Provider and Identity Portal SAML configurations. You can also check the logs for information about the error.
  • Users requesting access to Identity Portal must exist in both Identity Provider and Identity Manager user store. Else, the user is considered as an unauthorized user and the Identity Provider throws "Unauthorized Access" error.
  • If Identity Manager is SAML enabled, ensure that even Identity Portal is SAML enabled.