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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://doc.wearepatchworks.com/product-documentation/registration/sso/okta.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.