Entra ID

Configure SURF to authenticate and authorise users against Microsoft Entra ID (formerly Azure AD). This page covers user sign-in via SAML or OIDC, user and group synchronisation, admin console SSO, and conditional access.

Before you start

Both SAML and OIDC are supported and either is sufficient for user sign-in. SAML is configured through an Entra ID enterprise application; OIDC is configured through an app registration. Group sync and admin SSO both build on the application object you create here, so keep its name to hand.

Step 1: Add the Azure integration in SURF

1. Navigate to SURF Admin portal → Settings → Integrations.
2. Find Azure and select Add integration.
3. In the Domain field, enter login.microsoftonline.com
4. Click Submit.

The Azure integration now appears in the integrations list. Every later step returns to this row and uses the gear icon beside it.

Step 2: Configure user authentication

Complete either Option A or Option B, not both.

Option A: SAML authentication

In SURF Admin

1. Go to Settings → Integrations, click the gear beside the Azure integration and select Update integration.
2. Select SAML.
3. Open the SAML dropdown and download the SURF metadata. Keep the file, you will upload it to Entra ID.

In Entra ID

1. Sign in to portal.azure.com as an administrator.
2. Go to Enterprise applications → New application → Create your own application.
3. Give the application a name and click Create.
4. In the left menu select Single sign-on, then choose SAML.
5. Select Upload metadata file and upload the SURF metadata.
6. Once saved, download the Federation Metadata XML from the SAML signing certificate section.
7. Under Users and groups, assign the groups that should be allowed to sign in.

Back in SURF Admin

1. Return to the Azure integration and upload the Entra ID Federation Metadata XML.
2. Select Submit credentials.

Option B: OIDC authentication

In SURF Admin

1. Go to Settings → Integrations, click the gear beside the Azure integration and select Update integration.
2. Select OIDC. Leave the dialog open, you will return to it with values from Entra ID.

In Entra ID

1. Sign in to portal.azure.com as an administrator.
2. Go to App registrations → New registration.
3. Enter a name, leave Supported account types as Accounts in this organizational directory only unless your tenant requires otherwise, and click Register.
4. On the Overview page, copy the Directory (tenant) ID and the Application (client) ID.
5. Go to Certificates & secrets → New client secret. Enter a description, set an expiry, and click Add.
6. Copy the secret Value immediately. It is not retrievable once you navigate away. Copy the Value, not the Secret ID.

Back in SURF Admin

1. Fill in the integration dialog:

1. Select Submit credentials.

Back in Entra ID

1. In the app registration, go to Authentication → Add a platform → Web.
2. Set the redirect URI to https://prod-backend.surf-admin.link/api/v1/admin/auth/azure-oidc
3. Under Implicit grant and hybrid flows, tick ID tokens.
4. Click Configure.

Step 3: Sync users and groups

Imports Entra ID users and groups into SURF so policies can be applied to existing groups. This is a prerequisite for admin SSO.

1. Open the app registration with the same name as the application created in Step 2.
2. Go to API permissions → Add a permission → Microsoft Graph → Application permissions.
3. Add the following:

1. Grant admin consent for the tenant. Each permission should show Granted in the admin consent column.
2. In SURF Admin, go to Users and Groups → Groups → sync options.
3. Select Azure and the tenant details configured above.
4. Choose the groups to import and confirm.

Step 4: Configure admin console SSO

Lets administrators sign in to the SURF Admin console with their Entra ID credentials. This is configured separately from user authentication and uses a different menu option in SURF.

4.1 Mark the admin group

1. In SURF Admin, sync the admin group from Entra ID following Step 3.
2. When selecting the group, tick both AUTO SYNC and IS ADMIN.

4.2 Create the enterprise application

1. Create an enterprise application configured for SAML authentication following Option A above, but assign the admin group as the group allowed to use the application.
2. Do not use the metadata step from that section. Use 4.3 below instead.

4.3 Exchange metadata using Update global SSO

1. In SURF Admin, go to Settings → Integrations, click the gear beside the Azure integration and select Update global SSO. This is a different menu item from Update integration and is what makes the configuration apply to the admin console.
2. Click Download Metadata.
3. In Entra ID, open the enterprise application from 4.2, go to Single sign-on → SAML, select Upload metadata file and upload the SURF metadata.
4. Download the Federation Metadata XML from Entra ID.
5. Return to the Azure SSO config dialog in SURF Admin and either upload the XML or enter the values manually:

1. Set Enable SSO config to ON.
2. Click Submit.

4.4 Verify

1. Log out of the SURF Admin console.
2. Attempt to log in with an Entra ID account belonging to the admin group.

Step 5: Configure conditional access

Restricts a SaaS application so it can only be reached from inside SURF. Traffic for the application is routed through a known proxy address, then Entra ID is told to block sign-ins that do not originate from that address.

The example below is Microsoft 365. The same pattern applies to any SaaS application.

5.1 Configure the proxy in SURF

1. In SURF Admin, go to Policy management → Proxy Access Management.
2. Configure the proxy:

1. Click Set.
2. Under Affected SaaS URLs, select the applications to route through the proxy.
3. Add anything not in the list under Additional Affected URLs. To cover Entra ID sign-in itself, add login.microsoftonline.com
4. Turn the Proxy Access Management toggle ON.

5.2 Create the conditional access policy in Entra ID

1. In the Azure portal, go to Conditional Access → Named locations and create a named location for the proxy address from 5.1. Name it recognisably, for example Surf Proxy.
2. Go to Conditional Access → Policies → New policy.
3. Under Assignments, select the users or groups and the target applications.
4. Under Grant, select Block access.
5. Under Conditions → Locations, include Any location and exclude the Surf Proxy named location.
6. Set the policy to On and save.

5.3 Verify

1. In the SURF browser, refresh policy.
2. Open the protected application from SURF. It should load.
3. Open the same application from a standard browser. It should be blocked by Entra ID.

Reference

SURF endpoints

Menu paths

Troubleshooting

For anything not covered here, contact the SURF support team.