Okta

Configure SURF to authenticate and provision users against Okta. This page covers user sign-in via SAML, user and group provisioning via SCIM, admin console SSO, and conditional access.

Before you start

Two separate Okta applications are involved. The Surf Security app from the Okta catalogue handles end user sign-in and provisioning. A second, custom SAML app handles sign-in to the SURF Admin console. They are configured independently, and the admin console one is optional.

Step 1: Configure user authentication with SAML

In Okta

1. Sign in to your Okta Admin tenant and go to Applications.
2. Select Browse App Catalog.
3. Search for Surf Security and select the application.
4. Click Add integration, then Done.
5. Open the Assignments tab and assign the application to the users or groups that should be able to sign in.

In SURF Admin

1. Go to Settings → Integrations.
2. Locate SAML 2.0 and select Add integration.
3. Fill in the SAML values. These come from the Okta application's Sign On tab, under Metadata details.
4. Click Submit.
5. Set the new integration's status to ON.

SURF supports SP-initiated SSO, meaning the sign-in flow starts from SURF rather than from the Okta dashboard.

Step 2: Provision users and groups with SCIM

Optional. SCIM lets Okta manage the SURF user directory automatically instead of users being added by hand.

1. In the Surf Security application in Okta, open the Provisioning tab and click Configure API integration.
2. Tick Enable API integration.
3. In SURF Admin, go to Settings → Additional Setup and copy the company Secret.
4. Paste the company secret into the Okta API Token field.
5. Click Test API Credentials to validate the settings.
6. If the test succeeds, close the dialog and click Save.

Step 3: Configure admin console SSO

Lets administrators sign in to the SURF Admin console with their Okta credentials. This uses a separate, custom Okta application, not the catalogue app from Step 1.

Create the application in Okta

1. In Okta Admin, go to Applications and select Create App Integration.
2. Choose SAML 2.0 and click Next.
3. Name the application, for example SURF Admin Console. A logo can be added from the SURF brand assets.
4. Enter the SAML settings:

1. Click Next, select I'm an Okta customer and this is an internal app, then Finish.
2. Open Assignments and assign the relevant administrators or admin group.
3. Open the Sign On tab, scroll to the SAML 2.0 instructions and click More details. Keep this page open, the next steps copy three values from it.

Exchange the details in SURF Admin

1. Go to Settings → Integrations, locate SAML 2.0 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. Copy the values across:

1. Click Submit.
2. Click the gear icon again and select Update global SSO a second time.
3. Set Enable SSO config to ON.
4. Log out and log back in with SSO to confirm it works.

Step 4: Configure conditional access

Restricts an application so it can only be reached from inside SURF. Traffic is routed through a known proxy address, then Okta is told to deny sign-ins that do not originate from that address.

4.1 Configure the proxy in SURF

1. In SURF Admin, go to Policy management → Proxy Access Management.
2. Under Hosting, choose SURF's proxy or Self hosted proxy. If SURF hosts it, the SURF support team supplies the address.
3. Enter the proxy address including port under Custom Proxy DNS / IP, for example 3.139.215.63:3221, and click Set.
4. Under Affected SaaS URLs, select the applications to route through the proxy.
5. Add anything not in the list under Additional Affected URLs. Include your Okta sign-in domain, for example your-org.okta.com, so the Okta login itself is proxied.
6. Turn Proxy Access ManagementON.

4.2 Define the proxy as a network zone in Okta

1. Sign in to Okta Admin and go to Security → Networks.
2. Select Add IP Zone and give it a recognisable name, for example surf-zone.
3. Under Gateway IPs, enter the SURF proxy address from 4.1.
4. Leave Block access from IPs matching conditions listed in this zone unticked. This zone is used to allow SURF traffic, not to block it.
5. Click Save.

4.3 Create the authentication policy

1. Go to Security → Authentication policies and add a new policy.
2. Assign the policy to the relevant application.
3. Add two rules, both assigned to the relevant group of users:

4.4 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. Okta should block it.

Reference

Troubleshooting

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