Skip to main content

Documentation Index

Fetch the complete documentation index at: https://backstage.spotify.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

It is important to follow all the steps in this guide to ensure a successful configuration of authentication.If you encounter any issues, please contact support.
Portal can ingest organizational data—such as users and teams—from your Okta tenant via the Okta API. To do this, you must create a new Okta App with specific permissions to your and configure the Okta catalog provider in Portal.

​
Create new App in Okta

Within your Okta dashboard create a new app integration where the sign-in method is API Services. Call the application “Spotify Portal - Provisioning” (or your own custom app name). Then store the following information:
  • Client ID
  • Public Key
  • KID (A Key ID that is associated with your private key)
In addition, in the tab Okta API Scopes you need to add the following scopes:
  • okta.groups.read
  • okta.users.read
In the app’s “General Settings” tab, scroll down to the “Client Credentials” section and uncheck the Demonstrate Proof of Possession header option. This is required for Portal to properly authenticate with Okta.

​
Scoping the application

It is important to note that you can scope the application to make sure Portal can access only the users and groups it needs. This can be done by creating and assigning the following Resource Sets and Roles:
  1. Navigate to Security > Administrators
  2. Click on the Resources tab and create a new resource set called “Spotify Portal Users & Groups”.
  3. Add the Users and Groups resources. (For now, we recommend to ingest all users but only a set list of groups.)
  4. Now navigate back to your newly created app
  5. Select the Admin roles tab and select add assignment
  6. Select “Create a role” and call it “Spotify Portal org data viewer” with the following permissions
    • User > View users and their details
    • Group > View groups and their details
  7. Assign the admin role to the just created resource set

​
Configure the Okta Org Provider in Portal

  1. In Config Manager, go to the Catalog plugin
  2. Scroll to catalog.providers.okta
  3. from your Okta instance fill in
    • id (e.g., default)
    • oktaUrl (URL of your Okta instance)
    • clientId
    • privateKey
    • keyId (which is the KID)
Add app credentials
  1. Then scroll down and fill in the Schedule
    • frequency (We recommend every 30 minutes)
    • timeout (We recommend keeping it consistent with the chosen frequency value)
Add schedule
  1. Add groups you want to ingest by adding their Okta names in the groups section
Add groups
  1. Click Save changes.
Portal will now begin ingesting and synchronizing user and group data from Okta. You can check this by visiting Portal’s Catalog, and looking to see if expected users and groups are being added from Okta.

​
Next Steps

Your Portal instance should now have users and groups from Okta within the catalog. It is very likely that you will now have multiple providers bringing in users and groups to your catalog which can result in duplicate users and cause conflicts when attempting to sign in. Follow the next section for how to remove existing users and groups from the catalog and complete this integration.