Okta SSO and SCIM setup

Overview

This guide walks an Okta administrator through configuring Okta as the identity provider for a Fencer organization. Okta supports two SSO protocols — choose whichever fits your organization best:

• SAML 2.0 — the traditional enterprise SSO protocol. Follow Part 1A.
• OIDC (OpenID Connect) — a lighter-weight alternative. Follow Part 1B.

Both protocols can be paired with SCIM provisioning (Part 2) to automatically create, update, and deactivate Fencer user accounts from Okta.

Prerequisites

• An Okta administrator account with permission to create applications.
• A Fencer organization administrator role.
• A plan that includes single sign-on and SCIM. Without it, the Single Sign-On and User provisioning (SCIM) sections of Settings > Authentication show Upgrade to unlock.

Part 1A: SAML SSO setup

Step 1: Get the Service Provider details from Fencer

1. In Fencer, navigate to Settings > Authentication and find the Single Sign-On section.

2. Click Configure SSO (or Edit on the SAML 2.0 card if a connection already exists). In the Add SSO connection dialog, keep SAML 2.0 selected as the Protocol.

3. At the top of the form, note the Service Provider Details panel with copyable values:

   • Entity ID — https://app.fencer.dev/accounts/saml/<your-org-uid>/metadata/
   • ACS URL — https://app.fencer.dev/accounts/saml/<your-org-uid>/acs/

   You will paste these into Okta in Step 2. Keep this dialog open — you will return to finish the connection in Step 4.

Step 2: Create the SAML app in Okta

1. In the Okta Admin Console, go to Applications and Resources > Applications > Create App Integration.
2. Select SAML 2.0 and click Next.
3. Name the app Fencer and click Next.
4. Fill out the SAML settings using the values below.

General SAML settings

Okta field	Value
Single sign-on URL	Paste the ACS URL from Fencer
Use this for Recipient URL and Destination URL	Checked
Audience URI (SP Entity ID)	Paste the Entity ID from Fencer
Default RelayState	Leave blank
Name ID format	EmailAddress (Okta defaults to “Unspecified” — change it)
Application username	Email

Show Advanced Settings

Okta field	Value
Response	Signed
Assertion Signature	Signed
Signature Algorithm	RSA-SHA256
Digest Algorithm	SHA256
Assertion Encryption	Unencrypted

Caution

Verify that both the Signature Algorithm and Digest Algorithm are set to their SHA-256 variants. Fencer requires SHA-256 — if either is set to SHA-1, every login will fail with a digest mismatch error.

Step 3: Map SAML attributes in Okta

Still on the Configure SAML page, scroll down to the Attribute Statements (optional) section. Okta offers two attribute-mapping modes — use the legacy format (the default when creating a new SAML app). If you see a newer “attribute mappings” interface, switch to legacy mode by clicking Switch to legacy attribute statements at the bottom of the section.

Add the following mappings:

Name	Name format	Value
urn:oid:0.9.2342.19200300.100.1.3	URI Reference	user.email
urn:oid:2.5.4.42	URI Reference	user.firstName
urn:oid:2.5.4.4	URI Reference	user.lastName
https://app.fencer.dev/SAML/Attributes/role (optional)	URI Reference	appuser.fencerRole

Add the role row only if you want to manage Fencer roles from Okta; it needs the fencerRole app attribute from Manage Fencer roles from Okta.

Leave the Group Attribute Statements section empty — Fencer does not use SAML group assertions.

Click Next, select I’m an Okta customer adding an internal app, and click Finish.

Note

These OID-format attribute names (urn:oid:...) are standard LDAP attribute identifiers that Fencer recognizes. Do not use Okta’s friendly names (e.g. email, firstName) — Fencer will not map them correctly.

Step 4: Finish the connection on the Fencer side

1. In Okta, go to the Sign On tab of the Fencer app.
2. Copy the Metadata URL (under “SAML Signing Certificates”, click Actions > View IdP metadata and copy the URL from your browser’s address bar). Also copy the entityID value at the top of that metadata page (it looks like http://www.okta.com/exk…).
3. Return to the Fencer Add SSO connection dialog and keep IdP Configuration Method on Metadata URL.
4. Paste the metadata URL into IdP Metadata URL and the entityID into IdP Entity ID.
5. Leave Reject IdP-initiated SSO on if your users start from Fencer’s login page. Turn it off if they launch Fencer from the Okta dashboard tile.
6. Under Provisioning, keep Just-in-Time provisioning on to let users who are new to Fencer join with the Default role for new users (Administrator, Team Member, Read Only, or a custom role), or turn it off to admit only existing members (invited, or provisioned by SCIM in Part 2). Optionally, restrict it to specific Allowed email domains.
7. Check Enable SSO, leave Enforce SSO off until you have tested, and click Save Configuration.
8. On the connection card, click Test Connection. Fencer redirects you through Okta. On success, you return to Settings > Authentication with a confirmation banner. On failure, Fencer shows an error page with a diagnostic of what went wrong and a reference ID (for example sso-1a2b3c4d). Share this ID with support@fencer.dev if you need help resolving the issue.

Note

The diagnostic details are only shown during the test flow. Regular sign-in failures show only the reference ID, to avoid leaking configuration details. Test Connection appears once the connection is enabled.

After testing, assign users or groups to the Fencer app in Okta’s Assignments tab so they can sign in.

Manage Fencer roles from Okta

Fencer reads each user’s role from the https://app.fencer.dev/SAML/Attributes/role attribute. In Okta, the simplest way to fill it is an app attribute that you set when you assign a group to the Fencer app:

1. Go to Directory > Profile Editor and open the Fencer app’s user profile.

2. Click Add Attribute and create:

   Field	Value
   Data type	string
   Display name	Fencer role
   Variable name	fencerRole
   Enum	Checked, with the values admin, member and read_only, plus the slug of any custom role you want to grant
   Attribute type	Group, so a group assignment can set it

3. Back on the Fencer app, add the role attribute statement from Step 3 with the value appuser.fencerRole.

4. On the Assignments tab, assign each group and pick its Fencer role — for example your security team as admin and engineering as member. When a user is in more than one assigned group, Okta uses the value from the group with the highest priority; you can reorder groups on the same tab.

At each sign-in Fencer sets the user’s role to the value Okta sends. Moving someone to another group in Okta changes their Fencer role the next time they sign in. See The role attribute for the accepted values and the full rules.

Continue to Part 2 if you also want automated user provisioning, or skip to Linking existing users to SSO.

---

Part 1B: OIDC SSO setup

Use this section if you prefer OpenID Connect over SAML. If you already completed Part 1A, skip to Part 2.

Step 1: Start the connection on the Fencer side

1. In Fencer, navigate to Settings > Authentication and find the Single Sign-On section.
2. Click Configure SSO (or Add OpenID Connect connection if you already have a SAML connection). In the Add SSO connection dialog, select OpenID Connect as the Protocol.
3. Copy the Redirect URI shown at the top of the form. You will paste it into Okta in Step 2.

Keep this dialog open. You will return to it in Step 3.

Step 2: Create the OIDC app in Okta

1. In the Okta Admin Console, go to Applications and Resources > Applications > Create App Integration.
2. Select OIDC - OpenID Connect, then choose Web Application and click Next.
3. Name the app Fencer.
4. Fill out the settings using the values below.

Okta field	Value
Grant type	Authorization Code (checked by default)
Sign-in redirect URIs	https://app.fencer.dev/accounts/oidc/oidc-<your-org-uid>/login/callback/
Sign-out redirect URIs	Leave blank or remove the default
Controlled access	Choose who can access the app (e.g. Allow everyone in your organization)

Caution

The sign-in redirect URI must match exactly, including the trailing slash. Copy it from the Fencer connection form; <your-org-uid> is your Organization ID (shown on Settings > Organization, starting with org_). If the URI does not match, Okta will reject the authentication callback with an “Invalid redirect_uri” error.

5. Click Save.
6. On the app’s General tab, note the Client ID and Client Secret.
7. Note your Okta domain (e.g. your-company.okta.com) — this is used to construct the Discovery URL.

Step 3: Finish the connection on the Fencer side

1. Return to the Fencer Add SSO connection dialog.

2. In the OIDC Discovery URL field, enter your Okta issuer URL. Use either:

   • Org authorization server: https://<your-okta-domain> (simpler, pre-configured)
   • Custom authorization server: https://<your-okta-domain>/oauth2/default (more flexible — use this if you have customized scopes or claims)

   Fencer appends /.well-known/openid-configuration automatically to resolve the endpoints.

3. Paste the Client ID and Client Secret from Step 2.

4. Under Provisioning, keep Just-in-Time provisioning on to let users who are new to Fencer join with the Default role for new users (Administrator, Team Member, Read Only, or a custom role), or turn it off to admit only existing members. Optionally, restrict it to specific Allowed email domains.

5. Check Enable SSO, leave Enforce SSO off until you have tested, and click Save Configuration.

6. On the connection card, click Test Connection. Fencer redirects you through Okta. On success, you return to Settings > Authentication with a confirmation banner.

Note

If you are using a custom authorization server instead of the default, replace /oauth2/default with your custom server’s issuer URI (e.g. /oauth2/<server-id>).

After testing, assign users or groups to the Fencer app in Okta’s Assignments tab.

To manage Fencer roles from Okta over OIDC, create the fencerRole app attribute described in Manage Fencer roles from Okta, then add a role claim with the value appuser.fencerRole to the ID token. Custom claims need a custom authorization server (Security > API > Authorization Servers > default > Claims), so use the https://<your-okta-domain>/oauth2/default Discovery URL from Step 3. The org authorization server cannot add custom claims.

---

Linking existing users to SSO

After enabling SSO (SAML or OIDC), existing users who were created before SSO was configured need to link their accounts. Fencer does not automatically bind SSO identities to existing accounts by email — each user must explicitly link their SSO identity once.

• For users: A Link your account to SSO banner appears in Fencer for unlinked users. While signed in with their usual method (password or social login), the user clicks Link SSO Account, confirms on the next page, and signs in with Okta. Once linked, only an administrator can unlink the SSO identity.
• For admins: The Members tab of Admin > Team shows each user’s SSO link status next to their status. Admins can send a reminder email to a user who has not linked yet with Send SSO Linking Reminder in the member’s actions menu.
• New users provisioned via SCIM or created through JIT (just-in-time) provisioning are linked automatically — no action needed.

Caution

Until a user links their SSO identity, they cannot sign in through SSO — even if their email matches. This is a security measure to prevent unauthorized account binding.

Part 2: SCIM provisioning setup

Okta provisions Fencer accounts using a SCIM 2.0 bearer token. You generate the token in Fencer, then paste it into Okta’s provisioning settings.

Step 1: Generate a SCIM token in Fencer

1. In Fencer, navigate to Settings > Authentication and find the User provisioning (SCIM) section.
2. Click Enable SCIM.
3. In the Enable SCIM provisioning dialog, choose the Default role for provisioned users and click Enable SCIM.
4. Fencer displays the SCIM Bearer Token once. Copy it now — you will not be able to see it again. If you lose it, you can rotate to a new token from the same section.
5. Note the SCIM Base URL shown below the token: https://app.fencer.dev/scim/v2. Click Done when you have copied both.

Step 2: Configure Okta’s SCIM provisioning

1. In the Okta Admin Console, open the Fencer app and go to the Provisioning tab.
2. Click Configure API Integration and check Enable API Integration.
3. Fill in the settings below.

Okta field	Value
SCIM 2.0 Base Url	https://app.fencer.dev/scim/v2
Unique identifier field for users	userName
Authentication Mode	HTTP Header
Authorization / Bearer token	Paste the token from Step 1

4. Click Test API Credentials to verify the connection. If the test passes, click Save.
5. Under Provisioning > To App, click Edit and enable the actions you need:

Okta provisioning action	Recommended	Notes
Create Users	Enabled	Provisions new users in Fencer
Update User Attributes	Enabled	Keeps name and profile fields in sync
Deactivate Users	Enabled	Revokes access when users are unassigned or deactivated

To manage Fencer roles by Okta group, also check Push Groups under the app’s Provisioning > Integration settings. See Manage Fencer roles with groups.

Note

Okta uses PATCH to deactivate and reactivate users (active=true/false), and PUT to update profile attributes. Both operations are supported by Fencer.

Step 3: Configure attribute mapping

In Provisioning > To App > Attribute Mappings, verify the following mappings exist. Okta typically sets these up automatically:

Okta attribute	Maps to SCIM attribute	Required
userName	userName	Yes
givenName	name.givenName	No
familyName	name.familyName	No
displayName	displayName	No
email	emails[0].value	No

To manage Fencer roles with an attribute instead of groups, the Fencer app’s fencerRole attribute from Manage Fencer roles from Okta has to reach Fencer as its SCIM role attribute. In Directory > Profile Editor, open the Fencer app’s user profile, edit fencerRole and set:

Field	Value
External name	role
External namespace	urn:ietf:params:scim:schemas:extension:fencer:2.0:User

Okta only shows these two fields once the API integration from Step 2 is enabled. Because fencerRole is an app attribute, it needs no mapping from the Okta user profile: the value set on each group assignment is pushed as it is. With Update User Attributes enabled, moving someone to a group with a different Fencer role updates their role in Fencer at the next push, without waiting for them to sign in. See The SCIM role attribute for the full rules.

Caution

Do not map name.formatted. Fencer does not return that attribute, and mapping it can cause Okta to flag every synced user as having missing data.

Manage Fencer roles with groups

The recommended way to manage Fencer roles over SCIM is to push one Okta group per role:

1. In Okta, create a group for each Fencer role you want to grant, named after the role’s name or value — for example Administrator, Read Only and Security Lead. See SCIM role groups for the accepted names. Everyone in no role group gets the SCIM Default Role, so you don’t need a group for that role.
2. Assign the groups to the Fencer app, so their members are provisioned.
3. On the Fencer app’s Push Groups tab, click Push Groups and push the Administrator group first, with every Fencer administrator in it. Once any role group exists, everyone outside the role groups drops to the default role, so an administrator missing from it loses access to admin settings.
4. Push the remaining role groups.

Moving someone between role groups in Okta changes their Fencer role at the next push. Keep each user in one role group: someone in several keeps their current role. Use groups or the fencerRole attribute, not both: if you also set fencerRole for a user, it wins over their groups, and once SCIM sets a user’s role, the SAML/OIDC role attribute is ignored for them. See SCIM role groups for the full rules.

What Okta can sync

• Create user — Okta adds a new user to your Fencer organization. The user is immediately active and can sign in through SSO. If the user was previously deactivated, this reactivates the existing account instead of failing.
• Update user — Name, other profile fields and the Fencer role are kept in sync via PUT.
• Deactivate user — Unassigning or deactivating the user in Okta removes them from your Fencer organization. The SCIM mapping is preserved so the user can be reactivated later.
• Reactivate user — Re-assigning the user in Okta restores their Fencer membership.
• Push groups — Pushed groups named after a Fencer role value set their members’ role.
• Delete user — Removes the user from your Fencer organization and deletes their SCIM mapping. After a delete, the user cannot be reactivated via PATCH — Okta must re-provision them as a new user.

The following SCIM features are not supported by Fencer:

• Sort, ETag, bulk operations, or password sync.

Token rotation

If your bearer token is compromised or you want to rotate credentials:

1. In Fencer, navigate to Settings > Authentication and find User provisioning (SCIM).
2. Click Rotate Token.
3. Copy the new token immediately — the old one stops working as soon as you rotate.
4. In Okta, go to Provisioning > API Integration > Edit, paste the new token, and save.

Troubleshooting

• “Invalid SAML response” or digest mismatch errors. Open the Fencer app in Okta, go to General > SAML Settings > Edit, click Show Advanced Settings, and verify that both the Signature Algorithm and Digest Algorithm are set to their SHA-256 variants.

• “Invalid redirect_uri” error during OIDC login. The sign-in redirect URI in Okta does not match what Fencer expects. Verify the URI is exactly https://app.fencer.dev/accounts/oidc/oidc-<your-org-uid>/login/callback/ — including the trailing slash and the oidc- prefix before your Organization ID.

• “Client not found” or unknown service provider errors. The ACS URL or Entity ID in Okta does not match what Fencer expects. Confirm that both URLs include your organization’s UID exactly as shown under Service Provider Details in Fencer.

• “401 Unauthorized” on SCIM API Credentials test. The bearer token is wrong or expired. Rotate the token in Fencer and paste the new value into Okta’s provisioning settings.

• Synced users appear as having missing data in Okta. You probably mapped name.formatted in the attribute mappings. Remove it — Fencer does not return that field.

• “Email domain not allowed for SSO” when a user tries to sign in. The connection has an Allowed email domains restriction that excludes the user’s domain. Either add the domain to the allow list, or pre-provision the user via SCIM so JIT is bypassed.

• A user deactivated in Okta can still sign in to Fencer. Confirm that Deactivate Users is enabled in Okta’s Provisioning > To App settings. Without this, Okta does not send the SCIM PATCH to deactivate the account.

• “SSO identifier does not match a linked account.” The user exists in Fencer but has not linked their SSO identity. They need to complete the SSO linking flow — a Link your account to SSO banner guides them through it. Admins can also send a linking reminder from Admin > Team.

• A SAML sign-in or test shows a reference ID (e.g. sso-1a2b3c4d). Note this ID and share it with support@fencer.dev along with a description of what you configured. The ID helps the support team locate the exact failure in the logs.

Related pages

• SSO and Authentication
• General SAML & SCIM setup
• General OIDC setup
• Team and Member Management
• Roles and Permissions