Step 3: Create a SAML SSO Authentication Scheme

After setting up SAML SSO on the API Gateway, 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.
apip43
After setting up SAML SSO on the API Gateway, 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.
The following tasks are related to creating and managing a SAML SSO configuration:
Follow these steps:
  1. Log in as an administrator.
  2. From the menu bar, select the gear icon,
    Authentication
    .
  3. On the
    Authentication Schemes
    page, select the
    Add Authentication Scheme
    button.
  4. For
    Providers
    , select
    SAML SSO (Deprecated)
    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.
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 ACS URL should be the <
gateway host
>:<
port
> on which SAML has been configured in Step 2: Set Up SAML SSO on the API Gateway.
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.
SAML Token Attributeln
Defines how the SAML Token Attribute content is returned from the SAML IdP.  The content is returned as a parameter.
Service provider ID
Specify the service provider identification that identifies the CA API Developer Portal service to establish the connection between IdP and the Service provider.
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:
These field values depend on how IdP is configured on your gateway. Ensure that you enter the same values that you have used in Step 2: Set Up SAML SSO on the API Gateway.
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.
Portal
Select this authorization type, to manage the organization and role mapping from Portal. For more information, see Map IdP Users to Multiple Organizations
Identity Provider
Select this authorization type, to add the organization and role attributes, as provided by this external authentication scheme.
Organization
(When IdP is selected) Specifies the organization attribute that a user is associated with.
Role
(When IdP is selected) 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.
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.
API 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 Get Started - User Types, Roles and Permissions section.
For information about how to set up SSO for the API Gateway, see "Working with CA Single Sign-On" in the API Gateway documentation.
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 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.