SAML Setup for Azure AD

Overview

This guide covers configuring SAML single sign-on (SSO) with Microsoft Entra ID (Azure AD) for Aurva PaaS deployments. The setup involves configuring environment variables on the Aurva control plane and creating an enterprise application in Azure.

Aurva Control Plane Setup

Step 1: Configure Gateway Service Environment Variables

Add the following environment variables to the Aurva Gateway service:

SAML_ENTITY_ID: "https://<gateway-api-host>/saml/metadata"
SAML_ACS_URL: "https://<gateway-api-host>/api/saml/response"
SAML_SP_KEY: "-----BEGIN PRIVATE KEY-----  -----END PRIVATE KEY-----\n"
SAML_SP_CERT: "-----BEGIN CERTIFICATE-----  -----END CERTIFICATE-----"

Replace <gateway-api-host> with your actual gateway API hostname.

ALLOWED_CORS_ORIGIN: "https://login.microsoftonline.com"

Step 2: Configure Webapp Service Environment Variables

Add the following environment variables to the Webapp service:

SERVICE_PROVIDER_ENTITY_ID_URL: "https://<gateway-api-host>/saml/metadata"
INTEGRATIONS_ACS_URL: "https://<gateway-api-host>/api/saml/response"

Replace <gateway-api-host> with your actual gateway API hostname.

Generating SAML Certificates

Generate a private key and self-signed certificate using OpenSSL for the SAML_SP_KEY and SAML_SP_CERT environment variables.

Step 1: Generate the Private Key

openssl genpkey -algorithm RSA -out saml_sp_key.pem -pkeyopt rsa_keygen_bits:2048

Step 2: Generate the Self-Signed Certificate

openssl req -new -x509 -key saml_sp_key.pem -out saml_sp_cert.pem -days 365

Use the generated key and certificate as SAML_SP_KEY and SAML_SP_CERT in the gateway environment variables.

Before (multi-line format):

-----BEGIN PRIVATE KEY-----
MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQC5AUPdZaHLhq2Y
yA0sHrJ6D/in2EiIpE0bsWPKotYXNiqOSWJfRrWUfnRAjbKDtb/LlV2jqmzJbdKM
...................
twU6K4rjJnH2PtDK57YdcQs=
-----END PRIVATE KEY-----

After (single-line format for Helm):

-----BEGIN PRIVATE KEY-----\nMIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQC5AUPdZaHLhq2Y\nyA0sHrJ6D/in2EiIpE0bsWPKotYXNiqOSWJfRrWUfnRAjbKDtb/LlV2jqmzJbdKM\n....................\ntwU6K4rjJnH2PtDK57YdcQs=\n-----END PRIVATE KEY-----

Azure AD Configuration

Prerequisites

• Access to the Microsoft Entra ID admin portal with permissions to create and configure enterprise applications
• Access to the Aurva Integration Dashboard to retrieve the Entity ID, ACS URL, and Relay State

Step 1: Create an Enterprise SAML Application

1. Navigate to the Microsoft Entra Admin Center.
2. Create a new enterprise application for SAML integration.

Refer to the official Microsoft documentation for detailed steps.

Step 2: Configure Basic SAML Settings

In the application's Single Sign-On settings, configure the following values:

Example values:

Step 3: Update SAML Configuration in Azure

1. Add the Entity ID and ACS URL in the Azure SAML configuration page.
2. Set the Relay State as specified above.
3. Download the SAML app metadata.xml file from Azure.

Step 4: Assign Users and Groups

Add the appropriate Owners, Users, and Groups to the Azure application. Only assigned users will be able to access Aurva using SAML.

Step 5: Integrate SAML with Aurva

1. Navigate to the Aurva dashboard.
2. Upload the downloaded metadata.xml file.
3. Complete the configuration.

Step 6: Verify the Configuration

Test the SAML integration by logging in through Azure AD to ensure the setup is successful.

Troubleshooting