# Single sign-on: Okta

Source: https://parasend.com/docs/sso/okta

Your staff sign in to Parasend with their Okta account. With provisioning (SCIM), Okta also adds and suspends them in
Parasend, and Push Groups can set their role. Setting it up takes about 20 minutes.

You need to be an admin in Parasend, on Plan 1–3 or Enterprise. In Okta, you need to be a super admin or an app
admin.

## Before you start

- **Verify your e-mail domain** in Parasend under **Team → Domains**. Single sign-on can be turned on only once a
  domain is verified. When staff sign in with SSO and enter their work e-mail, the domain tells Parasend where to
  send them.
- **Open the Set up dialog** in Parasend under **Sign-in & SSO → Set up**, and choose **Okta**. It shows the addresses
  to paste into Okta, each with a copy button. Keep it open next to this guide.

## 1. Create the app in Okta

1. In the Okta Admin Console, go to **Applications → Applications → Create App Integration**, choose **SAML 2.0**,
   and name the app, for example "Parasend".
2. Under **Configure SAML**, paste these from Parasend's Set up dialog:
   - **Single sign-on URL** (keep "Use this for Recipient URL and Destination URL" ticked);
   - **Audience URI (SP Entity ID)**.
3. Set **Name ID format** to **Unspecified**, and keep **Application username** as Okta username.
4. Under **Attribute Statements**, add one: name `parasend_user_id`, value `user.id`.
   - Parasend links each person by this value. It is Okta's own user ID, which never changes.
   - The e-mail address is never used to link anyone. Without the attribute, the test fails.
   - Optionally, also add `firstName` = `user.firstName` and `lastName` = `user.lastName`. Parasend only shows them.
5. Choose **Preview the SAML Assertion** and check that `parasend_user_id` is in it. Then finish.
6. On the **Sign On** tab, copy the **Metadata URL**. In Parasend's dialog, paste it under step 3 and choose
   **Register provider**.
7. On the **Assignments** tab, assign the people or groups who should use Parasend.

## 2. Test, then turn on

1. In Parasend, choose **Test with your own account**. You sign in at Okta and come back to Parasend. You must be
   assigned to the app yourself.
2. Parasend shows whom Okta signed in. If it is you, choose **Yes, this is me**. That Okta account is then linked to
   your electronic ID.
3. Choose **Turn on** and confirm with your electronic ID.

From then on, staff choose **Use Microsoft, Okta, Google or SAML?** on Parasend's sign-in page and enter their
work e-mail, or open Parasend from their Okta
dashboard. The first time, each person confirms who they are once with their electronic ID. After that, their Okta
account is enough.

## 3. Require SSO (optional)

- **What it does:** when SSO is required, members get into your Parasend account only through Okta. Someone you
  deactivate in Okta can no longer get in.
- **If Okta fails:** the owner and up to two admins you name can still sign in with an electronic ID.
- **Before you turn it on:** Parasend names the members who have never signed in through Okta. Make sure Okta has
  them.
- **API keys** keep working.

To turn it on, sign in with SSO, choose **Require SSO**, and confirm with your electronic ID.

## 4. Provisioning (SCIM)

With provisioning, Okta sends each change to Parasend at once. It adds people when you assign them and suspends them
when you unassign or deactivate them.

1. In Parasend, under **Provisioning (SCIM)**, choose **Create token** and confirm with your electronic ID. Copy the
   token: it is shown only once.
2. In Okta, on the app's **General** tab, edit **App Settings**, set **Provisioning** to **SCIM**, and save.
3. On the **Provisioning** tab, under **Integration**, choose **Edit** and fill in:
   - **SCIM connector base URL**: the SCIM URL from Parasend;
   - **Unique identifier field for users**: `userName`;
   - **Supported provisioning actions**: Push New Users and Push Profile Updates, and Push Groups if you want roles
     from groups;
   - **Authentication Mode**: HTTP Header, with the token as the Bearer token.
4. Choose **Test Connector Configuration**, then **Save**.
5. Under **Provisioning → To App**, choose **Edit** and enable **Create Users**, **Update User Attributes** and
   **Deactivate Users**. Leave **Sync Password** off, and save.
6. People assigned before provisioning was on aren't sent yet. On the **Assignments** tab, choose **Provision User**
   for them.

What each change in Okta does in Parasend:

- **Assigned:** the person is listed under **Provisioned, not signed in yet** on the Team page. They join your team
  at their first SSO sign-in.
- **Unassigned or deactivated:** the member is suspended and signed out at once. They take no seat, and their SSO link
  ends, so if they come back they confirm with their electronic ID again. The owner gets an e-mail listing the live API
  keys the person held, to roll.
- **Suspended in Okta:** nothing reaches Parasend, because Okta doesn't tell apps about a suspension. Deactivate or
  unassign instead. While SSO is required, a suspended Okta user can't get in anyway, because they can't sign in to
  Okta.
- **Assigned or activated again:** the member is restored, if your plan has a free seat.
- **Removing someone from the team:** Okta never removes people from apps, so do this on Parasend's Team page.
- **Never deleted:** deliveries, evidence and the audit trail.
- **Never suspended by provisioning:** the owner.

## 5. Roles from groups (Push Groups)

1. Check that **Push Groups** is ticked under **Provisioning → Integration**.
2. In Okta, create a group for each role you want to give, named after it: **Parasend Admins**, **Parasend
   Developers**, **Parasend Senders**, **Parasend Viewers** or **Parasend Billing**. The role's name alone also works.
   Its members must also be assigned to the app, directly or through a group.
3. On the app's **Push Groups** tab, choose **Push Groups → Find groups by name** and pick the group.
4. Under the push action, choose **Create Group**, keep the group's name, and save.
   - Okta then finds Parasend's group by that name, so "Parasend Admins" becomes the Admin group.
   - Don't use **Link Group**: it lists Parasend's groups only when Okta can import groups, which this app doesn't do.

Okta pushes membership changes at once. How roles work:

- **One group:** each member gets that group's role at once.
- **Several groups:** they get the highest role, in the order Admin, Developer, Sender, Billing, Viewer.
  Parasend shows a warning.
- **No group:** they get the role set under **Without a group** in Parasend.
- **Changing a role:** a role that comes from a group can't be changed in Parasend. Change the group in Okta.
- **The owner's role** never changes.
- **Unlinking a pushed group** and deleting it in the app empties the group in Parasend. Its members fall back to the
  role set under **Without a group**.

## Certificates

- **Validity:** Okta's SAML signing certificate for an app is valid for ten years.
- **Warnings:** Parasend e-mails your owner and admins 30, 14 and 7 days before it expires.
- **To rotate:** on the **Sign On** tab, under **SAML Signing Certificates**, generate a new certificate and activate
  it. There is nothing to do in Parasend. Parasend reads your metadata URL every day, and at once when a new
  certificate signs a sign-in.

## If something goes wrong

- **Parasend says the test failed with the reason code `subject`:** the `parasend_user_id` attribute is missing or
  empty. Check it with **Preview the SAML Assertion**.
- **The SCIM test in Okta fails:** check the base URL, and that the token is entered as a Bearer token. Revoked tokens
  stop working at once.
- **Someone left but can still get in:** they were suspended in Okta, not deactivated. Deactivate or unassign them.
- **Locked out while SSO is required:** the owner and the admins you named sign in with their electronic ID on the
  usual sign-in page, and can stop requiring SSO.