SCIM 2.0 Schema: Users, Groups, Extensions and Mapping

The SCIM 2.0 schema is the set of attribute definitions that describes users, groups and other resources in JSON, so that an identity provider and a cloud application can exchange them. It is defined in RFC 7643. The transport rules (HTTP methods, filtering, discovery) are defined separately in RFC 7644. This article covers the core User and Group schemas, the enterprise extension, custom attributes, and how to map attributes between a directory and a destination app without breaking provisioning.

TL;DR

• SCIM 2.0 defines a core User schema, a core Group schema and an Enterprise User extension. Each is identified by a URN in the schemas array of every resource.
• Every attribute carries metadata: type, cardinality, required, mutability, returnability, uniqueness and case sensitivity. Matching JSON property names is not enough. You must also respect these rules.
• Most compatibility problems come from extensions and destination-specific constraints, not from the core URN. Use /Schemas and /ResourceTypes to discover what a service provider supports.
• Group membership is written through the Group resource's members attribute. The User groups attribute is read-only.
• Keep an explicit mapping per destination and test it before you enable provisioning.

Table of Contents

• What the SCIM 2.0 schema is
• The core User schema
• Attribute characteristics
• The enterprise user extension
• The core Group schema
• Custom attributes and vendor extensions
• Discovering what a service actually supports
• Attribute mapping between a directory and an app
• Our perspective
• Syncing Google Workspace to SCIM apps with AnySCIM
• FAQ
• Sources

What the SCIM 2.0 schema is

A SCIM schema is a collection of attribute definitions that describe the contents of a whole resource or part of one. Oracle's schema overview uses the core User URN as its example. The design separates attribute meaning from transport. That is why SCIM can connect different cloud domains.

It is not an XML-Schema-style validator. The receiving service evaluates each attribute against the schema it supports. A SCIM client therefore has to discover and test the target application's actual contract. It cannot assume the destination implements all of RFC 7643.

A SCIM resource is a JSON document. According to RFC 7644, it lists its applicable schemas in a schemas array, and payloads use the application/scim+json media type.

A minimal user looks like this:

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
  "userName": "jane.doe@example.com",
  "name": { "givenName": "Jane", "familyName": "Doe" },
  "emails": [{ "value": "jane.doe@example.com", "type": "work", "primary": true }],
  "active": true
}

The core User schema

The core User schema URI is urn:ietf:params:scim:schemas:core:2.0:User. RFC 7643 requires every User to contain a non-empty userName that is unique within the service provider. The userName is case-insensitive.

The core User attributes are:

• Identity: id, externalId, userName
• Name and display: name, displayName, nickName, profileUrl
• Profile: title, userType, preferredLanguage, locale, timezone
• State and credentials: active, password
• Contact data: emails, phoneNumbers, ims, photos, addresses
• Access data: groups, entitlements, roles, x509Certificates
• Metadata: meta

Each provider supports its own subset of this list. A provider that ignores nickName or ims is still a valid SCIM service.

Identifiers: id, externalId and userName

Three identifiers cause most early confusion:

• id is assigned by the service provider. The client never sets it.
• externalId is the identifier the client uses for the same resource in its own system. For a Google Workspace source, the stable user ID is a better candidate than the primary email, because the email can change.
• userName is what the destination uses to identify the user at sign-in and for uniqueness checks. It is often the email address.

If you map userName to a value that can change, such as a renamed mailbox, you risk duplicate or orphaned accounts in the destination. Anchor matching on externalId where the destination supports it.

Attribute characteristics

Every SCIM attribute is defined by more than a name. According to RFC 7643 and Oracle's documentation, each attribute carries these properties:

Complex attributes contain sub-attributes. name is complex, with givenName and familyName. Multi-valued attributes such as emails hold a list of values or complex objects, usually with type and primary sub-attributes.

These properties are why interoperability depends on more than JSON property names. A client that sends a value for a readOnly attribute, or a second primary email to a service that accepts one, gets an error or a silently ignored value.

The enterprise user extension

The Enterprise User extension URI is urn:ietf:params:scim:schemas:extension:enterprise:2.0:User. RFC 7643 defines these attributes: employeeNumber, costCenter, organization, division, department and manager.

The manager value normally identifies another SCIM User resource. This means the manager must usually exist in the destination before the report can reference them. Order of provisioning can therefore matter.

An extension is declared in the schemas array and its attributes sit under the extension URI as a key:

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User",
    "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"
  ],
  "userName": "jane.doe@example.com",
  "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
    "department": "Finance",
    "costCenter": "CC-1042",
    "manager": { "value": "2819c223-7f76-453a-919d-413861904646" }
  }
}

This namespacing lets a client tell core fields from enterprise or vendor-specific fields without renaming the core schema. An extension can be required or optional for a given resource type.

The core Group schema

The core Group schema URI is urn:ietf:params:scim:schemas:core:2.0:Group. According to RFC 7643, a Group requires displayName and supports multi-valued members entries that identify users or groups.

Each member entry uses value for the target resource's id. It may also include $ref, type and display.

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
  "displayName": "Engineering",
  "members": [
    { "value": "2819c223-7f76-453a-919d-413861904646", "type": "User" }
  ]
}

Membership is written on the group

The groups attribute on a User is read-only. To manage membership, provision the Group resource and update its members attribute. Do not expect a standards-compliant service to accept membership changes through a user's groups array.

This has a practical consequence for sync order. Create users first, capture the id the destination returns, then create or update groups with those IDs in members. Group membership removal for a departed user is a change to the Group, not to the User.

Custom attributes and vendor extensions

When the core and enterprise schemas do not hold a field you need, such as a badge number or a data-residency flag, the SCIM model allows additional schema extensions. A vendor defines its own URN, adds it to schemas, and places its attributes under that URN in the resource.

Three rules keep custom attributes safe:

1. Do not rename core attributes. Put new data in a namespaced extension, as the specification intends.
2. Read the vendor's schema before sending. The destination decides which extension URNs and attributes it accepts. Unknown attributes may be rejected or dropped.
3. Respect the attribute metadata. An immutable custom attribute cannot be changed after creation. A writeOnly one will not come back in a GET, so you cannot verify it by reading.

Schema compatibility problems usually occur in extensions and attribute constraints, not in the core URN. Providers may support only a subset of RFC 7643, add platform-specific cardinality or value restrictions, and expose extra namespaces.

Discovering what a service actually supports

RFC 7644 defines three discovery endpoints:

• GET /ServiceProviderConfig reports supported features such as PATCH, filtering, sorting and bulk. Bulk support is optional, so check it rather than assuming it.
• GET /ResourceTypes lists the resource types and which schema extensions each uses.
• GET /Schemas returns the schema definitions, including attributes and their metadata.

A request looks like this, as shown in the scim.dev API examples:

GET /scim/v2/Schemas HTTP/1.1
Host: api.example.com
Authorization: Bearer YOUR_TOKEN

The ResourceType and Schema resources are read-only. You cannot change a provider's schema through SCIM. Not every provider exposes these endpoints in full, so vendor documentation remains the fallback. For enterprise provisioning, schema discovery plus a tested compatibility profile is safer than treating RFC 7643 as a guarantee that every field is accepted.

Attribute mapping between a directory and an app

Attribute mapping is the step where each source field, such as a Google Workspace user property, is assigned to a SCIM attribute in the destination. Good mapping is explicit, per destination, and tested.

Why a universal mapping fails

Microsoft Entra's SCIM documentation shows how standard attributes map to directory properties with service-specific restrictions. Work email may be limited to one primary value. Work addresses may be limited to one value. Password can be write-only and creation-only in applicable scenarios. Its enterprise extension mapping covers costCenter, department, division, employeeNumber, manager.value and organization.

These examples show that an attribute can exist in SCIM and still carry limits at the destination. A single mapping reused across every app will eventually send something one of them rejects.

A mapping checklist

1. List required attributes first. userName for users, displayName for groups, plus anything the vendor marks required.
2. Choose a stable matching key. Map externalId to an immutable source ID where supported.
3. Map multi-valued attributes deliberately. Decide which email is primary and which type values the destination accepts.
4. Map extension fields under the correct URN. Confirm the URN in the vendor's /Schemas output or documentation.
5. Skip attributes the destination marks read-only. Do not map into them.
6. Define behavior for empty values. Decide whether a blank source field clears the destination value or is omitted.
7. Test with a small scope. Run a dry-run or a pilot group before enabling the full directory.

Attribute normalization

Normalization means converting source values into the form the destination expects before sending. Common cases:

• Case: userName is case-insensitive, but other strings may be caseExact. Lowercase emails consistently so comparisons do not produce duplicates.
• Format: phone numbers, locale codes (en-US) and time zone names should follow the destination's accepted format.
• Cardinality: collapse several source emails into one primary value when the destination allows only one.
• Type: send booleans as JSON booleans, not strings such as "true". active is a boolean.
• References: resolve manager to the destination's user id, not to an email or a name.

Normalization rules belong in the mapping configuration, documented per destination, so a later change in one app does not alter another.

Our perspective

We build provisioning from Google Workspace to SCIM 2.0 apps, and the same pattern repeats. Teams assume the standard guarantees compatibility, then find that each vendor implements a different subset. The core URN is rarely the problem. The problems are extension attributes, single-value restrictions and group handling.

Three principles follow from that:

• Treat the source as read-only. A sync tool that only reads from Google Workspace cannot damage the directory it reads. That limits the blast radius of a mapping mistake to the destination app.
• Keep an audit trail. When a field is rejected or a user is deactivated, you need a record of what was sent and when. Exportable logs make compliance reviews and troubleshooting shorter.
• Map per destination. Group and attribute mapping should be configurable for each app, including custom SCIM endpoints, without writing scripts.

Schema knowledge pays off most when you can test a mapping quickly. Connecting a new vendor should take a short, repeatable process, not a scripting project.

— Nicolas

Syncing Google Workspace to SCIM apps with AnySCIM

If your source of truth is Google Workspace and your destination speaks SCIM 2.0, AnySCIM handles the schema work described above. It syncs users and groups in real time, reads from Google Workspace with read-only access, supports customizable group and attribute mapping, offers preconfigured integration templates, and connects to custom SCIM endpoints without scripts. Detailed audit logs are included.

You can start with a 14-day free trial. Published plans on the pricing page are Startup at $49.99 per month or $249.99 per year, and Scale at $199.99 per month or $999.99 per year. Enterprise pricing is not published.

FAQ

What is the difference between the SCIM core schema and the enterprise extension?

The core schema defines the base User and Group attributes, such as userName, emails and displayName. The enterprise extension adds employeeNumber, costCenter, organization, division, department and manager. It is declared separately in the schemas array and its attributes sit under its own URN.

Can I add custom attributes to a SCIM resource?

Yes, through a schema extension with its own URN, added to schemas and placed as a namespaced object in the resource. The destination decides which extensions it accepts, so check its /Schemas output or documentation first. Do not rename or repurpose core attributes.

How do I add a user to a group in SCIM?

Update the Group resource's members attribute with the user's id. The groups attribute on the User is read-only, so a compliant service will not accept membership changes there. Create the user first so you have the id to reference.

How do I find out which attributes an application supports?

Call GET /Schemas, GET /ResourceTypes and GET /ServiceProviderConfig if the provider exposes them. These endpoints are defined in RFC 7644. If they are missing or incomplete, rely on the vendor's SCIM documentation and test with a small pilot group.

Sources

• RFC 7643: SCIM Core Schema
• RFC 7644: SCIM Protocol
• Microsoft Entra ID SCIM API schema documentation
• Oracle: SCIM Schema Overview
• SCIM API examples (scim.dev)

Made with BabyLoveGrowth technology