Skip to main content
Instead of managing roles manually in Pinecone, you can have Pinecone automatically assign organization and project roles from your identity provider (IdP) on each login. This page continues Configure SSO with Okta and shows how to set up SAML role management with Okta. These instructions can be adapted for any provider with SAML 2.0 support.
SAML role management is available on the Enterprise plan and builds on SAML SSO. Before you begin, configure SSO with Okta and enforce SSO for your organization.

​
How it works

When SAML role management is enabled, Pinecone reconciles each user’s roles on every SSO login:
  • Pinecone reads the roles your IdP sends in the SAML roles attribute.
  • It replaces the user’s organization and project roles with exactly the roles in that attribute. Roles for projects not included in the attribute are removed, and values that don’t match a known role are ignored.
  • Because roles come entirely from your IdP, while this mode is enabled you can no longer invite members or edit roles in the Pinecone console or through the Admin API, and the SSO Default role is not applied.
  • To revoke a member’s access, remove their roles in your IdP. At their next sign-in, Pinecone clears all of their organization and project roles and blocks the login. Active members are re-authenticated at least every 24 hours, so the change applies within a day.
Because SSO is enforced, deactivating or removing a member in your IdP blocks them from signing in to Pinecone right away, so their access ends immediately. Their role assignments stay in Pinecone until their next sign-in—which a removed member never reaches—so the assignments remain but grant no access on their own. To clear them, or to have Pinecone remove members automatically, use SCIM provisioning. You can also switch to Manage roles in Pinecone to remove the member manually, then switch back.
To avoid losing access, configure and verify the roles attribute in Okta before you enable SAML role management in Pinecone. The steps below are in that order.
Enabling SAML role management does not validate your IdP configuration, so a user missing an organization role can be locked out on their next login. Before you enable it, verify the roles attribute for a current owner (see Step 2).

​
Role attribute values

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.

​
Organization roles

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

​
Project roles

For details on what each project role grants, see Understanding projects. For example, to make a user an organization owner who is also an editor on one project, send these two values in the roles attribute:

​
1. Send roles from Okta

Configure Okta to send each user’s roles in a SAML attribute named roles, where each value is one of the role attribute values above. You can populate that attribute in a few ways; choose whichever fits how you already manage users in Okta.
In newer versions of Okta, attribute and group statements are configured on the app’s Sign On tab after the app is created, rather than in the app creation wizard. If you don’t see the Attribute Statements (SAML) section, expand Show legacy configuration within it.

​
Option A: From a user profile attribute

Use this option to set roles directly on each user’s Okta profile.
  1. In Okta, go to Directory > Profile Editor and edit the Okta user profile.
  2. Add an attribute named pineconeRoles with data type string array.
  3. For each user, set pineconeRoles to their pinecone:* values (directly, or through a profile mapping).
  4. In Applications > Pinecone > Sign On, add an Attribute Statement:
    • Name: roles
    • Name format: Unspecified
    • Value: user.pineconeRoles

​
Option B: From group membership

Use this option to assign roles by adding users to Okta groups.
  1. In Okta, create a group for each Pinecone role you want to assign, naming each group exactly as the role’s attribute value (for example, pinecone:OrgOwner or pinecone:project:<projectID>:ProjectEditor), and add the appropriate users to each group.
  2. In Applications > Pinecone > Sign On, send those group names in the roles attribute using either:
    • A Group Attribute Statement with Name roles, Name format Unspecified, and Filter Starts with pinecone:.
    • Or an Attribute Statement with Name roles and the expression user.getGroups({'group.profile.name': 'pinecone:', 'operator': 'STARTS_WITH'}).![profile.name].
The user.getGroups(...).![profile.name] expression is for an app-level attribute statement on the Sign On tab, and it returns every matching group, so no limit argument is required. (Only the Groups.startsWith, Groups.endsWith, and Groups.contains functions require a limit.) If you configure this claim on a custom authorization server instead, use the .![name] projection.
Any other approach works as well, as long as the roles attribute resolves to the role attribute values.

​
2. Verify the roles in the SAML assertion

Before you hand role management to Okta, confirm the roles attribute contains what you expect.
  1. In Applications > Pinecone > Sign On, click Preview the SAML Assertion.
  2. Select a user who should be an organization owner and generate the preview.
  3. Confirm the assertion includes a roles attribute containing pinecone:OrgOwner (and any project roles you assigned).
If no current organization owner’s preview includes pinecone:OrgOwner, fix your Okta configuration before continuing. Enabling SAML role management without a provisioned owner can lock your organization out of role management. If the roles attribute is empty or missing, re-check your attribute statement expression and projection before continuing, as a malformed expression returns no roles rather than an error.

​
3. Enable SAML role management in Pinecone

You must be an organization owner on the Enterprise plan, and SSO must be enforced for your organization.
  1. In the Pinecone console, go to Settings > Access > Identity provider.
  2. Confirm that single sign-on shows the Enforced status. If it does not, edit your SSO configuration to enforce SSO before continuing.
  3. In the User management section, select Manage roles with SAML attributes.
  4. In the Enable SAML role management dialog, review the Before you enable prerequisites, then click Enable SAML role management.
Role assignment now comes entirely from your IdP. Roles update at the member’s next SSO login. Since SAML sessions re-authenticate at least every 24 hours, an active user’s role changes apply within 24 hours. Default role assignments configured during SSO setup no longer apply. To stop syncing roles from your IdP, return to Settings > Access > Identity provider and select Manage roles in Pinecone. Existing roles are preserved, and you can edit them again in the console.