How to: Using Certificates with SAML Assertions

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.

Access the 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:

A static image displaying the New SAML Certification configuration odal.

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.

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.

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.

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.

After creating a SAML Certificate, add it to a SAML SSO Configuration using the Single Sign-On (SSO) Management page.

Select one of the following methods below:

For in-depth details on creating new SSO configurations, view the 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.

This name is used to generate the default SP Entity ID.

6. In the Default Role drop-down, select a role.

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 Inline image displaying a selected radio button. 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.

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.

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 (checked).
16. (Optional) Set Expect Encrypted Assertions to (checked). The SAML Certificate* drop-down displays.

Creators can either enable Use Signed AuthnRequest, Expect Encrypted Assertions, or enable both settings depending on their configuration setup.

A static image displaying an new SAML SSO Configuration's advanced settings.

17. From the SAML Certificate* drop-down, select the certificate created during the 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 article.

20. Click Create SSO.
21. Test your configuration using the Testing Your Configuration steps.

Learn more about creating SSO SAML configurations for Express and Designer by using the guides below:

SSO in Express View (SAML)

SSO in Designer (SAML)

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 (checked).
9. Set Expect Encrypted Assertions to (checked). The SAML Certificate* drop-down displays.

Creators can either enable Use Signed AuthnRequest, Expect Encrypted Assertions, or enable both settings depending on their configuration setup.

A static image displaying an existing SAML SSO Configuration's advanced settings.

10. From the SAML Certificate* drop-down, select the certificate created during the Create a SAML Certificate steps.
11. Click Save. SSO configuration's settings modal closes.
12. Test your configuration using the Testing Your Configuration steps.

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

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.

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.

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.

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 or SAML Message Decoder. Comparing the assertions you receive against the assertions you expect can help with debugging.

Resources