Skip to main content

ADFS SSO

Set up Active Directory Federation Services (ADFS) as your identity provider for Webrix.

What you'll enter in Webrix​

  • Client ID
  • Client Secret
  • Issuer (e.g., https://adfs.example.com/adfs)
  • Callback URL (read‑only): {gatewayUrl}/api/auth/callback/adfs

Prerequisites​

  • ADFS 2016 or later (required for OIDC support)
  • Administrative access to ADFS Management Console
  • A Webrix account with administrative access

Steps in ADFS​

1. Create an Application Group​

  1. Open ADFS Management Console
  2. Right-click Application Groups → Add Application Group
  3. Enter a name (e.g., "Webrix Integration")
  4. Select template: "Server application accessing a web API"
  5. Click Next

2. Configure Server Application​

  1. Note the Client Identifier (GUID) - this is your Client ID
  2. Add Redirect URI: {gatewayUrl}/api/auth/callback/adfs
    • Replace {gatewayUrl} with your actual Gateway URL (e.g., https://your-org.mcp-s.com)
  3. Click Next

3. Generate Client Secret​

  1. Select "Generate a shared secret"
  2. Copy and save the Client Secret immediately (it won't be shown again)
  3. Click Next

4. Configure Web API​

  1. Identifier: Use the same Client ID from step 2.1
  2. Access Control Policy: Choose your policy (usually "Permit everyone" or your organization's policy)
  3. Click Next

5. Configure Application Permissions​

  1. Check these scopes:
    • openid
    • email
    • profile
  2. Click Next, then Close

6. Configure Claims​

  1. Right-click your new Application Group → Properties
  2. Select the Web API → Edit
  3. Go to Issuance Transform Rules → Add Rule
  4. Choose Send LDAP Attributes as Claims:
    • LDAP Attribute → Outgoing Claim Type:
      • E-Mail-Addresses → email
      • Display-Name → name
      • User-Principal-Name → upn
  5. Click OK to save

7. Verify OIDC Discovery​

Test that OIDC discovery is working by visiting in your browser:

https://adfs.example.com/adfs/.well-known/openid-configuration

You should see a JSON response with endpoints. If you get an error, ADFS may not support OIDC (pre-2016 versions).

Finish in Webrix​

  1. In Admin → Settings → Authentication, choose Provider: ADFS
  2. Enter:
    • Client ID: The GUID from step 2.1
    • Client Secret: The secret from step 3.2
    • Issuer: https://adfs.example.com/adfs (your ADFS domain)
  3. Click Save Changes

Troubleshooting​

"Unable to connect to ADFS"​

  • Verify the issuer URL is correct and accessible
  • Ensure OIDC discovery endpoint returns valid JSON: {issuer}/.well-known/openid-configuration
  • Check firewall rules allow outbound HTTPS connections to your ADFS server

"Invalid claims received"​

  • Verify claims are properly configured in ADFS (step 6)
  • Ensure users have email addresses in Active Directory
  • Check the Issuance Transform Rules include email, name, and upn

Users can't sign in​

  • Verify users are assigned to the Application Group in ADFS
  • Add users to Webrix first via Admin Console → Users → Add User
  • Check that the email addresses match between ADFS and Webrix

Notes​

  • ADFS 2016+ is required for OIDC/OAuth 2.0 support
  • Older ADFS versions only support SAML, which is not compatible with Webrix
  • The issuer URL should end with /adfs (e.g., https://adfs.company.com/adfs)

Contact support​

If you need assistance, contact Webrix support at [email protected] with:

  • Your ADFS version
  • The issuer URL you're using
  • Any error messages from the configuration
  • Screenshots of your ADFS Application Group settings (with secrets redacted)

Docs: https://docs.microsoft.com/en-us/windows-server/identity/ad-fs/development/ad-fs-openid-connect-oauth-concepts