Configure SSO Custom Role Provisioning

This guide explains how to use your SAML identity provider (IdP) to assign a Coconut profile and Custom Roles when a user signs in. Before you begin, ensure that basic SSO and SSO role mapping are already configured

• Before you begin
• How it works
• Set up Coconut
• Configure your identity provider
  • Microsoft Entra ID
  • Okta
  • Google Workspace
  • Other SAML 2.0 providers
• Test before production rollout
• Expected behaviour
• Troubleshooting
  • What to provide when requesting support

Before you begin

• Your Coconut SAML SSO connection must already be working.
• Your Coconut administrator must have created the Custom Roles you want to assign through SSO.
• Have a test user available in your IdP.
• Coordinate with your Coconut contact to confirm that SSO role provisioning is enabled for your organization.

How it works

Coconut reads a SAML attribute named externalRoleId at sign-in.

The attribute must contain two or more values in this order:

1. Your Coconut profile mapping value
2. One or more Custom Role IDs

For example:

profile-branch-manager
crp-analytics
crp-approver

Conceptually, the SAML assertion should look like this:

<Attribute Name="externalRoleId">
  <AttributeValue>profile-branch-manager</AttributeValue>
  <AttributeValue>crp-analytics</AttributeValue>
  <AttributeValue>crp-approver</AttributeValue>
</Attribute>

Set up Coconut

1. In Coconut SSO settings, create or confirm the User Role Mapping for the profile value you will send first (for example, profile-branch-manager).
2. In each Custom Role you want to assign through SSO, set the role’s External ID to the exact value your IdP will send (for example, crp-analytics).
3. Record the ordered values for your test user.

Configure your identity provider

 In your external identity provider, navigate to your Coconut SAML application, and add or update the attribute named externalRoleId.

Configure it to send repeated, ordered values:

• First: the Coconut profile mapping value
• Then: the applicable Custom Role External IDs

The exact steps vary by provider. Use your provider’s current documentation, then validate the actual SAML assertion before rolling out the change.

Microsoft Entra ID

1. Open the Coconut enterprise application.
2. Go to Single sign-on → Attributes & Claims.
3. Add or edit the externalRoleId claim.
4. Use a multi-valued source attribute or transformation as appropriate.
5. Ensure the profile mapping value is emitted first, followed by Custom Role IDs.

Okta

1. Open the Coconut SAML application.
2. Go to Sign On → Attribute Statements.
3. Add an attribute named externalRoleId.
4. Configure the profile attribute or expression to return multiple values in the required order.

Google Workspace

1. Create a multi-value custom user attribute named externalRoleId.
2. For the test user, enter the values in the required order.
3. In the Coconut SAML application, map that custom attribute to externalRoleId.

Other SAML 2.0 providers

Your provider must be able to send multiple values for one SAML attribute, in a defined order. The required contract is the same:

• Attribute name: externalRoleId
• First value: Coconut profile mapping value
• Remaining values: Custom Role External IDs
• Format: repeated SAML values, not a delimited string

Test before production rollout

1. Sign in to Coconut using the test user.
2. Inspect the raw SAML response. Confirm there is one externalRoleId attribute with multiple values in the intended order.
3. Confirm the user receives the expected Coconut profile and Custom Roles.
4. Remove one Custom Role ID from the IdP, sign in again, and confirm that role is removed.
5. Test with only the profile value to confirm your standard profile-based role behavior.

A preview in your IdP’s expression editor is not sufficient. The raw SAML assertion is the source of truth.

Expected behaviour

• Coconut updates SSO-managed Custom Roles when the user next signs in through SSO.
• Adding a role value in the IdP adds that role at the next SSO login.
• Removing a role value in the IdP removes that role at the next SSO login.
• If any value is invalid, access is not partially assigned. Correct the mapping and try again.
• If SSO role provisioning is being used, updating a user’s role in the Coconut app UI will only apply for that user’s active Session, and will be reset to whatever Role(s) have been assigned in the IDP upon their next login

Troubleshooting

What to provide when requesting support

When requesting support from our technical support team, please provide the following:

• Your organization name and environment
• Your identity provider
• The ordered externalRoleId values expected for the test user
• The profile mapping value and Custom Role External IDs being used
• A redacted SAML assertion showing the externalRoleId attribute
• The test user’s sign-in time and the observed result or error message