In this article, you'll learn how to set up SAML SSO with Okta, allowing you to:
- Enable your users to be automatically signed in to Productboard using their Okta accounts.
- Manage your accounts in one central location – Okta.
- Change the default role settings for users managed in Okta, from contributor to admin, maker, or viewer.
To learn more about SAML app integration with Okta, take a look at this official documentation.
Prerequisites
To get started, you'll need the following items:
- An Okta subscription. If you don't have a subscription, you can sign up for a one-month free trial.
- A Productboard single sign-on (SSO) enabled subscription (available on the Enterprise plan).
Let's configure and test SAML SSO with OKTA:
Add Productboard to your list of managed SaaS apps
1. Log in to your Okta account and navigate to the Admin dashboard.
2. On the top navigation panel, select Applications.
3. Select Add Application.
4. Please don't ❌ use this Productboard application in Okta's catalog. This application will not work when setting a custom "pb_role" attribute.
5. Use Create New App button and set application as following.
Make sure you fill the following fields correctly:
SSO URL: https://{workspace_name}.productboard.com/users/auth/saml/callback
you can check the option Use this for Recipient URL and Destination URL...
- Audience URI: productboard
- Name ID format: EmailAddress
- Attribute statements:
pb_role: appuser.pb_role - this one is optional, if you don't plan to set different role than contributor during provisioning new users, you can skip this step
lastName: user.lastName
firstName: user.firstName
6. Save new application.
Grant access for OKTA users
In this section, you'll enable your users to use Okta single sign-on by granting access to Productboard.
1. Make sure you are inside the Productboard application and click Assignments.
2. Select Assign and then select Assign to people.
3. Then select assign to select the user to whom you are going to give access to Productboard using Okta.
4. Then check if the email is correct and select Save and go back.
5. Check if your user is Assigned and then select Done.
6. The user should appear in the People filter.
Note: the default role provided to users in this step is contributor – for instructions on how to change it, check out the Change default role for new users in Okta section.
Change default role for new users in Okta
In this section, you'll change the role of your users in Okta.
1. Select Directory and then click on Profile Editor in your Okta application.
2. Then, in the Productboard Profile, select Profile.
3. Then click Add Attribute.
4. Make sure you fill the following fields correctly:
- Display name: PB Role
- Variable name: pb_role
- Check the enum checkbox with the text "Define enumerated list of values".
- Then fill the Display name and Value fields with the following values:
admin | admin
editor | editor
contributor | contributor
viewer | viewer - And click Save.
5. Make sure you get confirmation that the attribute pb_role has been added.
6. Then we need to click on Applications and then on Productboard.
7. Make sure you select Assignments in the Productboard profile and then click on the person's name for whom you would like to change the role.
8. Click on Applications and then in edit.
9. You should see pb_role. You can change it to the role that the user should have in Productboard and then click Save.
10. Log in with this user using Okta. You will see that the user has the role.
Configure Productboard SSO in the Productboard app
1. First, open the Sign On section in the Productboard app in Okta, then select View Setup Instructions.
2. Now you can to follow the configuration steps in this article or continue following these instructions.
3. Copy the URL of your Okta space.
First option: Left click in the link (Identify Provider metadata) and then select Copy Link Location.
Second option: Open the link (Identify Provider metadata) and Copy the URL over there.
The URL should look like this:
https://<your_okta_space>.okta.com/app/asdasdadgtrrd/sso/saml/metadata
4. Go to https://<your_workspace>.productboard.com/
5. Go to Settings under the Profile menu.
6. In the Single Sign-on section, make sure to first turn off Enforce Google apps SSO
7. Toggle on Enforce SAML SSO.
8. Select From Metadata.
9. Paste the Identify Provider Metadata app (the one we copied in step 3) to the Manifest URL field and fill in Name Okta - this name will be visible on the login button.
10. Click Save & authorize.
11. Click the red Authorize button.
12. You will be redirected to Productboard, where you will be asked to log in under SAML SSO to finish the configuration. During this step, if configuration leads to an error, you will be able to log in to your space with "username + password" or Google SSO as you used to.
Disabling SAML SSO
You can disable the SAML SSO integration at any time in the Productboard settings.
The next time members log in, those who haven't set a Productboard password will be required to reset their password to receive login instructions via email.
If you wish to delete the Productboard application from Okta, you can do it by clicking Deactivate.
And then Delete.
Troubleshooting Okta issues
My certificate expired and I lost access to Productboard. How can I update the new certificate?
Reach out to us through the nifty Zendesk widget in the bottom right of the page, or email us at support@productboard.com. We can disable the SAML for you, and then you will be able to log in and update the certificate manually.
Backup URL
Productboard does not provide a backup login URL where users can sign in using their normal username and password. You can contact Productboard support (support@productboard.com) to turn off SAML, if necessary.
What should I do if I receive an "Invalid ticket" error?
This error occurs when something is not configured properly and you try to log in in the Productboard app. The easiest way to fix this is to start the configuration process again in Okta and double-check that everything is set according to our tutorial.
If you see this error and are having issues setting SAML configuration in Productboard again (you logged out and can't get back in), contact our Support Team, and we will disable SAML SSO in your workspace, allowing you to set it again.
For any further Okta-related troubleshooting, please see the official documentation.