SAML SSO with Microsoft Entra ID (Azure AD)¶

Step-by-step guide to integrate Faraday's SAML SSO with Microsoft Entra ID (formerly Azure Active Directory).

Prerequisites: Faraday commercial edition, Microsoft Azure account with permission to manage Enterprise Applications. See See SAML for general SAML configuration reference.

Configuration Summary¶

Replace <domain> with your Faraday server's FQDN throughout.

Step-by-Step Setup¶

Step 1 — Access Azure Portal¶

1. Navigate to the Microsoft Azure Portal.
2. Sign in with your admin account.

Step 2 — Create an Enterprise Application¶

1. Navigate to Enterprise Applications.
2. Click New Application.
3. Click Create your own application.

Step 3 — Configure Application Type¶

1. In the What's the name of your app? field, enter Faraday.
2. Select Integrate any other application you don't find in the gallery (Non-gallery).
3. Click Create.

Step 4 — Enable SAML Sign-On¶

1. On your new application page, go to Single sign-on.
2. Click the SAML button to select SAML-based sign-on.

Step 5 — Configure Basic SAML Settings¶

1. Click Edit in the Basic SAML Configuration section.

2. Enter the following:

   Field	Value
   Identifier (Entity ID)	https://<domain>/_api/saml/metadata.xml
   Reply URL (Assertion Consumer Service URL)	https://<domain>/_api/saml/acs

3. Click Save.

Step 6 — Configure User Attributes & Claims (Optional)¶

By default, Azure sends the User Principal Name (UPN) as the NameID claim. To customize which attribute is sent as the username:

1. Click Edit in the Attributes & Claims section.
2. Review or modify the Unique User Identifier (Name ID) claim.
3. Add additional claims if needed (e.g., email, groups).

Common claim configurations:

Step 7 — Download the SAML Certificate¶

1. In the SAML Certificates section, find Certificate (Base64).
2. Click Download to save the certificate file.

Step 8 — Copy IdP Configuration Values¶

From the Set up Faraday section, copy:

Step 9 — Assign Users and Groups¶

1. Go to Users and groups in your application settings.
2. Click Add user/group.
3. Select the users or groups who should have access to Faraday.
4. Click Assign.

Step 10 — Generate SP Certificates¶

On your Faraday server, generate the Service Provider certificate pair:

openssl req -newkey rsa:2048 -nodes -keyout key.pem -x509 -days 1825 -out certificate.pem

• certificate.pem → SP Certificate in Faraday settings
• key.pem → SP Private Key in Faraday settings

Step 11 — Configure Faraday¶

Apply the settings via CLI:

faraday-manage settings -a update saml

Fill in the prompts:

Alternatively, configure via the Web UI at Preferences → Authentication → SAML.

Step 12 — Restart Faraday¶

systemctl restart faraday-server

Step 13 — Test the Integration¶

1. Open the Faraday login page.
2. Click the SSO button labeled with your display_name.
3. Authenticate with your Microsoft credentials.
4. Verify you are redirected back to Faraday with an active session.

Attribute Mapping¶

Microsoft Entra ID (Azure AD) sends SAML assertions with claims. The attribute_identifier setting tells Faraday which claim to use as the username.

Default Claims¶

Azure AD includes these claims by default:

Group Claims (Optional)¶

To enable group-based role mapping:

1. In Attributes & Claims, click Add a group claim.
2. Select Security groups (or the appropriate option).
3. Under Source attribute, select Group ID or Display Name.
4. Set admin_group in Faraday to match the group ID or display name for admin users.

Troubleshooting¶

Verifying the SAML Response¶

Azure provides a Test button on the Single sign-on page. Use it to:

1. Click Test in the Azure SAML configuration.
2. Choose Sign in as current user or Sign in as someone else.
3. Review the test results for any errors in the assertion.