Securing Introscope Using SAML 2.0

SAML 2.0 is an SSO authentication protocol providing a centralized point for user authentication. Use SAML 2.0 to navigate between web applications with only one login required. WebView, Web Start Workstation, and Command Center act as SAML 2.0 service providers. WebView, Web Start Workstation, and Command Center can connect to the identity provider (IdP) for authentication.
apmdevops106
SAML 2.0 is an SSO authentication protocol providing a centralized point for user authentication. Use SAML 2.0 to navigate between web applications with only one login required. WebView, Web Start Workstation, and Command Center act as SAML 2.0 service providers. WebView, Web Start Workstation, and Command Center can connect to the identity provider (IdP) for authentication.
Configure Introscope to use either an internal or external IdP. Use an external IdP so that Introscope can use the existing company IdP for user authentication. Alternatively, the Enterprise Manager includes an internal IdP that you can enable for user authentication.
Configuring SAML Authentication with an Internal IdP
Set up Introscope with an internal IdP.
Follow these steps
:
  1. Go to the
    <EM_Home>/config
    directory.
  2. Open the
    IntroscopeEnterpriseManager.properties
    file in a text editor.
  3. Enable SAML authentication for WebView, Web Start Workstation, and Command Center:
    introscope.saml.enable=true
  4. Enable the internal provider to be started during Enterprise Manager start:
    introscope.saml.internalIdp.enable=true
  5. Restart Enterprise Manager.
  • Do not change other SAML configuration options. If you change them, CA APM cannot communicate with the internal IdP.
  • The internal provider is configured to use
    realms.xml
    in the
    <EM_Home>/config
    directory for getting user information. Configure
    realms.xml
    to use Local, LDAP, or EEM authentication.
Configuring SAML Authentication with an External IdP
Set up Introscope with an external IdP.
Follow these steps:
  1. Open the
    <EM_Home>/config/
    IntroscopeEnterpriseManager.properties
    file in a text editor.
  2. Enable SAML authentication for WebView, and Web Start Workstation:
    introscope.saml.enable=true
  3. (Optional) Change the Binding parameter to use for IdP requests. The Binding can be either
    Post
    or
    Redirect
    . When changing to
    Redirect
    , change
    internalIdpUrl
    to the correct value if the IdP has a different URL for Redirect requests.
    Default:
    Post
    introscope.saml.request.binding=POST
  4. Configure a URL to the IdP SAML 2 SSO page. Consult your IdP configuration for the correct value.
    Example: CA Single Sign-On Used as IdP
    introscope.saml.idpUrl=http://<hostname>/affwebservices/public/saml2sso
  5. (Optional) Change other SAML settings according to your IdP configuration. If you have only one CA APM deployment, use the default settings.
    introscope.saml.issuer=com.ca.apm.webview.serviceprovider
    introscope.saml.webstart.issuer=com.ca.apm.webstart.serviceprovider
    introscope.saml.em.issuer=com.ca.apm.em.serviceprovider
    introscope.saml.principalAttributeName=principalName
    introscope.saml.groupsAttributeName=groups
  6. Open the
    <EM_Home>/config/realms.xml
    file and add the SAML realm. This realm enables the Enterprise Manager to authenticate all users that the IdP authenticates.
    <realm descriptor="SAML Realm" id="SAML Realm" active="true" />
Configuring an External IdP
Configure the IdP using service provider metadata to redirect users back to the application after successful login. The Enterprise Manager contains service provider metadata files for WebView and Web Start Workstation. Metadata files contain configuration settings such as assertion consumer address or encryption keys. If your IdP supports metadata import, use these files to create a service provider entity in the IdP. Metadata files are named in the following format:
<EM_Home>/config/saml-sp*-metadata.xml
. As the Service Provider, provide the following NameID formats:
After login, the username is passed in the SAML assertion response either in the assertion attributes or the NameID tag. Change the attribute name in the configuration file.
For clusters, import service provider metadata from the MOM.
Configure administrator groups and users in the
<EM_Home>/config/domain.xml
file directory. Assign permissions to users for all operations individually and by assigning permissions to the group they are a member of. The authorization definition for Universes in Team Center is also based on user group membership that is retrieved in SAML assertion.
Authorization
SAML 2.0 assertion from the IdP can provide an attribute statement with a defined attribute. The Enterprise Manager can use the defined attribute for user authorization. If provided in SAML assertion, this attribute contains names of groups of which the user is member. These groups can be used to authorize resources in Enterprise Manager line access to agent domains or servers. The default name for this attribute is
groups
.
Change the name by configuring the
introscope.saml.groupsAttributeName
property.
Security Options
Signing
SAML responses can include the signature of the assertion or the whole response.
You configure the SAML responses/assertion signature in the IdP relying party configuration file. You configure a signature for each service provider profile configuration. For internal IdP, the relying party configuration file is located in
<EM_Home>/config/shibboleth/conf/relying-party.xml
.
When an IdP SAML response contains a response or assertion signature, a key within the response verifies the signature. However the trust is validated with the certificates in the WebView certificate store that is located in the
<WebView_Home>/config/internal/server/keystore
file. Add your IdP certificate to this store to facilitate trust validation.
If the signature verification or trust validation fails, user authentication fails and the user is not authenticated to Enterprise Manager.
Encryption
Assertions or NameID in SAML response can be encrypted.
You configure the SAML assertions/NameID encryption in the IdP relying party configuration file. You configure encryption for each service provider profile configuration. For internal IdP, the relying party configuration file is located in
<EM_Home>/config/shibboleth/conf/relying-party.xml
.
The service provider public certificate is present in the service provider metadata file. IdP uses this certificate for encryption. The service provider private key is present in the WebView certificate store that is located in
<WebView_Home>/config/internal/server/keystore
. The public certificate is the RSA key in PEM format. You can change the public certificate in the service provider metadata file. After you make the service provider metadata file change, add the corresponding private key to the WebView certificate store. These changes facilitate decryption.
If the decryption process fails, the user authentication fails and user is not authenticated to Enterprise manager.
Import IdP Public Certificate into trustStore
The Enterprise Manager and WebView trustStore file is located in
<WebView_Home>/config/internal/server/keystore
. The IdP public key must be in the Enterprise Manager and WebView trustStore file for authentication to succeed. When you import the public key, the IdP can send signed SAML responses. The import establishes trust in the received signature, therefore the message. If the trust is not validated, the authentication fails. The IdP metadata file contains the IdP public key. You can import the certificate into the keystore.
Follow these steps:
  1. Copy the certificate information in IdP metadata into a new file (for example,
    idp_public.pem
    ). The certificate in IdP metadata is in a format named PEM.
  2. Add a header and footer to the new file. The file looks similar to this example after the addition:
    -----BEGIN CERTIFICATE-----
    MIIDeTCCAmGgAwIBAgIEb1CaGjANBgkqhkiG9w0BAQsFADBtMQswCQYDVQQGEwJDWjEXMBUGA1UE
    CBMOQ3plY2ggUmVwdWJsaWMxDzANBgNVBAcTBlByYWd1ZTEMMAoGA1UEChMDQVBNMQwwCgYDVQQL
    EwNBUE0xGDAWBgNVBAMTD0NBIFRlY2hub2xvZ2llczAeFw0xNTAyMTgxNjA0NDBaFw0xNTA1MTkx
    NjA0NDBaMG0xCzAJBgNVBAYTAkNaMRcwFQYDVQQIEw5DemVjaCBSZXB1YmxpYzEPMA0GA1UEBxMG
    UHJhZ3VlMQwwCgYDVQQKEwNBUE0xDDAKBgNVBAsTA0FQTTEYMBYGA1UEAxMPQ0EgVGVjaG5vbG9n
    aWVzMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAmEbxIlwPc8yD1JzSN/Fex52Rjfwl
    ImI4QUeKk5f23qFiYM+n/5zMf5aQVfr548E1PrZeuug+PmyiJJzT9waLxXwK7ifQjDndcusYAuYT
    NRALylfse08Z0Wzfd1q54eo7lx+fnzlzFTOhKNa3ecHg5KibPV1TQny/HI+5pRJpMnL7zXu+UkYF
    Xc2VDtX9PXC46M0Z27XkVnx96uQfYI8hHLYkUyw90/8E7U+9/veYbaSafMgPJvmtlgt7jvsk131u
    6YNzB0Kw6eC3J1MJuenu390qYi8hyrifnA969xVNfSzgs8WMo0XWdBWOfFDCqPQlG8O1n24kKjID
    DiwrfwseFwIDAQABoyEwHzAdBgNVHQ4EFgQUQ7SL+nQvflhanTopBW86MfdRrSUwDQYJKoZIhvcN
    AQELBQADggEBAHIcZ/zwuf4w6S6TV58vjy0OS/3Jqc+uGr31AeRzPTip1qjGOJSTVrCSeFzZxcQd
    PsehylsKDAxCdaTsgBuGv0idoC0LofNOJrm2Wwzwxj/1dcUIls4xDXWxHPSjHyLVKUxTtGZLXNKR
    lICLOW1FEUs42G2VR00Zj0t7A1XjHG4Z+UhjclXEXOkWprk9VI9cn2z80jr8VQWlf6sCuEnpkoML
    2G+geeSYvBI5E6QgpjgevIsK0r2NXigH+JTZ+psLa+tPpHhXCkNLNAueq3bgkbodK8E1Dpv8IRX6
    z6LUS/iuMCCtjoA1FGMsF1EZiQ2Pt/MPZgPAAsMrZWkikXqNke4=
    -----END CERTIFICATE-----
  3. Save the file.
  4. Convert the file from PEM to DER format using open ssl.
    openssl x509 -outform der -in idp_public.pem -out idp_public.der
  5. Import the certificate in DER format into the Enterprise Manager and WebView keystore using keytool.
    keytool -import -alias your-alias -keystore keystore -file idp_public.der
    The password for the keystore is
    password
    .
  6. If the Enterprise Manager and WebView are installed at the same location, import the certificate only once into the keystore. If the installations are not in the same location, import the certificate into each of the installations.
Limitations
  • SAML 2.0 can be used only for authentication.
  • We support only one WebView server per cluster.
  • We support only one Web Start Workstation server per cluster.
  • We do not support failover for IdP.
Configuration Options in IntroscopeEnterpriseManager.properties
The following configuration options are available in the
IntroscopeEnterpriseManager.properties
file:
introscope.saml.enable
Option to enable SAML authentication.
Default:
false
introscope.saml.request.binding
Binding for requests to IdP. Binding can be either
POST
or
Redirect
. When changing to
Redirect
, change
internalIdpUrl
to the correct value if the IdP has a different URL for Redirect requests.
Default:
POST
introscope.saml.idpUrl
URL address of IdP SAML 2.0 SSO service. See the IdP documentation for the correct value.
Default:
URL to internal IdP SAML SSO service
introscope.saml.issuer
The service provider identifier string for WebView must match the service provider identifying string in the IdP. The default value matches the value in the service provider metadata file. Importing metadata ensures that it is the same in the service provider and IdP. When running more than one WebView with one IdP, change this setting. Modify the IdP settings to match this string.
Default
:
com.ca.apm.webview.serviceprovider
introscope.saml.webstart.issuer
Service provider identifier string for Web Start Workstation must match the service provider identifying string in the IdP configuration. The default value matches the value in service provider metadata file. Importing the metadata ensures that it is the same in the service provider and IdP. Change this setting when running more than one Web Start Workstation with one IdP. Modify the IdP settings to match this string.
Default:
com.ca.apm.webview.serviceprovider
introscope.saml.principalAttributeName
SAML assertion response attribute that is used as the source of the username. If not present in the assertion response then NameID is used.
Default:
principalName
introscope.saml.groupsAttributeName
SAML assertion response attribute that is used as the source of authorization groups.
Default:
groups
introscope.saml.webstart.tokenTimeoutInSeconds
Set the period for which the Webstart Workstation SAML SSO tokens are valid. After authentication, you must start Webstart Workstation within this period. If you do not start Webstart Workstation within this period, your authorization expires. Refresh the Webstart Workstation page to generate a new token.
Default:
60
introscope.saml.internalIdp.enable
Option to enable the internal IdP.
Default:
false
introscope.saml.sp.privatekey.alias
Option to configure the private key alias.
Default:
spprivatekey
introscope.saml.idp.time.skew
Option to configure time skew between the IdP and service provider. Value is in seconds.
Default:
60
apm.webview.saml.sp.truststore
WebView configuration property that is used for SAML purposes. Option to configure keystoreFile, relative to the
<EM_Home>
directory.
Default:
config/internal/server/keystore
Example of SAML Configuration in IntroscopeEnterpriseManager.properties
###############################################################################
# SAML SSO Settings
#
###############################################################################
introscope.saml.enable=true
introscope.saml.idpUrl=http://siteminder01.ca.com/affwebservices/public/saml2sso
introscope.saml.issuer=com.ca.apm.webview.serviceprovider
introscope.saml.webstart.issuer=com.ca.apm.webstart.serviceprovider
introscope.saml.principalAttributeName=principalName
introscope.saml.groupsAttributeName=groups
introscope.saml.internalIdp.enable=false