SCIM provisioning with Okta

Instead of managing members and roles manually in Pinecone, you can have your identity provider (IdP) provision them automatically over SCIM. This page continues Configure SSO with Okta and shows how to set up SCIM provisioning with Okta. These instructions can be adapted for any provider with SCIM 2.0 support.

When SCIM provisioning is enabled, your IdP manages organization membership and roles in Pinecone in near real time:

• As members are added, updated, or removed in Okta, those changes sync to Pinecone over SCIM in near real time, not just at login.
• Okta connects to a SCIM endpoint that Pinecone provides, authenticating with a bearer token you generate in the Pinecone console.
• Pinecone reads each member's roles from the SCIM roles attribute and sets their organization and project roles to exactly those values. Values that don't match a known role are ignored. For the other attributes Pinecone reads, see Supported attributes.
• While SCIM is enabled, SCIM is the source of truth for roles: Pinecone no longer applies the roles in a member's SAML login assertion, even though members still sign in through SAML SSO.
• Deactivating or removing a member in Okta removes them from the organization, and clearing a member's roles revokes their access.
• Because membership and roles come entirely from your IdP, while SCIM is enabled you can no longer invite members or edit roles in the Pinecone console or through the Admin API.

Pinecone reads the following SCIM user attributes and ignores all others, including emails, phoneNumbers, addresses, photos, title, and enterprise extension attributes such as department and manager.

A member needs both required attributes to get access. Okta can't provision a member without userName, and a member whose roles has no organization role has no access to the organization.

The console shows a member's displayName, or their email address if Okta doesn't send one. To show members' names in the console, keep the displayName mapping.

Pinecone reads roles from the roles attribute. Each value uses one of the following formats:

• Organization role: pinecone:<OrgRole>
• Project role: pinecone:project:<projectID>:<ProjectRole>

<projectID> is the project's unique ID. To find it, go to the project list in the Pinecone console. For more information, see Project IDs.

A user can hold multiple roles by sending multiple values in the roles attribute.

For details on what each organization role grants, see Understanding organizations.

For details on what each project role grants, see Understanding projects.

For example, to make a user an organization manager who is also a project owner on one project, send these two values in the roles attribute:

pinecone:OrgManager
pinecone:project:a2f7dddb-1597-4eff-9f71-535fde243f58:ProjectOwner

1. In the Pinecone console, go to Settings > Access > Identity provider.
2. Confirm that single sign-on shows the Enforced status. If it doesn't, edit your SSO configuration to enforce SSO before continuing.
3. In the User management section, select Manage roles with SCIM provisioning.
4. In the Set up SCIM provisioning dialog, review the instructions and click Get started.

1. Choose the token's permissions and expiry. By default the token grants all user permissions and expires in 90 days; you can also choose Token never expires.
2. Click Generate token.
3. Copy the bearer token. The SCIM endpoint is shown on the next screen of the dialog. You'll add both to Okta in Step 3.

1. In Okta, navigate to Applications > Pinecone > General.

2. In the App Settings section, click Edit, set Provisioning to SCIM, and click Save.

3. Open the Provisioning tab and click Configure API Integration.

4. Select Enable API Integration and enter the following:

   • SCIM connector base URL: The SCIM endpoint you copied in Step 2.
   • Unique identifier field for users: userName.
   • Authentication Mode: HTTP Header.
   • Authorization: The bearer token you copied in Step 2.

5. Click Test API Credentials to verify the connection, then click Save.

6. Under Provisioning > To App, click Edit and enable Create Users, Update User Attributes, and Deactivate Users.

7. Still under Provisioning > To App, scroll to Pinecone Attribute Mappings and check the source for userName. If it's set to user.login or an Active Directory attribute, change it to user.email and click Save.

Okta doesn't send a member's Pinecone roles by default. You define one app attribute per role you want to assign, then map a value to it for the right members. Pinecone reads only each value, so the same approach scales to as many roles as you need.

1. In Okta, go to Directory > Profile Editor and open the Pinecone app profile.

2. For each role you want to assign, click Add Attribute and configure:

   • Data type: string
   • External name: roles.^[type=='<label>'].value, where <label> is any unique label for the role (for example, orgOwner or projManager). Pinecone reads only the value, so the label is only used to keep attributes distinct in Okta.
   • External namespace: urn:ietf:params:scim:schemas:core:2.0:User

3. Go to Provisioning > To App > Pinecone Attribute Mappings (or Mappings in the Profile Editor) and map each attribute to the role value for the members who should hold it. Set the mapping to apply on create and update. Source the value however you manage users, for example:

   • From a custom user profile attribute that holds the pinecone:* value.
   • From group membership with an expression such as isMemberOfGroupName('Pinecone Owners') ? 'pinecone:OrgOwner' : ''.

4. Click Preview for a representative user and confirm the roles attribute resolves to the expected pinecone:* values (including pinecone:OrgOwner for a current owner).

For example, an organization manager who is also a project owner on one project needs two attributes: one mapped to pinecone:OrgManager and one mapped to pinecone:project:<projectID>:ProjectOwner. Project values include the project's unique ID, not its name.

1. Assign your members to the Pinecone app in Okta so it pushes them over SCIM. For members who were already assigned, use Provisioning > To App > Force Sync or Apply updates now so their attributes resync.
2. Confirm the members and roles arrived. In Okta, check Reports > System Log (or the app's provisioning activity) for SCIM errors if members don't appear.
3. Verify that at least one current Pinecone organization owner was provisioned with pinecone:OrgOwner.

1. Back in the Pinecone Set up SCIM provisioning dialog, click Enable SCIM. Pinecone verifies that an organization owner has been provisioned with pinecone:OrgOwner before activating.
2. If Pinecone blocks activation because no owner is provisioned, return to Okta, assign pinecone:OrgOwner to a current owner (see Step 4), let it sync, and click Enable SCIM again.

Once enabled, your IdP is the source of truth for membership and roles. Members and their roles sync automatically as you provision them in Okta.

To rotate or revoke tokens or view the SCIM endpoint, select Manage next to the SCIM option. To stop provisioning, select Manage roles in Pinecone (or Disable SCIM from the Manage dialog), which revokes all SCIM tokens and reverts to manual role management. Existing role assignments are preserved until you change them.