Manage roles with Okta

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.

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 isn't 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.

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.

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

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.

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

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>:ProjectManager), 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].

Any other approach works as well, as long as the roles attribute resolves to the role attribute values.

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).

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 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.