# 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.
{% 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:
## Prerequisites
* Your Patchworks user account must be associated with [administrator permissions](https://doc.wearepatchworks.com/product-documentation/users-roles-and-permissions/roles-and-permissions-summary).
* 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](https://app.wearepatchworks.com/) and select `my company admin` from `general settings`:
{% 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.
{% endhint %}
**Step 2**\
Click the `Okta` button:
**Step 3**\
When prompted, enter the base URL for your Okta account.
{% 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:
**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](#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:
{% 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.
{% 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:
**Step 2**\
Choose to `add an app to use single sign-on`:
**Step 3**\
Choose to `create new app`:
{% 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:
**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.
{% hint style="info" %}
At this point, you may wish to assign a test user to try out the app once you've finished.
{% 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:
**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`:
{% hint style="warning" %}
The SSO implementation won't be operational until this setup is enabled.
{% endhint %}
**Step 5**\
Save changes:
Any assigned users in Okta should now see a Patchworks app in their Okta dashboard, ready for use:
Patchworks logos 
