---
title: "How to: Use Certificates With SAML Assertions"
slug: "how-to-using-certificates-with-saml-assertions"
updated: 2025-11-10T20:33:25Z
published: 2025-11-10T20:33:25Z
canonical: "docs.unqork.io/how-to-using-certificates-with-saml-assertions"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.unqork.io/llms.txt
> Use this file to discover all available pages before exploring further.

# How to: Use Certificates With SAML Assertions

## Overview

**Certificates for SAML (Security Assertion Markup Language) Assertion** help Creators implement higher security and compliance standards by leveraging their own trusted X.509 certificates. In this how-to guide, you'll create a certification for SAML assertion, then add it to a new or existing SAML SSO **(Single-Sign On)** configuration.

## Create a SAML Certificate

Access the [Certificate Management](/v1/docs/certificate-management) administration settings to create a new SSO **(Single-Sign On)** Certificate. For this how -to guide, you'll need access to an approved `encyrption.pfx` file.

To create a SAML Certificate from the [Unqork Homepage](/v1/docs/navigating-the-udesigner-homepage):

![](https://cdn.us.document360.io/15548f06-2fba-434c-b0c1-5df88317dbd7/Images/Documentation/samlCertificate_thumb_0_0.jpg?sv=2026-02-06&spr=https&st=2026-11-09T16%3A59%3A10Z&se=2026-11-09T17%3A59%3A10Z&sr=c&sp=r&sig=nYpSjJoHUAR91zAhVTwrHlmx3ZQ9ZMtIIjX0v0nfG%2F4%3D)

1. From the Homepage, click **Administration**.
2. Under Integration, select **Certificate Management**. The Certificate Management page displays.
3. Click **+ New Certificate**. The New Certificate modal displays.
4. In the **Certificate Title*** field, enter a name.

> [!TIP]
> Unqork recommends avoiding spaces and special characters in certificate titles. For example: `sso-cert` instead of `sso cert`.
5. In the **PFX or PKCS12 Encoded (Hex) Private Key and Certificate Chain** field, enter your `encyrption.pfx` file in Hexadecimal format with all spaces excluded. For example, if your `encryption.pfx` hex code looks like the following: `54 68 69 73 20 69 73 20 68 65 78 20 63 6F 64 65 2E`, then remove the spacing so it looks like the following: `546869732069732068657820636F64652E`.

> [!WARNING]
> The size of your `encryption.pfx` hexadecimal code might require a text or coding software tool to remove all spaces between hexadecimal values.
6. In the `PFX Passphrase` field, enter the password used to protect the certificate.

> [!WARNING]
> Never share passphrases over unsecure networks.
7. From the **Certificate Type** drop-down, select `SAML`.
8. Click **Add Certificate**. The New Certificate modal closes and the certificate displays in the Certificate Management list.

The certificate for SAML Assertion can now be added to a new or existing SAML SSO configuration.

## Adding a SAML Certificate to a New or Existing SSO

After creating a SAML Certificate, add it to a SAML SSO Configuration using the [Single Sign-On (SSO) Management](/v1/docs/single-sign-on-ssomanagement) page.

Select one of the following methods below:

Add to New SAML SSOAdd to Existing SAML SSO

## Add a SAML Certificate to a New SSO

> [!TIP]
> For in-depth details on creating new SSO configurations, view the [SSO SAML Express and Designer Guides](/docs/how-to-using-certificates-with-saml-assertions#sso_saml_express_and_designer_guides) section.

1. At the top right of the Unqork Designer Platform, click **Administration**.
2. Under Environment, select **Single Sign-On (SSO)**.
3. Click **+ New SSO**.
4. From the **+ New SSO** drop-down, select **Express** or **Designer**.
5. In the **SSO Name** field, enter a unique name for your configuration.

> [!TIP]
> This name is used to generate the default SP Entity ID.
6. In the **Default Role** drop-down, select a role.

> [!NOTE]
> When setting up SSO for Express View, select a default role with the lowest-level permissions. This lets you rely on the value stored in Okta to determine higher-level permissions.
7. (Optional) In the **Default Groups** list, select one or more groups.
8. Click **Next**. The Configure Protocol tab displays.
9. Set **Select Protocol*** to ![](https://cdn.us.document360.io/15548f06-2fba-434c-b0c1-5df88317dbd7/Images/Documentation/Screenshot 2025-09-16 124914.png?sv=2026-02-06&spr=https&st=2026-11-09T16%3A59%3A10Z&se=2026-11-09T17%3A59%3A10Z&sr=c&sp=r&sig=nYpSjJoHUAR91zAhVTwrHlmx3ZQ9ZMtIIjX0v0nfG%2F4%3D) **SAML**.
10. In a text editor, open the `IdP metadata` XML file provided by the SSO service.
11. In the **IdP Metadata XML*** field, copy and paste the contents of the file.

The **SAML IdP NameID Format**, **SAML IdP SSO URL**, and **SAML IdP X.509 Certificate** fields autofill. If the metadata is incorrect, an error message displays asking you to check the XML.

> [!NOTE]
> The SAML IdP NameID Format field is optional. The default value for this field is `urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress`. The NameID is a unique identifier that matches an end-user across multiple Unqork sessions.
12. (Optional) In the **SAML SP Entity ID** field, enter a value.

> [!NOTE]
> This value must match the value used by the IdP. If you're asked to define the Entity ID, use a value that relates to your configuration. For example, `{environment name and codebase}-{application name}-saml`. The Okta administrator might also have their own preferred Entity ID naming conventions.
13. (Optional) You can leave the default value for the **SAML Callback URL** field unless the Okta app integration uses a different value.
14. Click the **Show Advanced Settings** button.
15. (Optional) Set **Use Signed AuthnRequest** to ![](https://cdn.us.document360.io/15548f06-2fba-434c-b0c1-5df88317dbd7/Images/Documentation/image(43).png?sv=2026-02-06&spr=https&st=2026-11-09T16%3A59%3A10Z&se=2026-11-09T17%3A59%3A10Z&sr=c&sp=r&sig=nYpSjJoHUAR91zAhVTwrHlmx3ZQ9ZMtIIjX0v0nfG%2F4%3D) (**checked**).
16. (Optional) Set **Expect Encrypted Assertions** to ![](https://cdn.us.document360.io/15548f06-2fba-434c-b0c1-5df88317dbd7/Images/Documentation/image(43).png?sv=2026-02-06&spr=https&st=2026-11-09T16%3A59%3A10Z&se=2026-11-09T17%3A59%3A10Z&sr=c&sp=r&sig=nYpSjJoHUAR91zAhVTwrHlmx3ZQ9ZMtIIjX0v0nfG%2F4%3D) (**checked**). The **SAML Certificate*** drop-down displays.

> [!NOTE]
> Creators can either enable **Use Signed AuthnRequest**, **Expect Encrypted Assertions**, or enable both settings depending on their configuration setup.

![](https://cdn.us.document360.io/15548f06-2fba-434c-b0c1-5df88317dbd7/Images/Documentation/SSO_SAML_NewSettings_thumb_0_0.jpg?sv=2026-02-06&spr=https&st=2026-11-09T16%3A59%3A10Z&se=2026-11-09T17%3A59%3A10Z&sr=c&sp=r&sig=nYpSjJoHUAR91zAhVTwrHlmx3ZQ9ZMtIIjX0v0nfG%2F4%3D)
17. From the **SAML Certificate*** drop-down, select the certificate created during the [Create a SAML Certificate](/v1/docs/how-to-using-certificates-with-saml-assertions#create-a-saml-certificate) steps.
18. Click **Next**. The **Attribute Mapping** tab displays.
19. Enter the attribute mapping information for the SSO.

> Learn more about attribute mapping in our [SSO (Single Sign-on) Attribute Mapping](/v1/docs/sso-single-sign-on-attribute-mapping) article.
20. Click **Create SSO**.
21. Test your configuration using the [Testing Your Configuration](/v1/docs/how-to-using-certificates-with-saml-assertions#testing-your-configuration) steps.

## Add a SAML Certificate to an Existing SSO

After creating a SAML Certificate, Creators can edit an existing SSO configuration and add the certificate.

1. At the top right of the Unqork Designer Platform, click **Administration**.
2. Under Environment, select **Single Sign-On (SSO)**.
3. From the left menu, select **Express** or **Designer** depending on the SSO type.
4. From the list, navigate to the SAML SSO you want to edit, then click **Manage**. A drop-down menu displays.
5. Click **Edit**. The SSO configuration's settings modal displays.
6. Click **Configure Protocol**.
7. Navigate to and click the **Show Advanced Settings** button.
8. Set **Use Signed AuthnRequest** to ![](https://cdn.us.document360.io/15548f06-2fba-434c-b0c1-5df88317dbd7/Images/Documentation/image(43).png?sv=2026-02-06&spr=https&st=2026-11-09T16%3A59%3A10Z&se=2026-11-09T17%3A59%3A10Z&sr=c&sp=r&sig=nYpSjJoHUAR91zAhVTwrHlmx3ZQ9ZMtIIjX0v0nfG%2F4%3D) (**checked**).
9. Set **Expect Encrypted Assertions** to ![](https://cdn.us.document360.io/15548f06-2fba-434c-b0c1-5df88317dbd7/Images/Documentation/image(43).png?sv=2026-02-06&spr=https&st=2026-11-09T16%3A59%3A10Z&se=2026-11-09T17%3A59%3A10Z&sr=c&sp=r&sig=nYpSjJoHUAR91zAhVTwrHlmx3ZQ9ZMtIIjX0v0nfG%2F4%3D) (**checked**). The **SAML Certificate*** drop-down displays.

> [!NOTE]
> Creators can either enable **Use Signed AuthnRequest**, **Expect Encrypted Assertions**, or enable both settings depending on their configuration setup.

![](https://cdn.us.document360.io/15548f06-2fba-434c-b0c1-5df88317dbd7/Images/Documentation/SSO_SAML_ExistingSettings_thumb_0_0.jpg?sv=2026-02-06&spr=https&st=2026-11-09T16%3A59%3A10Z&se=2026-11-09T17%3A59%3A10Z&sr=c&sp=r&sig=nYpSjJoHUAR91zAhVTwrHlmx3ZQ9ZMtIIjX0v0nfG%2F4%3D)
10. From the **SAML Certificate*** drop-down, select the certificate created during the [Create a SAML Certificate](/v1/docs/how-to-using-certificates-with-saml-assertions#create-a-saml-certificate) steps.
11. Click **Save**. SSO configuration's settings modal closes.
12. Test your configuration using the [Testing Your Configuration](/v1/docs/how-to-using-certificates-with-saml-assertions#testing-your-configuration) steps.

## Testing Your Configuration

After completing the Unqork side of the setup, test your configuration.

> [!NOTE]
> You'll need a set of test credentials from the Okta administrator. The test user must be assigned to the app integration in Okta, under the Assignments tab.

### Testing an SP-Initiated Flow

From the SSO dashboard, you can preview the Unqork entrypoint and use a set of test credentials from your SSO provider to test the configuration. To test the SP-initiated flow:

1. In the SSO dashboard, find the SSO configuration to preview.
2. Click **Manage**. A drop-down menu displays.
3. From the Manage drop-down, right-click **Preview**.
4. Click **Open Link in Incognito Window**.

> [!TIP]
> By default, the Unqork entrypoint URL uses `123` as the module ID. To test access to an actual module in your application, replace `123` at the end of the URL with your module's module ID.
5. Log in using your test credentials.

If you see an error page, there are issues with your configuration. If you can successfully log in to Unqork, your SAML configuration of Okta as SSO provider is working.

### Testing an IdP-Initiated Flow

To test the IdP-initiated login flow, you'll need the **Embed Link** found in Okta.

1. In Okta, navigate to the **Applications** page.
2. Select your app integration.
3. In the **Embed Link** field, copy the value.

![](https://cdn.us.document360.io/15548f06-2fba-434c-b0c1-5df88317dbd7/Images/Documentation/sso_okta_appEmbedLink_thumb_0_0.jpg?sv=2026-02-06&spr=https&st=2026-11-09T16%3A59%3A10Z&se=2026-11-09T17%3A59%3A10Z&sr=c&sp=r&sig=nYpSjJoHUAR91zAhVTwrHlmx3ZQ9ZMtIIjX0v0nfG%2F4%3D)
4. Open a new Incognito window of your browser.
5. Paste the **Embed Link** into the browser.
6. Log in using your test credentials.

If you see an error page, there are issues with your configuration. If you can successfully log in to Unqork, your SAML configuration of Okta as SSO provider is complete.

### Troubleshooting Tips

Understanding what's causing an error can be a frustrating part of creating a new configuration. One of the most common sources occurs when not using the Express View -specific host value in the **SAML Callback URL** field. By default, new Express SSO configurations use the Express View-specific host value in the SAML Callback URL. However, double-checking the `location` attribute in the SP metadata XML file can confirm it's correct. Also, ensure the SAML Callback URL value exactly matches the **Single Sign-On URL** in Okta, with both values use the Express View-specific host value.

It's useful to view what assertions your application receives from Okta. Assertions are not logged in Service Logs. Instead, you can use Google Chrome extensions, like [SAML Chrome Panel](https://chrome.google.com/webstore/detail/saml-chrome-panel/paijfdbeoenhembfhkhllainmocckace) or [SAML Message Decoder](https://chrome.google.com/webstore/detail/saml-message-decoder/mpabchoaimgbdbbjjieoaeiibojelbhm). Comparing the assertions you receive against the assertions you expect can help with debugging.

Also known as Unqork Users, or Designer Users; is anyone who is inside the Unqork platform.

X.509 certificates are digital documents that represent a user, computer, service, or device. A certificate authority (CA), subordinate CA, or registration authority issues X.509 certificates. Certificates contain the public key of the certificate subject. They don't contain the subject's private key, which must be stored securely.

Security Assertion Markup Language (SAML) is a protocol that allows an identity provider (IdP) to send a user's credentials to a service provider (SP) to verify their identity and grant them access to a service.

Single Sign-On is an authentication scheme that enables users to use one set of login credentials across multiple services.

A modal is a window that appears on top of the content you are currently viewing.

The hexadecimal format (base 16) is a numbering system that uses 16 symbols (0-9 and A-F) to represent values, commonly used in computing for memory addresses, color codes, and binary shorthand.

Extensible Markup Language (XML) is markup language that lets you define and store data in a shareable way.

Express View is how your end-user views your application. Express View also lets you preview your applications to test your configuration and view the styling. This is also the view your end-users will see when interacting with your application. After configuring a module, click Preview in the Module Builder to interact with the module in Express View.