SAP Knowledge Base Article - Public

2317944 - BizX Platform - Partner resources : SAML 2.0 Provisioning guide - Troubleshooting tips and tricks - Common errors and resolution

Symptom

  • SAML 2.0 Provisioning tips when working in the SSO Settings screen.
  • Troubleshooting tips and tricks
  • Common errors and resolution

 "Image/data in this KBA is from SAP internal systems, sample data, or demo systems. Any resemblance to real data is purely coincidental."

Environment

SAP SuccessFactors HCM Suite

Resolution

SAML 2.0 Provisioning tips when working in the SSO Settings screen.

    • What are the different sections in the SSO settings screen in provisioning?
      This section isn't a guide to the SSO setup screen, here we are merely capturing quick tips for common questions.

      • SSO Token:
        For SAML (1.1 and 2.0) this field is used to activate and deactivate the SSO. You can enter any value and use the save token field to activate SSO.
        If you want to deactivate SSO delete the value and press save token.

      • SAML Asserting Parties (or also know as IdP):
        To view the existing asserting parties already configured for this company, use the dropdown menu to navigate to the desired one.
        To create a new asserting party, select "Add an SAML Asserting Party" from the drop down menu, and provide the required information.

        To update any information in this section you need to hit the "update asserting party" button. If you hit the Save button at the top of the screen instead, this will not save the changes.
        This applies to saving changes to the redirection URL as well as the other related sections below such as SP initiated logout, login, etc..
        Note that for SAML SSO to work, the Enable SAML flag value need to be set to "Enabled".

        If your customer wants to have multiple asserting parties setup (aka. multiple IdP systems), this is supported by SuccessFactors.
        However you need to consider the effect it will have on the login process, due to the fact that the redirect URL's are setup independently for each asserting party.

        Please consider the below if you wish to setup multiple asserting parties (two or more):

        • Any login attempt that triggers the use of a redirect URL (for example missing credentials), will trigger an intermediate page called "SSO Redirect landing Page "to appear before the redirect.
          In this page the user has to choose which asserting party (SSO IdP) they belong to. Once they do this, the application can then pick the redirect URL setup for this asserting party and continue the process.
          Initially the names setup in the SSO settings will be displayed, but customer admins can setup translations which make sense to the end user population via admin tools, if required.
          See KBA 2150778 - SSO Redirect Landing Page Error for more details on how to setup asserting party translations

        • There also is an opt-out option which is provided in provisioning > SSO setting page, and it is found at SSO level. This can be useful if all asserting parties have matching redirect URL's.
          The opt-out will only be visible when the company has multiple enabled asserting parties.

          The setting is called Disable Multiple Asserting Party Selection
          If enabled, it will force the user to select a default asserting party. After which, the system will use the selected default asserting party's URLs and no longer ask the end users to select their asserting party.
      •  

      • Redirection URLs:
        These are used to redirect the users to the different customer defined URL's if the end user runs into one of the matching scenarios.
        As stated above these are linked to the asserting parties. We support one set of redirection URL's per asserting party.

        Note: If you are using SP initiated login, the deeplink redirect should be blank.
        As stated above any changes made here need to be saved using the "update asserting party" button

      • SAML v2 : SP-initiated logout, SP-initiated login, etc..
        Use these sections if you want to setup SP initiated, global IdP logout URL's etc..
        Remember these are also specific to the asserting party so again any changes made here need to be saved using the "update asserting party" button

        Note: If you are using SP initiated login, the deeplink and continue session redirect URL's should be blank.
        As stated above any changes made here need to be saved using the "update asserting party" button

      • Common SSO Settings:
        The sections are self explanatory. Please note that if you make changes here, you should use the "SAVE" button at the top of the screen, below the save token button.

    • How to Activate / deactivate SSO?
      Use the SSO token at the top of the SSO Settings screen in provisioning. You can enter any value and use the save token field to activate SSO.
      If you want to deactivate SSO delete the value and press save token.
      See the attached Guide "Activate & deactivate SSO.pdf" for step by step activate and deactivation. 

    • How to Update the SAML verifying certificate?
      If the IdP SAML verification certificate is expiring, or if the certificate being sent is not correct, you may need to amend the values in provisioning.
      1. Make sure the new certificate is in Base64 format
      2. To check, open the certificate in a text editor and verify that you can see "BEGIN CERTIFICATE" and "END CERTIFICATE" tags in it.
      3. Make sure the correct asserting party is selected from the "SAML Asserting Parties" drop down menu.
      4. Make a backup from the existing certificate by copying and pasting currently values from provisioning into a new text file.
      5. Copy and paste the full text from the new certificate into the provisioning settings. 
      6. Click "Update the asserting party" button to save the changes.
      7. If the certificate was saved successfully then you should that the values above the certificate field are showing the valid period and status of the certificate you just updated.

        See the attached guide "Update SAML cert SSO.pdf" for detailed steps with screenshots.

    • How to Update redirection URL's
      You can follow the same logical steps as for updating the certificate.
      1. Make sure that you backup any existing values before you change.
      2. Makes sure you are changing the values for the correct asserting party by using the drop down menu.
      3. After entering changes, use the ""Update the asserting party"" button to save the changes

Troubleshooting tips and tricks

    • Where to find the SSO error log? 
      1. The SSO Error log is located at the bottom of the SSO Settings page.
      2. Click the "SSO Log Viewer" link to access.

        See the attached guide "Find SSO error log.pdf" for detailed steps with screenshots.


    • How to locate the SAML response in the SSO error logs?
      1. In the SSO Log Viewer screen there is a table with different elements. once you have identified an error for which you want to see details, hit the "Toggle SSO error detail..." button to see the full details.
      2. Once you have the details expanded, you can copy and paste the SAMl Response from the "Message:" section (make sure to copy the full line as it is quite long)
      3. After copying the message you can paste it into an XML editor which will help you format and view the message.

        See the attached guide "Find SAML Response.pdf" for detailed steps with screenshots.

    • How to locate the Stack Trace from the SSO error logs?
      1. In the SSO Log Viewer screen there is a table with different elements. once you have identified an error for which you want to see details, hit the "Toggle SSO error detail..." button to see the full details.
      2. Once you have the details expanded, you can view the stack trace from the corresponding section
      3. Typically the important information will be at the bottom of the stack trace after the "caused by:" line.

        See attached guide "Find Stack trace.pdf" for detailed steps with screenshots.

    • How to decode a SAML response if it's not showing as an XML?
      1. At times the SAML Response in the Log Viewer may show as a long string of characters, rather than an XML message. In this case it is probably encoded in Base64.
      2. To decode the message, copy the full line(s) of text, and use a Base64 decoder (or SAML decoder) to decode the message into a readable XML format.
      3. You can do this using Notepad++ as well as some online decoding tools (you can search for SAML decoder in Google and you will find many)

    • What sections are most important in the SAML response?
      These are some areas of the SAML response message that should be checked if you want to ensure the correct information is being sent.
      1. "Destination=": This value should match with the AssertionConsumerService URL which was provided to you by SuccessFactors for this company and Datacenter combination. Make sure the "company=" value matches with the company ID in provisioning.
      2. </ds:X509Certificate>: This is the tag that indicates the beginning of the SAML verifying certificate sent by the IdP. You can use this to verify if the certificates match between the IdP and what is setup in provisioning.
      3. <Issuer> : This is the tag indicating what the issuer value sent by the IdP is. This needs to match the value in provisioning
      4. <Audience>: this is the Audience or Entity ID sent by the IdP. It needs to match the values for the datacenter the company is located in. If you do not know the correct values to use you can check with support.
      5. <NameID>: this is the value of the username being sent by the IdP for that login attempt.



Common errors and resolution

NOTE: Customers now have the capability to access SSO Error Logs via Admin Center. The feature is called 'Login Failures Error Log'. Please see the following KBA:

2757960 - Login Failures Error Log - SSO - BizX Platform

Please use this feature in conjunction with the following SSO error information / resolutions if you encounter any issues.

    •  [companyId:XXXX][issuer:XXXX] [local user authentication fail for user abcdef]
      There is something wrong with user abcdef, either on the id sent from SSO or on the BizX.

      • Is the username being sent from the IDP valid? Is the spelling and case matching the one on BizX?
        • The username being sent from the IDP must be valid, correct spelling and adhere to case sensitivity so that it matches exactly what is set in the Username column in User Data File in SuccessFactors. Example: In the above error, the username being sent from the IDP is abcdef. If the username for this user in SuccesFactors is set to ABCDEF the login will fail
      • Is this user an active user? Active / Inactive?
        • For a users to login to SF they must be Active in the instance.  
      • Is the user locked?
        • See KBA 2086751 for details on how to unlock a user.
      • Does the user have a valid Manager?
        • Check to make sure their manager’s ID is valid. A user cannot login if they do not have a valid manager.
        • Export your user file from Admin Center -> Employee Export and check the MANAGER field for the user. It must contain a valid Manager ID (check for spelling mistakes or incorrect numbers) or NO_MANAGER.
      • For non-RBP enabled instances, is the user in the default user group? 
        • Users must be in the default group.
      • For RBP enabled instances does the user have login permission?
        • To be able to login, the user needs to have "User Login" permission as referred on this KBA 2410089.
      • If Partial Org. SSO is on, is the user set to use SSO or blank loginmethod?
        • If they are set to loginmethod PWD they cannot login using SSO.
      • Is there an IP restriction set in IP Restriction Management and is the user connecting from a valid IP address?
        • See KBA 2089414 on how this can be set.
      • Is the SAML User Column empty?
        • SPLUNK error: java.lang.Exception: Username for company id TESTComp custom column 'AbCdEfG' and custom username abcdef is not found
          Fix:
          In Provisioning > Single Sign-On (SSO) Settings, "SAML User Column" field should be left blank.
    •  [issuer:http://testcompany/adfs/services/trust] [company Id TESTComp not match request parameter company Testcompany.]
      The Company ID in the login (TESTComp) is not the same as the instance name (Testcompany).
      We identify where the logins are going based on the Issuer value (http://testcompany/adfs/services/trust) . In this case it means that the issuer in the SAML Response message has been setup in provisioning for company ID TESTComp, but the target URL in the SAML Response is targeting the company ID Testcompany. Verify that the SAML Response message has the correct issuer matching the target company.

    •  [companyId:XXXXXX][issuer: http://testcompany/adfs/services/trust] [decrypt assertion fail.]
      The Assertion information is being encrypted with the wrong certificate.
      Only the SF provided encryption cert should be used. Typically, that cert is named SFAdmin.txt, and can be provided by support.

    •  [companyId:XXXXXX][issuer:ABC-SAML2-Entity][validate response fail.]
      Look at the bottom of the stack trace.
      If it says “The response is not signed correctly” Either the Response is not signed or it is signed with the wrong certificate. Open the SAML Response from the error log in an XML editor.
      Look for two tags/sections.
      One for Signature and the other for Assertion. If you find the Signature outside the Assertion section, then the Identity Provider (customer’s SSO system) is trying to sign the Response.
      If you find the Signature inside the Assertion, the Identity Provider (customer’s SSO system) is trying to sign the Assertion and not the Response.

      The fixes are:
      If signing the Assertion, change our setting from Response Signature (YES) to Require Assertion Signature(YES).

      If they are signing the Response and we have this failure, we have the wrong certificate. Ask the customer for a copy of the correct certificate.
      It may also be in the Response info in the error log.
      Look for the </ds:X509Certificate> tags. If you find them, use the certificate info to correct the one in provisioning.
      Note: The one you find will not contain begin and end tags. Paste the new one between the existing tags in provisioning. Make a backup of the existing one before you amend it.

    •  [validate assertion fail.]
      Look at the bottom of the stack trace.
      If it says “The assertion is not signed correctly” Either the Assertion is not signed or it is signed with the wrong certificate. Open the SAML Response from the error log in an XML editor. Look for two tags/sections.
      One for Signature and the other for Assertion. If you find the Signature outside the Assertion section, then the Identity Provider (customer’s SSO system) is trying to sign the Response.
      If you find the Signature inside the Assertion, the Identity Provider (customer’s SSO system) is trying to sign the Assertion and not the Response.

      The fixes are:
      If signing the Assertion, change our setting from Response Signature (YES) to Require Assertion Signature(YES).

      If they are signing the Response and we have this failure, we have the wrong certificate. Ask the customer for a copy of the correct certificate.
      It may also be in the Response info in the error log.
      Look for the </ds:X509Certificate> tags. If you find them, use the certificate info to correct the one in provisioning.
      Note: The one you find will not contain begin and end tags. Paste the new one between the existing tags in provisioning. Make a backup of the existing one before you amend it.

      If it says “Condition NotOnOrAfter is after now: 2012-11-28T19:39:19.000Z
       “ then we received the login after it was expired. The customer controls how long each login is good for with the NotOnOrAfter time. We compare it to the current time and stop the login if it’s too old. This error indicates either a latency issue (slow speed getting us the login late) or a clock sync issue. It’s usually the customers clocks. Have them verify the time on their servers. You can also ask support to have the clocks verified on the SF application servers. BizX has 2 minutes buffer or tolerance, so if the time difference between the systems is longer than this, the login attempt will fail.

    • [issuer:COMPTest] [No related companyId found.]

      This one is saying that there is no company instance with SAML Issuer COMPTest.
      It pulled the COMPtest issuer name right from the customers login attempt (SAMLResponse).
      Just change our SAML issuer to the value the customer’s IdP is sending.
      You may want to confirm with the customer before doing it. Tell them what SAML Issuer is in provisioning and what Issuer they are sending. Ask them if they prefer to switch it on their side.

    •  [null]
      This one is a little cryptic, as there is typically no SAML response provided in the SSO error log. In this scenario the reason is usually that the HTTP request was sent using GET method and not POST by the IdP. A telltale sign is when you see “UnsupportedOperationException” and “handleGet” in the stack trace:

      Example:
      java.lang.UnsupportedOperationException
       at com.successfactors.authentication.service.saml2.SFSAML2AssertionConsumerHandler.handleGet(SFSAML2AssertionConsumerHandler.java:121)
      […]

      SF only accepts POST method. Typically this is changed on the IdP side of the setup, and SF support does not have the expertise for configuring IdP’s. Work with your experts or the customer’s IT teams to fix the setup. Google is also a great source of information for many IdP’s

    • [The assertion must contain the service provider www.successfactors.com or the company-wide service provider www.successfactors.com/XXXXXXX within the Audience list: [http://www.successfactors.com] or [The assertion must contain the service provider www.successfactors.eu or the company-wide service provider www.successfactors.eu/XXXXXXX within the Audience list: [http://www.successfactors.eu] (for DC2 data Center)

      The customer's IdP (identity provider) is sending the www.successfactors.com/XXXXXXX or www.successfactors.eu/XXXXXXX entity ID (Audience) in the SAML response but it's not being accepted on our side (Successfactors)

      Resolution
      The customer should amend the Entity ID to be only www.successfactors.com or www.successfactors.com/XXXXXXX on the IdP side (remove http://) and
      The customer should amend the Entity ID to be only www.successfactors.eu or www.successfactors.eu/XXXXXXX on the IdP side (remove http://) for DC2 data Center

  •            This will resolve the issue. Also see KBA 2233329

    •  [Didn't get an assertion in ArtifactResponse]

      This is common in SP-Initiated scenarios where the IdP was not able to process the Authn Request sent by the SP.
      The SAML Response received from the IdP side is not containing the section called assertion.
      You can check it by copying the long text string available in the SSO error log in provisioning (Starts & looks like this" PHNhbWxwOlJlc3BvbnNlIElEPSJfN2VjOTMyMTgtNmE5OS......" ), and decoding it:
      Use a BASE64 decoder tool to convert the BASE64 encoded string into a SAML message.
      You can use tools like Notepad++ (Plugins menu > MIME Tools > BASE64 Decode) or online tools like http://www.john-james-andersen.com/blog/programming/great-saml-decodeencode-tool.html
      Once you have decoded the message you can copy and paste it in an XML editor and you will see that there is no <assertion> section which is a required section.
      At the end of the SAML message, you will see a reason for the empty assertion response.
      For example it could read InvalidNameIdPolicy which would indicate a change in the Name ID policy is required i.e. change from persistent to unspecified.

      You can also check if the signature is configured correctly on customer side (see KBA 2408674).

      Since the error is originating from the IdP the common troubleshooting process is to ask the administrator of the IdP system to analyze and provide the reason for the failure.

    •  [issuer:http://adfsfederation.com] [No related IdP Metadata found.]
      This means that there is no company setup with the related issuer in provisioning.
      Check if the issuer value from the SAML message is setup correctly in Provisioning. If not you need to make sure they match. You can update the existing one, create a new asserting party with the new issuer, or ask the customer to change the issuer they are sending from the IdP side.

      In some cases the value is already in provisioning but you still see this message. We have seen this occur occasionally after refresh activities or migration to the early test release.
      If this is the case then you can re-trigger the save to the database. Simply make a small change to the issuer value in provisioning, save your changes, then revert the change and save again. (Remember to use Update asserting party to save or else the changes will not stick)

    •  [token not set in provisioning]
      This means that the SSO is not active in provisioning. Make sure to set a token value at the top of the SSO settings page. Then save in order to activate Single Sign On.

    • Certificate valid time not valid
      This means that the certificate in the SSO settings has probably expired AND the "SAML Verifying Certificate Valid Period" setting is set to YES.
      To fix this issue you need to update the certificate with a new valid certificate.
      If you don't have a new certificate yet, as a workaround, you can also change the value for the "SAML Verifying Certificate Valid Period" to NO until you have it.
    •  [Decrypt assertion fail]
      The Idp is encrypting the Assertion with a certificate that is not ours. If an Identity Provider chooses to encrypt the Assertion, they must do so with the certificate supplied by SuccessFactors. This is the SFAdmin certificate and it's the same certificate we supply for all customers.

    • [Format null unknown]
      This error is coming from the customer's identity provider settings. They have selected an invalid name ID policy. Here is an example of a name ID with no policy specified which will cause the error: <NameID>185737</NameID>
      Here is an example of a name ID with the correct policy: <saml2:NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified">testuser</saml2:NameID>
      This setting is controlled by the identity provider side and cannot be changed by SuccessFactors.
    • Validate assertion fail. now [<timestamp on SF at moment of the error>] is before Condition NotBefore [<timestamp sent by SSO on SAML request>]
      This error is due to the time on BizX and on the SSO being more than 2 minutes with difference as SuccessFactors has a buffer that allows up to 2 minutes difference.
      To solve this issue, please change your server time (SSO) to less than 2 minutes from SuccessFactors, which our servers are synchronized with the following servers:

      clock.via.net prefer
      t2.timegps.net

    • [is not enable]

kba fix error.jpg

    This error is caused by a wrong setting in SSO Provisioning settings. The Enable SAML Flag is set to 'Disabled'. It must be set to 'Enabled'.

kba fix cause.jpg

    • Errors from the Idp (provided by Idp provider): 
      -
      SSOv2 IdP configuration /Common/idp-prd-xxxxxx-xx does not contain SP connector with Issuer: https://www.successfactors.com/companyID
      - SSOv2 Error: No SP Connector attached to SAML SSO from assigned SAML resources matching authentication request. If ACS URL is present in authentication request it should match ACS URL from SP Connector. If Issuer is present in authentication request it should match entity_id from SP connector.
      - SSOv2 Error(16) Unable to find SAML SSO/SP Connector object matching SAML Authn Request

      This means that we are sending the entityID as https://www.successfactors.com/companyID , while the Idp has it configured as https://www.successfactors.com

      The reason is that in provisioning "Send request as Company-Wide issuer " is set to YES, which means that we will send the companyID in the entityID as: https://www.successfactors.com/companyID

      To resolve this, either disable the option in provisioning or have the Idp update the EntiryID on their side to include the companyID

      company-wide_issuer.png
    • The client IP  does not fall into IP Address range. Please consult with Administrator 
      --
        If you receive the below error in the SAML log which means that the respective IP address is not fall into the range that you restricted in the instance. 

      SSO erorr.PNG
      --
      When this kind of error occurs, please follow the below steps:-
          1. Go to provisioning --> company settings --> Search for Restrict access to IP range: Add the IP address range in the highlighted box shown in the below screenshot. 

              SSO erorr2.PNG

 

See Also

2757960 - Login Failures Error Log - SSO - BizX Platform

Keywords

SSO, SAML, Error Logs, Hints, Tips, Troubleshoot, How to, Response, Error, company-wide, issuer, ACS , KBA , LOD-SF-PLT-SEL , SSO Errors & Logs , LOD-SF-PLT-SAM , SAML SSO First Time Setup , How To

Product

SAP SuccessFactors HCM Suite all versions

Attachments

Activate & deactivate SSO.pdf
Update SAML cert SSO.pdf
Find SSO error log.pdf
Find Stack trace.pdf
Find SAML Response.pdf