> For AI agents: [llms.txt](https://docs.trustedauth.com/llms.txt) provides a Markdown index of this documentation.

# Add generic SAML Identity Provider

Before you begin, you need to obtain the following from your Identity Provider:

- SP Entity ID
- SSO endpoint
- Identity Provider verification certificate (one or two)
- Optional values:
  - Issuer, for example the Entity ID of the Identity Provider.
  - Assertion Consumer Service URL if you are using a proxy server.

### Integrate a generic SAML Identity Provider

1. Click Menu icon **>** **Security > Identity Providers**. The **Identity Providers List** page appears.

2. Click **Add** and then select **Generic (SAML)** from the drop-down list. The **Add Identity Provider** page appears.

3. Configure the **Identity Provider Settings**, as follows:

   1. Enter a **Name** for the Identity Provider.

   2. In the **SP Entity ID** field, enter the main name of your SAML service provider.

      > **Example:** `https://mycompany.<locale>.trustedauthcom/api/saml`

   3. Optional. In the **Issuer URL** field, enter the Entity ID of the Issuer to require the SAML assertion issuer response to be verified using this value. You can also leave this field blank if you do not want the valued to be verified.

   4. Optional. In the **Assertion Consumer Service URL** field, enter the redirect ID if you are using a proxy server. Otherwise, keep the default value.

   5. Optional. In the **Name ID Policy Format**, enter the Name ID format if the SAML value to be request requires this value to be requested.

   6. Optional. In the **Requested Information from the Identity Provider**, add the following:

      - Add a **User Name (Login Hint) Parameter** to append a parameter (Login Hint) to be used as part of the SAML assertion request to identify the user. Specifying a value of NameID will include this value in the SAML request in contrast to an HTTP request parameter.
      - Add a **User Name (Login Name) Format** to include a specific format when a NameID username parameter is used.

   7. Select **Force Authentication** to require a user to reauthenticate at each login attempt.

   8. Optional. In the **Auth Context Request Values** field, enter the auth context request if the SAML request requires this value to be requested.

4. Optional. Enter the **Federation Metadata URL** to import your Identity Provider settings.

5. If you do not have a Federation URL, do the following:

   - Enter the **SSO Endpoint** that receives the SAML request.
   - Enter the **SLO Endpoint** **url** that receives the logout requests.

6. Click **Fetch Configuration** to obtain the fields for the **SAML Endpoints**.

7. Configure **Signature Verification**. At least one signature (SAML Request or SAML Assertion) is always required and verified.

   - Select **SAML Response** to always require signature verification for the SAML response.

   - Select **SAML Assertion** to always require signature verification for the SAML response.

   - Optional. Click Arrow Up From Line icon and browse to upload the **SAML Verification Certificate**.

   - Optional. Click Arrow Up From Line icon and browse to upload the **SAML Verification Certificate2**.

   note
   Expired certificates are not supported and cannot be used to validate SAML signatures.

8. Configure **User Management**.

   1. Select **Create User (Authentication)** to create the user whose information is returned from the Identity Provider if it does not already exist.

   attention
   **Create user** allows anyone with access to your chosen Identity Provider to create a user in your IDaaS account. Depending on your IDaaS configuration, new users created by your IDP will be able to access all the resources controlled by your IDaaS account. This may be a concern if your Identity Provider has no limits on who can create an account or if it has a large user base. Analyze the risks before enabling this option.

   2. Select **Update User** **(Authentication)** to update the IDaaS user to match the Identity Provider during authentication.

      If you select **Update User (Authentication)**, the IDaaS system user attributes and any existing IDaaS custom user attributes can be set based on SAML attribute mappings.

      After user authentication, if the user exists in IDaaS, IDaaS compares the attributes of the existing user to the SAML attribute returned from the Identity Provider If they are different, the IDaaS user attributes are updated with the SAML attribute values.

   3. The following system attributes are mandatory in IDaaS by default:

      - Email: email
      - First name: given_name
      - Last name: family_name

   4. If they do not exist in your Identity Provider account, you must add them to your user profiles or make them optional in IDaaS. See your Identity Provider documentation for information on how to add a new user or update an existing user profile.

   5. Select **Update User** **(Verification)** to update the IDaaS user to match the Identity Provider during verification.

      If you select **Update User (Verification)**, the IDaaS system user attributes and any existing IDaaS custom user attributes can be set based on SAML attribute mappings. After user verification, the IDaaS user attributes are updated with the SAML attribute values.

9. Select the **System User Attributes** used to identify the user.

10. Configure **Groups, Organizations, and role mapping**.

    1. Select applicable groups from the **Select Group** drop-down list to assign created users to groups.

    2. Select applicable organizations from the **Select Organization** drop-down list to assign created users to organizations.

    3. In the **Group Mapping** field, enter the claim containing the group membership for users.

       Only existing groups are mapped. If a group is not found, it is not mapped. The mapping does not remove any existing groups. If group mapping is not configured, existing groups remain.

    attention
    **Group Mapping** allows anyone with access to this Identity Provider to have their IDaaS groups include the groups defined by the Identity Provider. Groups set the policies applied to users. Enabling this setting could result in users having access to unexpected policies, especially if the Identity Provider has different user access policies than IDaaS. Analyze the risks before configuring this option.

    4. In the **Role Mapping** field, enter the SAML attribute containing the role membership for users.

       Only existing roles are mapped. If the role is not found, it is not mapped. The mapping does not remove an existing role. If a role is mapped and is different from the existing role, the existing role is replaced. If role mapping is not configured and if there is an existing role exist, the existing role remains.

    attention
    **Role Mapping** allows anyone with access to this Identity Provider to have their IDaaS account role defined by the Identity Provider, including the super administrator role that has access to all the resources controlled by your IDaaS account. Enabling this setting could result in unexpected access, especially if your Identity Provider has different user access policies than IDaaS. Analyze the risks before configuring this option.

11. Configure **Branding** as follows:

    1. Enter the **Login Button Text**. This is the text that appears on the IDaaS log in page.
    2. If your Identity Provider has a login button image, enter the URL in the **Login Button Image** field. The login button appears on the IDaaS log in page.

12. Configure **User Authentication** as follows:

    1. Select **Enabled for User Authentication**.

       During authentication, the Identity Provider returns either a SAML NameID value or a SAML attribute that is used to find the IDaaS user based on a user attribute. The attribute mappings in the SAML NameID value or the SAML attribute must uniquely identify the IDaaS user for mapping to be successful. If mapped successfully, the Identity Provider can be used as an alternative authentication method.

    2. In the **Domains** field, enter the domains returned from the SAML Identity Provider after authentication. When set, any user ID ending with the domain (for example <user@mycompany.com>), or one of the domains is linked to the Identity Provider. Separate each domain with a space.

    3. Select the **User** **Attribute used to identity the user** to to map a SAML NameID or SAML attribute returned from the Identity Provider to the IDaaS The default is User ID/Alias.

    4. In the **Attribute (or NameID) used to identity the user** field, enter the attribute in the SAML assertion that stores the identity of the user.

    5. Optional. Configure **System** **User Match Mapping** and **Custom User Mapping**.

       - Every configured attribute must match the corresponding Identity Provider claim value and the IDaaS user attribute, which must both exist and match.
       - User matching is case-insensitive.

13. Optional. If user verification is used with the Identity Provider, under **User Verification**, do the following:

    1. Select **Enable for User Verification** if you want the Identity Provider to be used for verification. For example, you want do this to allow SAML Identity Provider to validate a user's photo or private identification information and return corresponding the SAML attribute that is mapped to the IDaaS user attribute.

    2. Optional. Configure **System User Match Attribute** and **Custom User Match Attribute**.

       - Every configured attribute must match the corresponding Identity Provider SAML attribute and the IDaaS user attribute, which must match.
       - User matching is case insensitive.

    note
    See [Manage user policies](/docs/people-and-access/manage-user-policies.md) for more information on the verification process.

14. Click **Save**.