> For the complete documentation index, see [llms.txt](https://doc.wearepatchworks.com/product-documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://doc.wearepatchworks.com/product-documentation/registration/sso/okta.md).

# 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:

<div align="left"><figure><img src="/files/HcnBHBjhCbQUekRRjSWE" alt=""><figcaption></figcaption></figure></div>

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.&#x20;

{% hint style="info" %}
Your Okta administrator requires a Patchworks account with administrator permissions to complete this setup.
{% endhint %}

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 URL](#stage-1-patchworks-add-okta-provider-and-generate-urls)s
* [Stage 2: Okta - add Patchworks app & apply URLs](#stage-2-okta-add-patchworks-app-and-apply-urls)
* [Stage 3: Patchworks - apply Okta credentials & enable](#stage-3-patchworks-final-setup)

## Demo

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

<div align="left"><figure><img src="/files/KvhJgVzPLuFTDITHOrM6" alt=""><figcaption></figcaption></figure></div>

## Prerequisites

* Your Patchworks user account must be associated with [administrator permissions](/product-documentation/users-roles-and-permissions/roles-and-permissions-summary.md).
* 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.&#x20;

**Step 1**\
Log into the [Patchworks dashboard](https://app.wearepatchworks.com/) and select `my company admin` from `general settings`:

<div align="left"><figure><img src="/files/2oNRZkiZMlNWdnmubU6r" alt=""><figcaption></figcaption></figure></div>

{% hint style="info" %}
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.&#x20;
{% endhint %}

**Step 2**\
Click the `Okta` button:

<div align="left"><figure><img src="/files/FpP6NhWLlywEFsdGBqW1" alt="" width="375"><figcaption></figcaption></figure></div>

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

<div align="left"><figure><img src="/files/oT4NYBv9P184c6SPPl5s" alt="" width="375"><figcaption></figcaption></figure></div>

{% hint style="info" %}
This is the first part of the URL that you use to access your Okta dashboard - for example:\
[https://wearepatchworks.okta.com/](https://trial-6142540.okta.com/). For our working example, the base URL is:\
`https://trial-6142540.okta.com/`.
{% endhint %}

**Step 4**\
Click the `create` button:

<div align="left"><figure><img src="/files/PvFS7n2ytED6HlHb87Mr" alt="" width="375"><figcaption></figcaption></figure></div>

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

<div align="left"><figure><img src="/files/6ZAyYOG7bHIWyIDXztG0" alt=""><figcaption></figcaption></figure></div>

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

<div align="left"><figure><img src="/files/qyKnpF1yOiR4Isaow3CQ" alt=""><figcaption></figcaption></figure></div>

These URLs are needed to complete your [Okta setup in the next stage](#stage-2-okta-setup). 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` |

{% hint style="info" %}
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`.
{% endhint %}

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

<div align="left"><figure><img src="/files/iptqxt4aIKyNKkRrHeUF" alt=""><figcaption></figcaption></figure></div>

{% hint style="info" %}
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.&#x20;
{% endhint %}

**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 `admin`for your organisation:

<div align="left"><figure><img src="/files/UZHujkeaDsOWUDUNPIZP" alt=""><figcaption></figcaption></figure></div>

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

<div align="left"><figure><img src="/files/ZtT4JlrNwDOpPGkw3mQY" alt=""><figcaption></figcaption></figure></div>

**Step 3**\
Choose to `create new app`:

<div align="left"><figure><img src="/files/GybJvAOukKX0VRj0wlnD" alt=""><figcaption></figcaption></figure></div>

{% hint style="info" %}
As an Okta administrator, you'll likely have your own shortcut/route to access this option - feel free to use these instead.
{% endhint %}

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

<div align="left"><figure><img src="/files/eFY6wPGKfCkDI8BzjdOB" alt=""><figcaption></figcaption></figure></div>

**Step 5**\
Select `web application` as the `application type`:

<div align="left"><figure><img src="/files/WasZnkbeSV4bdDF9YGad" alt=""><figcaption></figcaption></figure></div>

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

<div align="left"><figure><img src="/files/2Bf9wbNjlxUrG2CzT2vk" alt=""><figcaption></figcaption></figure></div>

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

<details>

<summary><img src="/files/p8Imrv0C8FKXThhHEGzf" alt="" data-size="line"> Patchworks logos </summary>

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

<img src="/files/SjiB3nI7g0L3QuX4FLOL" alt="" data-size="original">

<img src="/files/JWzh89vp664EbpvJ5a1a" alt="" data-size="original">

<img src="/files/VHthxdZOERttoPd6ye3n" alt="" data-size="original">

</details>

**Step 8**\
Save changes.

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

<figure><img src="/files/VRFYEJFossvpsmWYoDWa" alt=""><figcaption></figcaption></figure>

**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:

<div align="left"><figure><img src="/files/d2Ivo5iXAyxbfZu7yzU7" alt=""><figcaption></figcaption></figure></div>

**Step 11**\
Save your changes.

{% hint style="info" %}
At this point, you may wish to assign a test user to try out the app once you've finished.&#x20;
{% endhint %}

## 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 credential`s section - you'll see `client id` and `client secret` details:

<div align="left"><figure><img src="/files/nAE4Dy6907sXkdbiXD5p" alt=""><figcaption></figcaption></figure></div>

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

<figure><img src="/files/q4x41DBAYTa7XApfaWyw" alt=""><figcaption></figcaption></figure>

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

<div align="left"><figure><img src="/files/vC3EQjJ3SmyvOH41sQP9" alt=""><figcaption></figcaption></figure></div>

**Step 4**\
Toggle the `enable` option to `on`:

<div align="left"><figure><img src="/files/eUAgmDRx2vjwSMeLh8Gq" alt=""><figcaption></figcaption></figure></div>

{% hint style="warning" %}
The SSO implementation won't be operational until this setup is enabled.&#x20;
{% endhint %}

**Step 5**\
Save changes:

<div align="left"><figure><img src="/files/5Njytdrsr7zO8NSrkCW5" alt=""><figcaption></figcaption></figure></div>

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

<figure><img src="/files/HcnBHBjhCbQUekRRjSWE" alt=""><figcaption></figcaption></figure>