Configure SSO for Local SaaS Environments

This article describes how to configure an IdP in your local environment for testing SAML SSO features.
This article describes how to configure an IdP in your local environment for testing SAML SSO features.
SAML 2.0 is an XML-based protocol that uses security tokens to pass user authentication and authorization data between an IdP, and a service provider.
API Management SaaS
adheres to SAML 2.0 standards and uses user authentication when integrated with a SAML IdP system. Employing SAML IdP to authenticate and manage API Portal users provides the benefit of SSO.
In the SAML context, the
API Management SaaS
is the service provider (SP).
The following tasks are supported:
  • Configuration of multiple SAML SSO schemes on CA API Developer Portal
  • Service provider initiated Web Single Sign-On (Web SSO).
Note the following conditions:
  • If you are using the Portal API, SAML SSO is not supported. The Portal API login policy does not support a third-party system for authentication.
  • During SSO testing, the Gateway serves as the IdP.
  • This procedure applies to SaaS and hybrid deployments.
This article contains the following information:
Prerequisites
Verify that your environment meets the following prerequisites before you configure an IdP:
  • CA API Management SaaS is running.
  • The Portal Gateway and the Tenant Gateways are running.
  • SoapUI or your favorite client tool is ready to consume services.
Integrate SAML SSO
Administrators can integrate SAML SSO using any one of following ways:
  • Integrate SAML SSO from the Tenant Gateway
  • Integrate SAML SSO from
    API Management SaaS
Integrate SAML SSO from the Tenant Gateway
Complete the following steps to create mock SAML IdP services in the Tenant Gateway for testing SSO:
  1. Use Chrome Postman, or another tool, such as DHC, to send a message to Tenant Gateway endpoint:
    • Endpoint
      : "
      https://
      <Your_Tenant_Gateway>
      :9443/restman/1.0/bundle"
    • Method
      : PUT
    • Authorization
      : Basic Auth: your Tenant Gateway Policy Manager login credential. (for example, pmadmin / 7layer)
    • Content-type
      : application/xml
    • You do not need Origin or Referrer headers
    • Body
      : select
      binary
      , select
      mock_sso_bundle.xml
      If consumption succeeds, you are expected to get a 200 OK response.
  2. Log in to the Policy Manager and perform the following steps:
    • Verify that a folder that is named
      Mock SAML IDP Services
      appears under the root tree.
      Note:
      If you were logged in to Policy Manager before you sent the request, manually refresh the Policy Manager to see the folder.
      Three services exist under the folder:
      • Redirect to SAML Login Page [/samlReqPost]
      • SAML Base64 Login [/testSamlLogin]
      • SAML Response Generation 1 [/testSAMLResponse]
    • Verify that the user group
      SAMLUsers
      exists in the Gateway, as follows:
      1. Navigate to
        Home
        ,
        Search Identity Provider
        ,
        Type: Groups
      2. Select
        Search
        . The SAMLUsers group appears.
  3. In
    Mock SAML IDP Services
    , replace the Gateway URLs with URLs for your environment:
    • In line 3, Redirect to SAML Login Page [/samlReqPost], set Property/Header Value to
      http://
      <Your_Tenant_Gateway>
      :8080/testSamlLogin
      For example, Property/Header Value: "http://emportal-tssg1.abc.com:8080/testSamlLogin"
    • In line 5, SAML Response Generation 1 [/testSAMLResponse1], Set Context Variable portalUrl as String to:
      https://
      <Your_Tenant_Gateway>
      :8443/portalAuth/sso/validateSaml
      Note:
      The URL should match the SSO endpoint on the API Portal SSO Configuration page.
  4. Create users for different Portal roles and assign them to the
    SAMLUsers
    group, as follows:
    1. Go to
      Home
      ,
      Create Internal User
      . Create a user called samladmin. Specify the following information:
      Password (Specify any password)
      First Name
      Last Name
      Email
    2. Repeat step a to create the following additional users:
      samlapiowner
      samlorgadmin
      samldev
    3. Go to
      Home
      ,
      Search Identity Provider
      ,
      Type: Users
      . Search for and select samladmin. On the Groups tab, add the SAMLUsers group to this user.
    4. Repeat step c for the following users:
      samlapiowner
      samlorgadmin
      samldev
  5. In line 10, set context variable userOrg to the default organization that is used in userGroup role mapping payload:
    SAML Response Generation.png
  6. Create different Portal roles in "SAML Response Generation 1 [/testSAMLResponse1]" as follows:
    SAML Response Generation Line 11.png
The preceding image illustrates the following changes:
Set ${authenticatedUser.login} to be "samladmin", "samlapiowner", "samlorgadmin", and "samlorgdev".
Set userGroup to  "CN=admin", "CN=apiowner", "CN=devorgadministrators", "CN=developer".
The following example shows how to configure userGroup to support different roles in different organizations:
[ { "organization": "HR", "role": "developer" }, { "organization": "Service", "role": "developer" }, { "organization": "Marketing", "role": "organizationAdmin" } ]
Integrate SAML SSO From
API Management SaaS
The following tasks are related to creating and managing a SAML SSO configuration:
More Information:
FAQ.
SAML Authentication Workflow
The following sequence diagram shows the SAML authentication workflow in CA API Developer API Portal.
SAML Authentication flow
SAML Authentication flow
Create a SAML SSO Authentication Scheme
You create the authentication scheme by adding provider configuration values, then mapping user attributes and roles. The resulting authentication scheme can be set as the default to render SAML login page.
Follow these steps:
  1. Log in as an administrator.
  2. Select
    Administration
    ,
    Authentication
    .
  3. On the
    Authentication Schemes
    page, select the
    Add Authentication Scheme
    button.
  4. For
    Providers
    , select
    SAML SSO
    provider from the available providers, and select
    Next
    .
  5. For
    Basic Details
    , type the SAML SSO provider name and a description.
  6. (Optional) Add a provider icon, and select
    Next
    . The provider icon must be a PNG file, and the size must not exceed 500 KB.
  7. Add provider configuration values, then map user attributes and roles.
    See sections following these instructions for details.
  8. Select
    Create
    to save the SAML SSO configuration.
    SAML authentication scheme is configured.
Set SAML Authentication Scheme as a Default Scheme
After
API Portal
is integrated with SAML IdP, you can set the SAML authentication scheme as a default scheme. On the Authentication Schemes page, for a SAML authentication scheme select
Set as Default
in the
Actions
menu. Once the SAML SSO authentication scheme is your default scheme,
API Portal
renders the selected SAML IdP login page to prompt for user credentials.
If the SAML authentication scheme is not set as a default authentication scheme, the SAML Provider is listed on the
API Portal
login page. Select the SAML Provider to open the SAML IdP login page. Provide the user credentials that are verified on the SAML IdP, and the user is logged in to CA API Developer Portal.
If the SAML Provider is set as default and you are unable to log in using SAML, use the
hostname/admin/login
URL to log in to
API Portal
and verify the SAML provider configuration.
CA API Developer portal does not support user creation and management in IdP. User management has to be done at the SAML IdP .
Having configured IdP with Portal, Portal administrators and Organization administrators can still create and manage users in Portal authenticated using CA APIM Authentication Scheme. For information about how to manage users from Portal, see the User Types, Roles and Permissions section.
For solutions to troubleshoot issues that may occur while configuring the SAML authentication schemes, see the FAQ, sections for queries about the SAML SSO integration with
API Portal
.
For information about how to set up SSO for the API Gateway, see "Working with CA Single Sign-On" in the API Gateway documentation.
Add Provider Configuration Details
Fill in provider configuration details as shown in the following table.
Attribute
Description
Notes
Assertion Consumer Service (ACS) URL
Assertion Consumer Service (ACS) URL for API Portal Authentication. SAML response is received at this URL. The field value is populated and is non-editable.
Identity Provider URL
SAML Identity Provider URL for user authentication.
For example, if the IdP is Salesforce:
http://mydomain.my.salesforce.com?login.
The URL is the SSO login page for the API Portal.
SAML Binding
Select the SAML Binding to determine how SAML requests map to communication protocols. Specify the request in POST or Redirect form to send it to the SAML IdP.
SAML Token Attribute
The value is populated with the SAML Token attribute name that contains the user information.
The value is read-only. No configuration available.
SAML Token Attributeln
Defines how the SAML Token Attribute content is returned from the SAML IdP.  The content is returned as a parameter.
The value is read-only. No configuration available.
Service provider ID
Specify the service provider identification that identifies the
API Management SaaS
service to establish the connection between IdP and the Service provider.
If you do not have any specific service provider ID, use the default ID that
API Management SaaS
generates.
Issuer ID
Specify the SAML issuer ID.
The SAML Response issuer should be set as the IdP's entity ID.
Upload Trusted Certificate.
Upload a trusted certificate in X.509 format to validate the signed SAML response that an Identity Provider provides.
Map User Attributes and Roles
Map
API Portal
user attributes to conceptually similar attributes that the SAML IdP returns.
The following attribute mappings are required:
User Attribute
Notes
Email
Specifies the email address attribute that is defined for users in your Identity Provider.
First Name
Specifies the first name attribute that is defined for users in your Identity Provider.
Last Name
Specifies the last name attribute that is defined for users in your Identity Provider.
Login
Specifies user ID attribute that is used for login.
Organization
Specifies the organization attribute that a user is associated with.
Role
Specifies the user role attribute that is defined in your identity provider.
Select a role from the available list and map it to conceptually similar user roles in your SAML IdP:
      • Portal Administrator
      • API Owner
      • Developer
      • Org Administrator
For more information about the roles and responsibilities of the
API Portal
users, see the User Types, Roles and Permissions section.
Establish Trust on SAML IdP
Collect the information that is required to establish trust from the Provider Configuration table. Ensure that the ACS URL provided is used to establish the trust.
The following values are required to establish trust on SAML IdP:
Information Type
Required Values
Service provider-specific information.
Requires the following values:
  • Assertion Consumer Service (ACS) URL
    URL where the SAML response is received from the IdP.
  • Service provider ID
    API Portal
    entity ID, or SAML request issuer. If the IdP does not have a service provider ID, use the default value that
    API Portal
    displays in the configuration screen.
API Portal
-specific information:
Requires the following values:
  • SAML Token Attribute
  • SAML Token Attributeln
Edit SAML SSO Configuration
To edit the SAML SSO details:
  1. Log in to the API Portal as an Administrator.
  2. Select
    Administration
    ,
    Authentication
    .
  3. On the
    Authentication Schemes
    page, select the down arrow in the
    Actions
    section of a configured SAML SSO, and select
    Edit
    .
  4. In the Edit Authentication Scheme page, select SAML SSO configuration to edit. For example, to edit the provider details, select the Provider Configuration option. Make the required changes and select
    Save
    .
Delete SAML SSO Configuration
To delete the SAML SSO configuration:
  1. Log in to the API Portal as an Administrator.
  2. Select
    Administration
    ,
    Authentication
    .
On the Authentication Schemes page, select the down arrow in the
Actions
section of a configured SAML SSO, and select
Delete
.
Troubleshoot
Issues that occur while Configuring the SAML Authentication Schemes
This section describes the solutions to troubleshoot issues that may occur while configuring the SAML authentication schemes.
Symptom:
Creating the SAML authentication scheme on
API Portal
throws the following error:
The specified username and password was invalid.
Reason:
The issue may be due to one of the following reasons:
  • incorrect Identity Provider URL, or Issuer ID, or trusted certificate is provided as the provider configuration details.
  • incorrect Assertion Consumer Service (ACS) URL, or Service provide ID is provided while establishing the trust on IdP.
  • incorrect mapping of the Role or Organization attributes.
Solution:
Ensure the:
  • provider configuration details are valid.
  • service provider ID and ACS URL are similar to the one that exists on
    API Portal
    .
  • role attribute that is mapped on
    API Portal
    is conceptually similar in your SAML IdP. The role attribute mapping that is returned in the SAML response should contain one of the roles that are mapped on
    API Portal
    as role attributes.
  • organization that SAML response returns as part of organization attribute mapping must exist in
    API Portal
    .
If the issue persists after you have ensured all the values for creating authentication schemes are correct, we recommend re-creating the authentication scheme.
Issues that Occur while Configuring SSO for Local SaaS Environments
API Portal SSO Fragments are Not Updated
Issue:
In existing environments, you do not see updated Fragments in the API Portal SSO folder on the Tenant Gateway after running updaterSA.
Solution:
Follow these steps:
  1. Log in to the Tenant Gateway Policy Manager.
  2. Go to
    Tasks
    ,
    Manage Scheduled Tasks
    .
  3. Remove
    Portal Sync SSO Configuration
    .
  4. Delete the API Portal SSO folder under the root tree.
  5. Open the following URL in a browser:
    https://<
    Portal Gateway Host Name
    >:9446/enroll/tenant1?reset=true
  6. Log in as the admin user.
  7. On the Enroll API Proxy page, select
    SELECT URL
    to copy the URL.
  8. Log in to the Tenant Gateway Policy Manager.
  9. Go to
    Tasks
    ,
    Additional Actions
    ,
    Enroll with Portal
    , Paste the Enrollment URL here, and select
    Apply
    . Select
    OK
    on the confirmation screen.
  10. Select OK again.
  11. Refresh the Tenant Gateway Policy Manager.
  12. Verify the following steps:
    • The
      API Portal SSO
      folder was recreated and contains updated Fragments.
    • The Portal Sync SSO Configuration appears under Scheduled Tasks.
    • You can successfully log in to the API Portal with saml-users.
Open Listen Port 9448 on Portal Gateway for Existing Environments
Issue:
The Portal and Tenant Gateways do not sync for SSO in existing environments.
Solution:
Manually open the listen port 9448 on the Portal Gateway.
Follow these steps:
  1. Use SoapUI or other client tools to send a PUT message to your Portal Gateway:
    • Endpoint: "https://
      <Your_Portal_Gateway>
      :8443/restman/1.0/listenPorts/41ff0f5f2b43e41d8fb814cf99cda2c5"
    • Method: PUT
    • Request HEADER: Basic authorization: Specify the Portal Policy Manager login credentials. (for example, pmadmin / 7layer)
    • Request BODY: Content-Type: application\xml; Body:
      <l7:ListenPort id="41ff0f5f2b43e41d8fb814cf99cda2c5" version="2"
      xmlns:l7="http://ns.l7tech.com/2010/04/gateway-management">
      <l7:Name>TSSG Sync SSO Port</l7:Name>
      <l7:Enabled>true</l7:Enabled>
      <l7:Protocol>HTTPS</l7:Protocol>
      <l7:Port>9448</l7:Port>
      <l7:EnabledFeatures>
      <l7:StringValue>Published service message input</l7:StringValue>
      </l7:EnabledFeatures>
      <l7:TargetServiceReference id="22a6e8737c85fc3833fb7164f029efcf" resourceUri="http://ns.l7tech.com/2010/04/gateway-management/services"/>
      <l7:TlsSettings>
      <l7:ClientAuthentication>Optional</l7:ClientAuthentication>
      <l7:EnabledVersions>
      <l7:StringValue>TLSv1.1</l7:StringValue>
      <l7:StringValue>TLSv1.2</l7:StringValue>
      </l7:EnabledVersions>
      <l7:EnabledCipherSuites>
      <l7:StringValue>TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384</l7:StringValue>
      <l7:StringValue>TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384</l7:StringValue>
      <l7:StringValue>TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA</l7:StringValue>
      <l7:StringValue>TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384</l7:StringValue>
      <l7:StringValue>TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384</l7:StringValue>
      <l7:StringValue>TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA</l7:StringValue>
      <l7:StringValue>TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256</l7:StringValue>
      <l7:StringValue>TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256</l7:StringValue>
      <l7:StringValue>TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA</l7:StringValue>
      <l7:StringValue>TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256</l7:StringValue>
      <l7:StringValue>TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256</l7:StringValue>
      <l7:StringValue>TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA</l7:StringValue>
      <l7:StringValue>TLS_ECDHE_ECDSA_WITH_3DES_EDE_CBC_SHA</l7:StringValue>
      <l7:StringValue>TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA</l7:StringValue>
      <l7:StringValue>TLS_ECDHE_ECDSA_WITH_RC4_128_SHA</l7:StringValue>
      <l7:StringValue>TLS_ECDHE_RSA_WITH_RC4_128_SHA</l7:StringValue>
      <l7:StringValue>TLS_DHE_RSA_WITH_AES_256_GCM_SHA384</l7:StringValue>
      <l7:StringValue>TLS_DHE_RSA_WITH_AES_256_CBC_SHA</l7:StringValue>
      <l7:StringValue>TLS_RSA_WITH_AES_256_GCM_SHA384</l7:StringValue>
      <l7:StringValue>TLS_RSA_WITH_AES_256_CBC_SHA</l7:StringValue>
      <l7:StringValue>TLS_DHE_RSA_WITH_AES_128_GCM_SHA256</l7:StringValue>
      <l7:StringValue>TLS_DHE_RSA_WITH_AES_128_CBC_SHA</l7:StringValue>
      <l7:StringValue>TLS_RSA_WITH_AES_128_GCM_SHA256</l7:StringValue>
      <l7:StringValue>TLS_RSA_WITH_AES_128_CBC_SHA</l7:StringValue>
      <l7:StringValue>SSL_DHE_RSA_WITH_3DES_EDE_CBC_SHA</l7:StringValue>
      <l7:StringValue>SSL_RSA_WITH_3DES_EDE_CBC_SHA</l7:StringValue>
      <l7:StringValue>SSL_RSA_WITH_RC4_128_SHA</l7:StringValue>
      <l7:StringValue>SSL_RSA_WITH_RC4_128_MD5</l7:StringValue>
      <l7:StringValue>SSL_DHE_RSA_WITH_DES_CBC_SHA</l7:StringValue>
      <l7:StringValue>SSL_RSA_WITH_DES_CBC_SHA</l7:StringValue>
      <l7:StringValue>TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA</l7:StringValue>
      <l7:StringValue>TLS_ECDH_RSA_WITH_AES_256_CBC_SHA</l7:StringValue>
      <l7:StringValue>TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA</l7:StringValue>
      <l7:StringValue>TLS_ECDH_RSA_WITH_AES_128_CBC_SHA</l7:StringValue>
      <l7:StringValue>TLS_ECDH_ECDSA_WITH_RC4_128_SHA</l7:StringValue>
      <l7:StringValue>TLS_ECDH_RSA_WITH_RC4_128_SHA</l7:StringValue>
      <l7:StringValue>TLS_ECDH_ECDSA_WITH_3DES_EDE_CBC_SHA</l7:StringValue>
      <l7:StringValue>TLS_ECDH_RSA_WITH_3DES_EDE_CBC_SHA</l7:StringValue>
      </l7:EnabledCipherSuites>
      </l7:TlsSettings>
      <l7:Properties>
      <l7:Property key="useExtendedFtpCommandSet">
      <l7:StringValue>false</l7:StringValue>
      </l7:Property>
      </l7:Properties>
      </l7:ListenPort>
  2. If the response succeeds, you see the " 201 Created" response.
  3. Log in to the Portal Policy Manager.
  4. Go to
    Tasks
    ,
    Manage Listen Ports
    .
  5. Verify that port 9448 is open for the TSSG Sync SSO Port.