Okta

Introduction

With an Okta SSO implementation, users log into the Patchworks dashboard from Okta. Your Okta administrator determines who has access to Patchworks and these users will see a Patchworks app in their Okta dashboard - for example:

Selecting this app directs the authenticated user to the Patchworks dashboard, where they are logged in directly. Okta users never see or require a password to access the Patchworks dashboard.

Your Okta administrator requires a Patchworks account with administrator permissions to complete this setup.

This guide details the setup required to integrate Patchworks with Okta. For clarity, the setup is documented in three stages:

• Stage 1: Patchworks - add OktaOne provider & generate URLs

• Stage 2: Okta - add Patchworks app & apply URLs

• Stage 3: Patchworks - apply Okta credentials & enable

Demo

The steps detailed in this guide are shown in this demonstration video:

Prerequisites

• Your Patchworks user account must be associated with administrator permissions.

• You must have administrator access to your Okta dashboard.

Stage 1: Patchworks - add Okta provider & generate URLs

In this stage, we add a new SSO provider in Patchworks using your Okta base URL. This generates a set of URLs that we'll go on to apply in Okta.

Step 1 Log into the Patchworks dashboard and select my company admin from general settings:

If you don't see this option, it's most likely that your user account is not associated with administrator permissions. In this case, please contact your system administrator.

Step 2 Click the Okta button:

Step 3 When prompted, enter the base URL for your Okta account.

This is the first part of the URL that you use to access your Okta dashboard - for example: https://wearepatchworks.okta.com/. For our working example, the base URL is: https://trial-6142540.okta.com/.

Step 4 Click the create button:

Step 5 An Okra provider is added - click this entry:

Step 6 You'll see that three Patchworks URLs have been generated - for example:

These URLs are needed to complete your Okta setup in the next stage. For reference, these are:

Patchworks URL	Okta usage
Initiate sign-in url	Login > Initiate login URI
Callback url (auth url)	New Web App Integration > Sign-in redirect URIs
Logout url	New Web App Integration > Sign-out redirect URIs

Note that URLs shown in our screenshots are for a development environment -dev.app.wearepatchworks.com. Yours will always be for a production environment -app.wearepatchworks.com.

Step 7 Optionally, you can click the edit option here and set a specific name for this implementation:

This isn't mandatory but using specific names can be useful if you're adding multiple implementations of the same type. Remember to save your change if you do update the name.

Step 8 Leave this page open and switch to another browser tab for the next stage.

Stage 2: Okta - add Patchworks app & apply URLs

In this stage, we create a new app for Patchworks in Okta. As part of this setup, we will provide URLs generated by Patchworks, at the end of the previous stage.

Step 1 Access Okta adminfor your organisation:

Step 2 Choose to add an app to use single sign-on:

Step 3 Choose to create new app:

As an Okta administrator, you'll likely have your own shortcut/route to access this option - feel free to use these instead.

Step 4 Select OIDC - OpenID Connect as the sign-in method:

Step 5 Select web application as the application type:

Step 6 Click next to access the New Web App Integration page:

Step 7 Update the following fields on this page (for URLs, you should switch back to the Patchworks dashboard to copy/paste values):

Field	Summary
Name	We suggest Patchworks or similar.
Logo	Optionally, you can upload a logo. A selection of Patchworks logos is available beneath this table.
Sign-in redirect URIs	Paste the callback url from your Okta provider details in Patchworks (click once in the callback url field to copy the url to the clipboard)
Sign-out redirect URIs	Paste the logout url from your Okta details in Patchworks (click once in the logout url field to copy the url to the clipboard).
Assignments	Assign people and groups from your organisation who require access to the Patchworks dashboard.

Patchworks logos

Right-click and save the desired logo with a .png file extension.

Step 8 Save changes.

Step 9 On the same page, move back up to general settings and select edit:

Step 10 Move down to the login section and update fields as detailed below:

Field	Required setting
Login initiated by	Either Okta or App
Application visibility	Display application to users
Initiate login URI	Paste the initiate sign-in url from your Okta provider details in Patchworks (click once in the initiate sign-in url field to copy the url to the clipboard).

For example:

Step 11 Save your changes.

At this point, you may wish to assign a test user to try out the app once you've finished.

Stage 3: Patchworks - apply Okta credentials & enable

In this stage, we take client credentials generated in Okta, apply them to our Okta provider setup in Patchworks, and enable this SSO implementation.

Step 1 Still on the New Web App Integration page in Okta, scroll to the client credentials section - you'll see client id and client secret details:

Step 2 In Patchworks, select the edit option for your Okta provider setup:

Step 3 Copy and paste client id and client secret values from Okta, into correlating Patchworks fields:

Step 4 Toggle the enable option to on:

The SSO implementation won't be operational until this setup is enabled.

Step 5 Save changes:

Any assigned users in Okta should now see a Patchworks app in their Okta dashboard, ready for use: