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.
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).
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:
More Information:
FAQs.
SAML Authentication Workflow
The following sequence diagram shows the SAML authentication workflow in 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. 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 (new)
    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 Identity Provider configuration values as shown below:
    Attribute
    Description
    Notes
    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.
  8. 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.
    Add Email Domains
    Specify valid unique email domains of the users in this IdP. Based on this email domain, Okta chooses the IdP to authenticate (IdP discovery). You can either use comma-separated values or use the
    Add
    button to add email domains individually.
    Select Authorization Type
    Portal
    Select this authorization type, to manage the organization and role mapping from Portal. This means, you can map the Developer user (who has logged in to API Portal, at least once) to multiple organizations by editing the user profile.
    Identity Provider
    Select this authorization type, to add the organization and role attributes as provided by this external authentication scheme.
    This option does not allow a Portal administrator to map a Developer user to multiple organizations. If you want to change the authorization type from Identity Provider to Portal after creating the authentication scheme, see
    Change Existing Authentication Scheme from "Identity Provider" to "Portal"
    section from the Map Existing IdP Users to Multiple Organizations topic.
    When Identity Provider is selected as the Authorization type
    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 Get Started - User Types, Roles and Permissions section.
  9. Select
    Create
    to save the SAML SSO configuration.
    The Authentication Schemes page opens showing the new SAML SSO configuration in the list. It also shows the Assertion Consumer Service (ACS) URL for the configuration.
    After you create the SAML SSO configuration, the new IdP will be in
    Inactive
    state. Contact Layer7 Support and the team will interface with Broadcom IT to review and activate the IdP. You can then start using the new IDP to login into API Portal.
    SAML authentication scheme is configured.
If you have configured the authorization type as Portal, any new user who logs in to Portal has only Guest user privileges.
Map a Developer to Multiple Organizations
To map a Developer to multiple organizations, you need a Portal administrator. Use one of the following methods:
  • Use an IdP user with Portal administrator role.
    1. Create another SAML SSO authentication scheme with authorization type as "Identity Provider".
    2. Add the role as Portal Administrator.
    3. Log in to API Portal as the Portal administrator.
    4. Edit the Developer user profile to map to multiple organizations.
  • Use the default Portal administrator added and managed in API Portal.
    • Edit the Developer user profile to map to multiple organizations.
Set SAML Authentication Scheme as a Default Scheme
(Only for SaaS users)
You can only configure the default login approach to be "SAML" and cannot choose the default IdP within the SAML.
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 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 Get Started - User Types, Roles and Permissions section.
For solutions to troubleshoot issues that may occur while configuring the SAML authentication schemes, see the troubleshoot section. See our 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.
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. From the menu bar, select the gear icon,
    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
    .
    (Only for SaaS users)
    If the selected provider is
    SAML SSO (new)
    , the
    Email Domains
    field is read-only and you cannot edit it.
Delete SAML SSO Configuration
To delete the SAML SSO configuration:
  1. Log in to the API Portal as an Administrator.
  2. From the menu bar, select the gear icon,
    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.