Configure SAML Single Sign-On

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.  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.
apip42
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 Developer Portal
 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 Developer Portal
 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).
To log in to portal, SAML SSO users need to use their IdP UI.
The following tasks are related to creating and managing a SAML SSO configuration:
2
2
More Information:
FAQ.
SAML Authentication Workflow
The following sequence diagram shows the SAML authentication workflow in CA API Developer API Portal.
SAML Authentication Workflow in API Portal
SAML Authentication Workflow in API Portal
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 Manage Users 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 Developer Portal
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 Developer Portal
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 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
.
Troubleshooting
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.