Set up AD FS for BusinessProxy
Prepare federation HTTPS, register an OIDC application, and verify sign-in, permissions and revocation with a pilot group.
1. Prepare the domain and federation server
This example uses corp.example.com for Active Directory, adfs.example.com for federation, and example.com for corporate email. Replace them with your own names. The guide assumes an existing AD DS domain and the Microsoft AD FS profile on Windows Server 2019 or later.
- If a farm is running, verify it and proceed to application registration. For a new farm, use a dedicated domain member server. Set its domain DNS, verify its clock and prepare a group managed service account. Authorize the farm nodes to retrieve the gMSA password, and let the KDS root key take effect and replicate.
- Create the adfs.example.com record. Internal DNS points it at the farm or its load balancer. For external access, publish federation HTTPS through Web Application Proxy or your approved gateway. Employee browsers and BusinessProxy need OIDC over TCP 443. Keep the domain controller on the internal network.
- Import the TLS certificate and private key into Local Computer → Personal. Install the role with Install-WindowsFeature ADFS-Federation -IncludeManagementTools. In the Server Manager wizard, create the first farm and select adfs.example.com, its TLS certificate, the gMSA and the agreed configuration database.
2. Verify TLS and CA trust
For cloud BusinessProxy, use a publicly trusted CA certificate at the public AD FS endpoint. Include adfs.example.com in the SAN, check its validity and confirm the Server Authentication purpose. Serve the intermediate certificates with the HTTPS chain.
- Your organization distributes a private root certificate to managed devices through Group Policy or MDM. In Windows Group Policy, go to Computer Configuration → Policies → Windows Settings → Security Settings → Public Key Policies → Trusted Root Certification Authorities. Distribute the public CA certificate.
- Device trust applies to the browser and other clients on that device. BusinessProxy checks the OIDC issuer on its server. The SSO form cannot add a private CA root to that server’s trust store.
- Configure LDAPS access to private AD separately. Give the public CA certificate or chain to the administrator configuring directory access or Directory Connector. Check the controller DNS name and TLS in the directory preview.
- The HTTPS certificate authenticates the server name. AD FS publishes its token signing keys through JWKS, which BusinessProxy verifies separately. Use the signing-key rotation guide when changing those keys.
3. Check the issuer and signing keys
Run these checks from an employee network and from an external network. The issuer value must match the address you enter in BusinessProxy. Discovery and JWKS must be available over HTTPS without a credential prompt. After saving, use Test connection to verify reachability from BusinessProxy itself.
$Issuer = 'https://adfs.example.com/adfs'
Resolve-DnsName ([uri]$Issuer).DnsSafeHost
Test-NetConnection ([uri]$Issuer).DnsSafeHost -Port 443
$metadata = Invoke-RestMethod ($Issuer + '/.well-known/openid-configuration')
if ($metadata.issuer -cne $Issuer) { throw 'Unexpected issuer' }
$keys = Invoke-RestMethod $metadata.jwks_uri
if (-not $keys.keys) { throw 'The issuer published no signing keys' }
$metadata | Select-Object issuer, authorization_endpoint, token_endpoint, jwks_uri
$keys.keys | Select-Object kid, kty, use4. Register a dedicated OIDC client
In the intended BusinessProxy workspace, open Team → SSO and copy the OIDC callback URL. In AD FS Management, go to Application Groups and create a BusinessProxy application group with the Server application accessing a web API template.
- For the Server application, retain the client ID and enter the copied redirect URI in full, including /api/auth/oidc/callback. Use a separate client ID for each test or production portal.
- Generate a client secret. Store it in your organization’s secrets manager and enter it in the protected BusinessProxy field. AD FS uses a confidential client and authorization code exchange with PKCE S256.
- For corporate claims, add a Web API with a unique identifier such as urn:businessproxy:example:corporate. Give this Web API a display name unique to the registration. Grant your client ID the openid and allatclaims scopes on that resource. Use the application access policy to restrict it to a pilot group. The SSO guide also covers the basic openid profile for already linked users without additional claims.
5. Configure signed claims
Configure issuance rules on the Web API you created for BusinessProxy. Verify the actual short names and values in the pilot sign-in’s ID token in a protected administrative environment.
Import-Module ActiveDirectory
Get-ADGroup -Identity 'APP_BusinessProxy_Pilot' |
Select-Object Name, @{Name='SID'; Expression={$_.SID.Value}}- For first-sign-in provisioning (JIT), issue email from the populated AD mail attribute and set email_verified to true only for addresses the organization vouches for. Restrict the rule to the exact corporate domain. If mail is blank, correct the AD record.
- For groups, register a short claim name such as bp_groups. Emit the SIDs of selected AD groups mapped to BusinessProxy permissions. Look up the SID with Get-ADGroup. If you recreate a group, update the SID in the AD FS rules and the BusinessProxy mapping.
- For the managed directory, issue a separate claim containing the employee’s single SID, for example bp_object_sid. Use its exact short name in the directory import settings.
6. Connect the workspace and verify access
In Team → SSO, select Microsoft AD FS (OIDC). Set the Issuer URL, client ID and client secret. For corporate claims, also enter the AD FS resource, the openid allatclaims scopes and the Groups claim. Save and select Test connection.
- Keep an independent BusinessProxy administrator sign-in. Create a BusinessProxy group, map the AD pilot group SID to it, and grant access to one test resource. Confirm the change with a BusinessProxy passkey or authenticator code.
- To require a group grant for ordinary CMS members, open Security settings → Default access and select Owner only. If you select All members, an ordinary member can also enter through the base role. Owners and administrators have their own BusinessProxy permissions.
- Open the employee sign-in link in a clean browser profile. Verify an allowed user can sign in and an out-of-scope user is denied. For a new user, check JIT or imported employee admission. BusinessProxy grants access to the CMS route. CMS administration requires a local account with the appropriate permissions. If CMS sign-in through BusinessProxy is enabled, the user first links their existing CMS account. CMS roles and second-factor policy still apply after linking.
- Open a protected page. End the test session in BusinessProxy and refresh the same tab. Verify the next protected request is denied. For a lasting removal, also remove the grant and test a new sign-in. If you use the managed directory, verify a successful import accepted the change.
7. Set up the branded portal and enable AD FS sign-in
Select the workspace that owns the portal and its apps. A workspace owner or administrator completes these steps.
- If the portal already has a working HTTPS address, continue with SSO. To create a portal, find Custom domains in workspace settings. Select Add domain, add the verification and routing records shown in the console, and run the DNS check. Once the domain is ready, open its dedicated app. portal address.
- Under Public apps, find the portal address and select Portal appearance. Set the theme, logos, logo background, primary button color and browser tab icon. Choose a white or light gray backing to make a dark logo legible over dark artwork. For an individual app address, open its settings, go to Addresses, and select the Branded portal mode.
- The workspace owner enables publication under Services → Branded portals. Review the price in your wallet currency before confirming. Portals published before the tariff was introduced have a 30-day transition period. When publication ends, the portal address redirects visitors to the standard BusinessProxy app catalog.
- In the same workspace, open Team → SSO. Add or edit a Microsoft AD FS (OIDC) connection, set its status to Active, save it, and select Test connection. Register the callback shown on the SSO page in AD FS. The branded portal address requires no extra callback registration.
- In a clean browser profile, open the portal HTTPS address and select Sign in with AD FS. Enter the domain account password on the AD FS page, return to the portal, and complete BusinessProxy verification if prompted. Verify that an authorized employee can launch an assigned app and an employee without access is denied. End the test session in the dashboard and verify denial in the same tab.
- If the button is missing, check the connection status, Microsoft AD FS (OIDC) profile, workspace and branded URL in a regular browser. If the button is visible but sign-in fails, check the callback and admission rules below.
If a check fails
- The browser shows a certificate error or the issuer check fails. Check internal and external DNS, TCP 443, the SAN, expiration and intermediate certificates. If the browser trusts a private CA, check the trust store of the BusinessProxy installation.
- Test connection passes but real sign-in returns a discovery error. In a self-hosted installation, check routing and CA trust on every replica serving the connection test and sign-in. For cloud installations, give support the failure time and issuer hostname.
- AD FS denies access during or after sign-in. Compare the exact callback, client ID, resource, permitted scopes and pilot group policy. Check AD FS → Admin in Event Viewer. Include the time and event identifier in a support request.
- AD FS returns MSIS7614 when adding a Web API. Check the resource display name across the farm and choose a unique name for this registration. Before retrying, check which objects the first attempt created.
- An employee signed in but cannot reach a resource. Check the signed claim short name, SID, group mapping, resource-specific grant and resource state. For CMS, verify fresh BusinessProxy step-up and check the service status if you selected a paid access method.