Redtrust IdP integration with SAML 2.0

Overview

This tutorial shows you how to integrate Redtrust with an Identity Provider (IdP) using Security Assertion Markup Language (SAML) 2.0 to enable single sign-on (SSO). It's intended for developers and IT administrators, and assumes basic familiarity with common IdPs such as Microsoft Entra ID (formerly known as Azure Active Directory) or Google Workspace.

How SAML integration works

SAML 2.0 lets a Service Provider (SP) — Redtrust, in this case — trust an Identity Provider (IdP) to authenticate your users. When a user signs in, the IdP sends the SP a signed assertion: an XML document that vouches for the user's identity and carries attributes such as their email and name.

Setting up that trust is a two-way exchange. You copy some values from your IdP into Redtrust, and some values from Redtrust into your IdP:

Identity Provider

IdP

Your directory — Entra ID, Google Workspace, Okta, or any SAML 2.0 provider. It authenticates your users.

Copy into Redtrust →

• Sign-in URL
• Signing certificate
• Attribute names

• Entity ID
• ACS (Reply) URL
• Signing certificate (optional)

← Copy into your IdP

Redtrust

Service Provider · SP

Trusts the IdP to authenticate users. On login it receives a signed assertion vouching for the user's identity.

Keep this picture in mind as you work: Step 1 registers Redtrust in your IdP, and Step 2 configures Redtrust with your IdP's details. Step 3 is optional and only applies if your IdP requires signed authentication requests.

Each IdP uses slightly different names for the same values. Use this table to translate between them:

What Redtrust needs	Microsoft Entra ID	Google Workspace	Generic SAML term
Sign-in URL	Login URL	SSO URL	SSO / sign-in URL
IdP signing certificate	Certificate (Base64)	Certificate	X.509 signing certificate
User attributes	Attributes & Claims	Attribute mapping	Assertion attributes / claims

You can optionally configure Redtrust to digitally sign SAML authentication requests, which some IdPs require. You can enable this while creating the domain or later by editing the domain settings.

Before you start

Make sure you have:

• Administrator access to Redtrust and permission to create domains in the Access section.
• Administrator access to the IdP you're integrating, with permission to create applications.
• The user attributes (email, name, surname) available in your IdP's directory.

info

If you already have a SAML domain and only want to add signed-request configuration, go to the optional item in Step 2 and then to Step 3.

note

If your IdP requires it, you can download Redtrust's SP metadata from the administration console. Go to Access > Domains and click Export SP metadata in the ⋯ options of your SAML domain.

Step 1: Register Redtrust in your IdP

In this step you tell your IdP about Redtrust by registering it as an application, so the IdP knows where to send authenticated users. Sign in to the relevant console as an administrator and follow the steps for your IdP.

Microsoft Entra ID

1. In the Microsoft Entra admin center, go to Enterprise apps.

2. Select + New application > Create your own application.

3. In the Create your own application panel, enter Redtrust as the app name. Make sure Integrate any other application you don't find in the gallery (Non-gallery) is selected, then click Create.

4. On the app's Overview page, go to the Getting Started section and select Set up single sign on > Get started, then choose SAML as the method. You land on the Set up Single Sign-On with SAML page, organized as a series of numbered panels you work through top to bottom.

5. In the Basic SAML Configuration panel, click Edit (the pencil icon in the panel's top-right corner) and enter these two values:

   Identifier (Entity ID): how the IdP uniquely names Redtrust

   https://YOUR_REDTRUST_IP/YOUR_DOMAIN

   Reply URL (Assertion Consumer Service URL): where the IdP sends its response

   https://YOUR_REDTRUST_IP/Auth/SamlConsumer

   Where:

   • YOUR_REDTRUST_IP is the IP address or host name of your Redtrust server.
   • YOUR_DOMAIN is the domain alias you create in Step 2.

   Click Save.

6. Keep this browser tab open, you will copy several values from it in Step 2.

For the full procedure, see Microsoft's Enable SAML single sign-on for an enterprise application.

Google Workspace

1. In the Google Workspace Admin console, go to Apps > Web and mobile apps.

2. Click Add app and select Add custom SAML app. This opens the custom SAML app setup wizard, which walks you through four pages: App details, Google Identity Provider details, Service provider details, and Attribute mapping.

3. On the App details page, enter the name Redtrust and click Continue.

4. On the Google Identity Provider details page, use Option 2: copy the SSO URL, Entity ID, and certificate. You need these values in Step 2. Click Continue.

5. On the Service provider details page, enter these two values, then click Continue:

   ACS URL: where Google sends its response

   https://YOUR_REDTRUST_IP/Auth/SamlConsumer

   Entity ID: how Google uniquely names Redtrust

   https://YOUR_REDTRUST_IP/YOUR_DOMAIN

   Where:

   • YOUR_REDTRUST_IP is the IP address or host name of your Redtrust server.
   • YOUR_DOMAIN is the domain alias you create in Step 2.

6. On the Attribute mapping page, click Add mapping for each attribute Redtrust needs. For each one, use the Select field menu to choose the Google Directory attribute (for example, Primary email, First name, Last name), then enter the corresponding App attribute name. Note the app attribute names you enter, as you need them in Step 2. Then finish the wizard.

For the full procedure, see Google's Set up your own custom SAML application.

Other IdPs

Redtrust works with any SAML 2.0-compliant IdP. The exact steps depend on your IdP, so consult its documentation. In general:

1. In your IdP, create a new SAML 2.0 application.

2. Register the following Redtrust values as the service provider (SP):

   Entity ID: how the IdP uniquely names Redtrust

   https://YOUR_REDTRUST_IP/YOUR_DOMAIN

   ACS URL (Reply URL): where the IdP sends its response

   https://YOUR_REDTRUST_IP/Auth/SamlConsumer

   Where:

   • YOUR_REDTRUST_IP is the IP address or host name of your Redtrust server.
   • YOUR_DOMAIN is the domain alias you create in Step 2.

3. Configure the IdP to include the email, name, and surname attributes in the assertion, along with a NameID (the unique identifier the IdP uses for the user).

4. From your IdP, obtain the sign-in URL, the signing certificate, and the attribute names. You need them in Step 2.

For some common IdPs, refer to their SAML configuration documentation:

• AD FS — Create a relying party trust.
• Okta — Create a SAML app integration.
• PingOne for Enterprise — Add a SAML application.
• JumpCloud — Create a custom SAML application connector.

Step 2: Create the domain in Redtrust

Now configure Redtrust with the values from your IdP.

1. In Redtrust, go to Access > Domains and click New.
2. In the dialog box:
   1. Add the alias you want to give the domain. The domain can match the users' email domain — the part after the @.
   2. Select SAML 2 as the domain type and click Next to see all configuration options.

The table below maps each Redtrust field to where you find its value in your IdP.

Microsoft Entra ID

3. Using the Entra ID tab you left open in Step 1, fill in each Redtrust field:

   Redtrust field	Where to find it in Entra ID
   Login URL (HTTP-redirect)	Set up Redtrust panel > Login URL.
   IdP X509 certificate (for signature)	SAML Certificates panel > Certificate (Base64). Download the file, open it in a text editor, and copy its contents.
   Email	Attributes & Claims panel > the emailaddress claim.
   Name	Attributes & Claims panel > the givenname claim (the Entra ID user must have a first name configured).
   Surname	Attributes & Claims panel > the surname claim (the Entra ID user must have a surname configured).

4. Fill in the rest of the fields:

   • Domain: The Entra ID domain in which you want to enable SSO.
   • Is it case sensitive?: No
   • ACS by index: No

5. (Optional) Select Signed request if you want to sign SAML authentication requests. Under Certificate source, choose Generate self-signed certificate or Upload PFX/P12 certificate. This is the public part of the signing certificate, and you need it in Step 3. If you generate a self-signed certificate, you download it in the next step.

Google Workspace

3. Using the values you copied from Google in Step 1, fill in each Redtrust field:

   Redtrust field	Where to find it in Google Workspace
   Login URL (HTTP-redirect)	The SSO URL you copied in Step 1.
   IdP X509 certificate (for signature)	The certificate you copied in Step 1.
   Email	The App attribute name you mapped for email on the Attribute mapping page.
   Name	The App attribute name you mapped for first name.
   Surname	The App attribute name you mapped for last name.

4. Fill in the rest of the fields:

   • Domain: The domain in which you want to enable SSO.
   • Is it case sensitive?: No
   • ACS by index: No

Other IdPs

3. Fill in the Redtrust configuration with your IdP's data: the Login URL, the IdP X509 certificate (for signature), and the attribute names for Email, Name, and Surname.

4. Fill in the rest of the fields:

   • Domain: The domain in which you want to enable SSO.
   • Is it case sensitive?: No
   • ACS by index: No

For a description of each field, see the Domain documentation.

Step 3 (Optional): Add signed request configuration

Complete this step only if your IdP requires signed authentication requests, and you selected Signed request in Step 2.

Microsoft Entra ID

1. If you generated a self-signed certificate in Step 2, go to Access > Domains, select the domain you just created, and download the certificate.

2. Back in the Entra ID application, open the Verification certificates (optional) panel and click Edit (the pencil icon).

   1. Select Require verification certificates.

   2. Click Upload certificate, select your certificate, then click Ok and Save.

Google Workspace

info

Google Workspace doesn't support validating signed SAML authentication requests, so you can't enable this option when integrating with Google as the IdP.

Other IdPs

If your IdP requires signed requests, go to Access > Domains, select the domain, download the certificate, and upload it to your IdP's signature verification settings. Refer to your IdP's documentation for the exact steps.

Verify the integration

After configuring both sides, confirm that SSO works end to end. Use a test account that belongs to the configured SAML domain:

1. In a private browser window, open the Redtrust sign-in page and enter the email address of a user in the SAML domain.
2. Redtrust recognizes the domain and redirects you to your IdP. Sign in there.
3. The IdP redirects you back to Redtrust, and you land authenticated.

If you aren't redirected, or authentication fails, see Troubleshooting.

Troubleshooting

Most SAML issues come from a value that doesn't match on both sides. Check these first:

Symptom	Likely cause	What to check
The IdP rejects the request or reports an invalid audience	The Entity ID in the IdP doesn't match Redtrust	Confirm the IdP Identifier (Entity ID) is exactly https://YOUR_REDTRUST_IP/YOUR_DOMAIN, with no trailing slash
Sign-in loops, or the IdP won't return the user	The ACS (Reply) URL is wrong	Confirm the Reply URL is exactly https://YOUR_REDTRUST_IP/Auth/SamlConsumer
Signature validation fails	The IdP signing certificate in Redtrust is wrong or expired	Re-copy the current Certificate (Base64) from the IdP into Redtrust
The user signs in but Redtrust shows a missing name or email	Attribute names don't match the IdP's assertion	Align the Email, Name, and Surname attribute names with those the IdP sends
A time or "response too old" error	Clock skew between the servers	Make sure the IdP and Redtrust server clocks are synchronized (NTP)
Signed-request errors after enabling Signed request	The IdP isn't verifying Redtrust's signing certificate	Complete Step 3, or clear Signed request if your IdP doesn't require it

Summary

In this tutorial, you configured Redtrust as a Service Provider (SP) and integrated it with an Identity Provider (IdP) using SAML 2.0 to enable SSO. You registered Redtrust in the IdP, configured Redtrust to trust the IdP, and verified the sign-in flow. Your users can now authenticate with their existing credentials, improving both security and user experience.

Next steps

• For a description of every SAML domain field, see the Domain documentation.
• To enforce signed SAML requests in Entra ID, see Microsoft's guide on configuring SAML request signature verification.