Manage SCIM Provisioning

Overview

Athennian supports the SCIM 2.0 (System for Cross-domain Identity Management) protocol for automated user and group provisioning. With SCIM, you can connect your identity provider (IdP) -- such as Okta, Microsoft Entra ID (Azure AD), OneLogin, or any SCIM 2.0-compatible provider -- to automatically:

• Create and deactivate user accounts in Athennian
• Update user profile information (name, phone number)
• Assign system roles during provisioning
• Create, update, and archive groups
• Manage group membership

This eliminates manual user management and ensures your Athennian instance stays in sync with your organization's directory.

Availability: Customers with the Enterprise SSO add-on.

Prerequisites

Before configuring SCIM provisioning, ensure the following:

1. Athennian administrator access -- you must have the Administrator role in Athennian to generate SCIM tokens and access the configuration page.
2. SCIM Provisioning feature enabled -- this feature must be enabled on your Athennian instance. If you don't see the "SCIM Provisioning" tab in the Access section, contact your Athennian account team.
3. A SCIM 2.0-compatible identity provider -- your IdP must support outbound SCIM 2.0 provisioning.

Setup

Step 1: Get the SCIM Endpoint URL

1. In Athennian, navigate to the main Access section.
2. Select the SCIM Provisioning tab.
3. Copy the SCIM Endpoint URL displayed on the page. It will look like:

https://<your-domain>/api/scim/v2

Step 2: Generate a Bearer Token

1. On the same SCIM Provisioning page, click Generate Token.
2. Enter a Token Name (required) and an optional Description to help you identify this token later.
3. Click Generate.
4. Important: Copy the token immediately. It is displayed only once and cannot be retrieved later. Store it securely.

Step 3: Configure Your Identity Provider

In your IdP's SCIM provisioning settings:

1. Set the SCIM Endpoint URL (also called "Tenant URL" or "Base URL") to the URL you copied in Step 1.
2. Set the Authentication Method to Bearer Token (also called "OAuth Bearer Token" or "HTTP Header Authentication").
3. Paste the token from Step 2 as the Bearer Token (or "API Token" / "Secret Token").
4. Set the Content-Type to application/scim+json or application/json (both are accepted).

Managing Tokens

• You can generate multiple tokens (e.g., one per IdP or environment). This also allows token rotations without downtime.
• To revoke a token, click Revoke next to it in the token table. All SCIM requests using that token will immediately stop working.
• The token table shows each token's status, who created it, when it was last used, and if revoked, who revoked it and when.

User Attribute Mapping

When configuring user attribute mapping in your IdP, use the following SCIM attributes:

Roles

You can optionally assign a system role to users during provisioning by mapping the roles attribute in your IdP. The role value must match a role name in your Athennian instance (matching is case-insensitive).

Available Built-in Roles

The available built-in role names are:

• administrator
• office-admin
• user
• read-only
• summary-only

If your organization has custom roles enabled, you can also use any custom role name exactly as it appears in Athennian.

Default Behavior

• If no roles attribute is sent, the user is assigned the User role.
• If multiple roles are sent, the entry marked with primary: true is used. Otherwise, the first entry is used.

Editing Roles in Athennian

Roles can also be changed directly in Athennian by an administrator, even for SCIM-provisioned users. Navigate to Access, open the user, and change their role. This is useful when you want to manage role assignments within Athennian rather than through your IdP.

Group Attribute Mapping

Groups created via SCIM are tagged as SCIM-managed. Changes to these groups (name, membership) should be made in your IdP.

Supported Operations

Users

Groups (User-Groups)

Discovery

Standard SCIM discovery endpoints (/ServiceProviderConfig, /Schemas, /ResourceTypes) are available and do not require authentication. Most IdPs use these automatically to detect supported capabilities.

What Is Managed by SCIM vs. In-App

Once a user or group is provisioned via SCIM, some fields are managed by your identity provider and others remain editable in Athennian.

For groups, all changes (name, membership) should be made in your IdP. An Athennian administrator can choose to Unlink from SCIM on a group's detail page to convert it to a locally-managed group.

Pagination and Filtering

Pagination and filtering are supported and are typically handled automatically by your IdP. If you are building a custom SCIM integration:

• Pagination: Use startIndex (1-based, defaults to 1) and count (defaults to 100, maximum 500).
• Filtering: Use the filter query parameter. Supported filter attributes:
  • Users: userName, externalId, name.givenName, name.familyName, emails, phoneNumbers, id, meta.created, meta.lastModified
  • Groups: displayName, externalId, id, meta.created, meta.lastModified

Not supported for filtering: displayName, active, roles and name.formatted on users; members and members.value on groups. These attributes appear in responses but cannot be used as filter criteria.

Deprovisioning

• Users: When a user is removed or deactivated in your IdP, their Athennian account is deactivated. The account is preserved (not permanently deleted), so historical records and audit trails remain intact.
• Groups: When a group is removed in your IdP, it is archived in Athennian.

Troubleshooting

Security

• All SCIM communication must occur over HTTPS.
• Bearer tokens are stored using a one-way hash and cannot be retrieved after creation.
• Tokens can be revoked at any time by an Athennian administrator.
• Each token is associated with a dedicated service account for audit trail purposes.

Need Help?

If you encounter issues not covered in this guide, contact your Athennian account team for assistance.