# PingOne
## Introduction
With a `PingOne` SSO implementation, users log into the Patchworks dashboard from PingOne. Your PingOne administrator determines who has access to Patchworks and these users will see a Patchworks app in their PingOne dashboard.
Selecting this app directs the authenticated user to the Patchworks dashboard, where they are logged in directly. PingOne users never see or require a password to access the Patchworks dashboard.
{% hint style="info" %}
Your PingOne administrator requires a Patchworks account with administrator permissions to complete this setup.
{% endhint %}
This guide details the setup required to integrate Patchworks with PingOne. For clarity, the setup is documented in six stages:
* [Stage 1: PingOne - create app for Patchworks](#stage-1-pingone-create-app-for-patchworks)
* [Stage 2: Patchworks - add PingOne provider & generate URLs](#stage-2-patchworks-add-pingone-provider-and-generate-urls)
* [Stage 3: PingOne - configure app](#stage-3-pingone-configure-app)
* [Stage 4: Patchworks - apply PingOne credentials & enable](#stage-4-patchworks-apply-pingone-credentials-and-enable)
* [Stage 5: PingOne - define scopes](#stage-5-pingone-define-scopes)
* [Stage 6: Test the connection](#stage-6-test-the-connection)
## 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 PingOne dashboard.
## Stage 1: PingOne - create app for Patchworks
In this stage, we create a new app in PingOne and copy the associated `issuer id` for use in the next stage.
**Step 1**\
Log into PingOne and select `administrators` | `applications` | `applications` from the navigation menu:
**Step 2**\
Click the plus icon at the top of the page:
**Step 3**\
Enter an `application name` (we suggest `Patchworks` or similar), then select `OIDC Web App` as the application type, and save changes:
The app is saved/published and configuration details are shown.
**Step 4**\
Scroll down to the `connection details` section and copy the `issuer ID`:
**Step 5**\
Leave this page where it is and go to the next stage.
## Stage 2: Patchworks - add PingOne provider & generate URLs
In this stage, we add a new SSO provider in Patchworks using your PingOne `issuer ID` (obtained in the previous stage) as the `base URL`. This generates a set of URLs that we'll go on to apply in PingOne.
**Step 1**\
In a new browser tab or window, 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 `PingOne` button:
**Step 3**\
Paste the `issuer ID` for your new PingOne app (copied at the end of the [previous stage](#stage-2-patchworks-add-pingone-provider-and-generate-urls)) into the `base URL` field **but remove the `/as` characters from the end**:
{% hint style="warning" %}
It's important to remove the `/as` characters from the end of the `issuer ID`. For example: \
`https://auth.pingone.eu/3c2eca2e-fc6e-4509-8154-68d93a9dbdf3/as` would be entered as:\
`https://auth.pingone.eu/3c2eca2e-fc6e-4509-8154-68d93a9dbdf3`.
{% endhint %}
**Step 4**\
Click the `create` button to confirm.
**Step 5**\
A PingOne provider is added - click this entry:
...you'll see that three Patchworks URLs have been generated - for example:
These URLs are needed to complete your PingOne setup in the next stage. For reference, these are:
| Patchworks URL | PingOne usage |
| ----------------------- | ------------------------ |
| Initiate sign-in url | `Initiate Login URI` |
| Callback url (auth url) | `Redirect URIs` |
| Logout url | Not required for PingOne |
{% 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 6**\
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 7**\
Save changes.
**Step 8**\
Leave this page open and switch back to PingOne for the next stage.
## Stage 3: PingOne - configure app
In this stage, we configure your new Patchworks app in PingOne. As part of this setup, we will provide URLs generated by Patchworks, at the end of the previous stage.
**Step 1**\
Back in PingOne, select the `configuration` tab:
**Step 2**\
Edit settings, then move down to the `redirect URIs` field and paste the `callback URL` value from your PingOne provider setup in Patchworks:
{% hint style="info" %}
When copying URLs from your Patchworks provider details, click anywhere on the required link to copy it to your clipboard:
{% endhint %}
**Step 3**\
Set `token endpoint authentication method` to `client secret post`:
**Step 4**\
Move down to the `initiate login URI` field paste the `initiate sign-in URL` value from your PingOne provider setup in Patchworks:
**Step 5**\
Save your changes and go to the next stage.
## Stage 4: Patchworks - apply PingOne credentials & enable
In this stage, we take client credentials generated in PingOne, apply them to our PingOne provider setup in Patchworks, and enable this SSO implementation.
**Step 1**\
Still in PingOne, scroll to the top of the configuration page and toggle the 'enable' option (to the right of the app name) to the `on` position:
**Step 2**\
A little further down, you'll see `client id` and `client secret` details - copy the `client id`:
**Step 3**\
Switch to Patchworks and select the `edit` option for your PingOne provider setup:
**Step 4**\
Paste the `client id` and then repeat the copy/paste for the `client secret` value:
**Step 5**\
Toggle the `enable` option to `on`:
{% hint style="warning" %}
The SSO implementation won't be operational until this setup is enabled.
{% endhint %}
**Step 6**\
Save changes:
## Stage 5: PingOne - define scopes
In this stage, we define permissions (scopes) for the connection between PingOne and Patchworks.
**Step 1**\
Still in PingOne, select the `resources` tab at the top of the page:
**Step 2**\
Edit scopes and make the following selections:
* `email`
* `offline access`
* `profile`
For example:
**Step 3**\
Save changes to complete the setup. When you're ready you can go on to assign groups/users who can access Patchworks. This is standard PingOne functionality that isn't covered here.
## Stage 6: Test the connection
To quickly test that a successful connection has been made between Patchworks and PingOne, switch back to the Patchworks dashboard, and copy the `initiate sign-in URL` value:
Now log out of Patchworks and paste the `initiate sign-in URL` value into your browser - this should log straight into the Patchworks dashboard.
{% endhint %}
**Step 3**\
Set `token endpoint authentication method` to `client secret post`:
