SSO Frequently Asked Questions and Troubleshooting Guide

SSO Configuration and Administration

• To use codeBeamer with your SSO system, both codeBeamer and your SSO system must be configured.
• Configuring your SSO system requires understanding your SSO system and also administration rights to configure that.

What version of SAML is supported?

Your IDP provider must support SAML 2.0 protocol.

What version of ADFS is supported?

ADFS 2.0 or higher is supported.

Is Azure AD supported by codeBeamer?

Azure AD is using and supports SAML 2.0, so this should work and is supported. However, we have not tested this with Azure AD yet.

How can I check / where can I find the SP metadata from codeBeamer?

Open https://yourcodebeamer.domain.com/cb/saml/sp/metadata and you should be able to successfully download the XML file.

Please note: depending on your installation and configuration, the codeBeamer base URL can be different, so please try both URLs:

<your_codebeamer>/cb/saml/sp/metadata
or
<your_codebeamer_base_url>/saml/sp/metadata

If you cannot download the XML file then make sure the Identity Provider Configuration is filled out properly in the 'SAML Configuration' page. Check the XML provided by your IDP and make sure it was inserted properly.
Restart your codeBeamer instance and try again.

What is the minimum configuration in order to get SSO working?

Go to the 'System Administration' - 'SAML Configuration' page and fill out all required fields

You will need:

1. General Configuration
   1.1 Enable SAML configuration
   1.2 Enter your domain name
   1.3 Fill out user mapping
2. Identity Provider configuration
   2.1 EntityID can be found in the IDP XML file in the 'entityID' attribute. e.g.
   

   <EntityDescriptor xmlns="urn:oasis:names:tc:SAML:2.0:metadata" ID="_c13d8658-35d4-4846-844d-f75a2d411228" entityID="http://fs.codebeamer.com/adfs/services/trust">
   <ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#">

   2.2 URL - In case your IDP XML is available via a URL, you can use this field instead of copy&pasting XML content
   2.3 XML - If your IDP XML is not available via URL or you manually need to change something in it
3. Service Provider Configuration
   3.1 EntityID can be any identifier, we recommend to use only alphanumeric characters
   3.2 Check tick-boxes based on your IDP configuration
   3.3 Generate and enter active and standby private keys and certificates (self signed certificates work here as well)

How to configure user mappings? How to use claimType URI from IDP metadata file?

You need to make the attribute on our side with claims on your side.

User account matching is done via the first non-empty value of the following Assertion attribute:

• ssoId
• name
• email

Please refer to this WIKI page for more detail.

Can we use the following for user mapping?

{
"ssoId":"emailaddress",
"name":"name",
"email":"emailaddress"
}

It depends on your IDP configuration. In our test IDP server we have the following claimType

<auth:ClaimType xmlns:auth="http://docs.oasis-open.org/wsfed/authorization/200706" Optional="true" Uri="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/privatepersonalidentifier">
  <auth:DisplayName>PPID</auth:DisplayName>
  <auth:Description>The private identifier of the user</auth:Description>
</auth:ClaimType>
<auth:ClaimType xmlns:auth="http://docs.oasis-open.org/wsfed/authorization/200706" Optional="true" Uri="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname">
  <auth:DisplayName>Given Name</auth:DisplayName>
  <auth:Description>The given name of the user</auth:Description>
</auth:ClaimType>
<auth:ClaimType xmlns:auth="http://docs.oasis-open.org/wsfed/authorization/200706" Optional="true" Uri="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name">
  <auth:DisplayName>Name</auth:DisplayName>
  <auth:Description>The unique name of the user</auth:Description>
</auth:ClaimType>

The configuration for this would be:

{
"ssoId":"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/privatepersonalidentifier",
"name":"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name",
"email":"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress"
}

I filled out the 'SAML Configuration' page correctly but the authentication is still not working.

Please restart codeBeamer service after you saved and finished 'SAML Configuration'. Furthermore, every time you change something in the SAML configuration, you need to restart the codeBeamer service.

What is the purpose of a standby certificate?

In case the Primary Certificate expires, the Secondary Certification will be used. Otherwise the IDP might not accept the authentication request due to an expired certification.

Please make sure the Secondary Certificate expiration date is longer than the Primary Certificate and not covering the same time period. So, for example, if your Primary Certificate is valid from 2020 January until 2021 December, we would advise to create the Secondary Certificate covering the 2021 November - 2022 November period.

Can I use self-signed certificates?

Yes, as these certificates are used only for encrypting the communication, so a self signed certificate will work, it does not need to be a CA certificate.

How can I troubleshoot and trace the request and response from Codebeamer to IDP?

All communication happens in the browser, you can use the Developer Tools in Google Chrome and record all request / response between codeBeamer and your IDP.
These are usually 'based64' messages; you can use the following website https://www.samltool.com/decode.php to decode them.

I got an NullPointerException error

2020-09-16 10:57.26,787 ERROR [localhost].[/].[default] - Servlet.service() for servlet [default] in context with path [] threw exception [Thread-6] [17] {Req#=-, Sess#=-, serverId=server}
java.lang.NullPointerException: null
at com.intland.codebeamer.saml.config.SamlAuthenticationRequestEnhancer.enhance(SamlAuthenticationRequestEnhancer.java:25) [cb.jar:?]
at com.intland.codebeamer.saml.config.SamlAuthenticationRequestEnhancer.enhance(SamlAuthenticationRequestEnhancer.java:20) [cb.jar:?]
at org.springframework.security.saml.provider.service.HostedServiceProviderService.authenticationRequest(HostedServiceProviderService.java:181) [spring-security-saml2-core.jar:2.0.0.M31]

Please check your IDP metadata xml and check that a "NameIDFormat" node it present. If not please add this node to the xml.

It could be added after SingleLogoutService node. e.g.

<SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" Location="https://login.com/test/saml2"/>
<NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress</NameIDFormat>

I got an error page when I tried to log in

Please check your log file, in case the error happened after the authentication on the IDP side and the response of the IDP is logged.

The log should contain the following log entry with a "SAMLResponse". e.g.:

com.intland.codebeamer.saml.controller.SamlSigninController.samlLogin(javax.servlet.http.HttpServletRequest,javax.servlet.http.HttpServletResponse),parameters={method 'samlLogin' parameter 0,method 'samlLogin' parameter 1},responseStatus=,responseStatusReason=,resolvedFromHandlerMethod=,interfaceParameterAnnotations=[],description=com.intland.codebeamer.saml.controller.SamlSigninController#samlLogin(HttpServletRequest, HttpServletResponse)], org.springframework.web.servlet.HandlerMapping.bestMatchingPattern=/saml/sp/SSO/**, org.springframework.web.servlet.HandlerMapping.matrixVariables={} // LinkedHashMap[accessOrder=false,threshold=0,loadFactor=0.75], org.springframework.web.servlet.HandlerMapping.pathWithinHandlerMapping=/saml/sp/SSO/alias/SAML2.spr, org.springframework.web.servlet.HandlerMapping.uriTemplateVariables={} // LinkedHashMap[accessOrder=false,threshold=0,loadFactor=0.75], org.springframework.web.servlet.resource.ResourceUrlProvider=org.springframework.web.servlet.resource.ResourceUrlProvider@dfa59b // ResourceUrlProvider[logger=org.apache.commons.logging.impl.SLF4JLocationAwareLog@25aba6c3,urlPathHelper=org.springframework.web.util.UrlPathHelper@4cb50fff,pathMatcher=org.springframework.util.AntPathMatcher@4c3ddff4,handlerMap={},autodetect=true], requestId=68, userGeoLocation=false}
requestParameters={RelayState={"1ec5fb7b-c5c9-4fac-995f-07a6f50edc4b"}, SAMLResponse={"<< SAMLResponse >>"}}
user=null
throwable=com.intland.codebeamer.persistence.util.exception.CodebeamerRuntimeException: org.springframework.security.authentication.InsufficientAuthenticationException: Validation Errors:
1. An error response was returned: urn:oasis:names:tc:SAML:2.0:status:Responder

Copy the content of SAMLResponse and decode it on the https://www.samltool.com/decode.php page. You should get an XML

<samlp:Response Consent="urn:oasis:names:tc:SAML:2.0:consent:unspecified" Destination="https://example.com/cb/saml/sp/SSO/alias/SAML2.spr" ID="_2c55b43a-0e7b-467b-a98e-139f08430a4c" InResponseTo="ARQa7eee9a-300d-4200-9bca-07e126b15402" IssueInstant="2020-05-04T16:37:29.208Z" Version="2.0" xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol">
    <Issuer xmlns="urn:oasis:names:tc:SAML:2.0:assertion">http://server.example.com/adfs/services/trust</Issuer>
    <ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
        <ds:SignedInfo>
            <ds:CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>
            <ds:SignatureMethod Algorithm="http://www.w3.org/2001/04/xmldsig-more#rsa-sha256"/>
            <ds:Reference URI="#_2c55b43a-0e7b-467b-a98e-139f08430a4c">
                <ds:Transforms>
                    <ds:Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature"/>
                    <ds:Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>
                </ds:Transforms>
                <ds:DigestMethod Algorithm="http://www.w3.org/2001/04/xmlenc#sha256"/>
                <ds:DigestValue>Fbcu+lHislndMwd2wjLKdGlU645/BE2KPWDMECgZoCQ=</ds:DigestValue>
            </ds:Reference>
        </ds:SignedInfo>
        <ds:SignatureValue><<SignatureValue>></ds:SignatureValue>
        <KeyInfo xmlns="http://www.w3.org/2000/09/xmldsig#">
            <ds:X509Data><<X509Data>></ds:X509Certificate>
            </ds:X509Data>
        </KeyInfo>
    </ds:Signature>
    <samlp:Status>
        <samlp:StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:Responder">
            <samlp:StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:__RequestDenied__"/>
        </samlp:StatusCode>
    </samlp:Status>
</samlp:Response>

Please check the "samlp:Status" in the XML. In the given example above the authentication request was denied by the IDP

I got an "InvalidNameIDPolicy" error

codeBeamer logs contains an XML with the following response

<samlp:StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:Requester">
   <samlp:StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:InvalidNameIDPolicy" />
</samlp:StatusCode>

Please check claim mapping on your IDP. See: SAML

How to capture Google Chrome HAR log

1. Launch Chrome

2. Press F12, or open the Developer tools and go to the "Network" tab, check the option 'Preserve Log'

3. Login to Codebeamer

4. Reproduce the issue

5. Right click on any place in the console content, and choose "Save all as HAR with content"