# Single sign-on: any SAML provider

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

Any identity provider that supports SAML 2.0 can sign your staff in to Parasend, for example JumpCloud, OneLogin,
PingFederate, Keycloak or AD FS. If it also supports SCIM 2.0, it can add, suspend and remove people in Parasend.

You need to be an admin in Parasend, on Plan 1–3 or Enterprise.

## What Parasend needs from your provider

- **A signed assertion, signed with RSA-SHA256.** Assertions signed with SHA-1 are refused. Encrypted assertions
  aren't accepted.
- **Sign-in started at Parasend**, with the HTTP-POST binding back to the ACS URL. A provider's app launcher works
  too: Parasend then starts the sign-in again at your provider, and the person is signed in without noticing.
- **A permanent ID for each person that is never reused.** Use a persistent NameID, or an attribute you name in the
  Set up dialog, for example `employeeId`. The e-mail address is never used to link anyone, unless it is the ID
  itself.
  - If the NameID has the e-mail format, Parasend treats it as an e-mail address. Such links last 90 days, as with
    Google Workspace. After that, the person confirms with their electronic ID again.
- **Clocks within two minutes** of the correct time.
- **Its metadata,** by URL or as XML. A URL is better: Parasend reads it every day, and at once when a new certificate
  signs a sign-in.

## 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 **Other SAML provider**. It
  shows the addresses to paste into your provider, each with a copy button.

## 1. Create the app at your provider

1. Create a SAML 2.0 app, and paste these from Parasend's Set up dialog:
   - **Entity ID** (also called Audience or SP Entity ID);
   - **ACS URL** (also called Reply URL or Single sign-on URL);
   - **Start URL**, if your provider has a field for the app's sign-in or start address.
2. Choose the NameID format **persistent**, or one whose value is permanent.
3. Give the app to the people who should use Parasend.
4. In Parasend's dialog, paste the metadata URL or XML under step 3.
5. If the NameID isn't permanent, enter the name of the attribute that holds the person's ID under **Attribute with
   the user's ID**.
6. Choose **Register provider**.

## 2. Test, then turn on

1. In Parasend, choose **Test with your own account**. You sign in at your provider and come back to Parasend.
2. Parasend shows whom your provider signed in, with the ID it sent. If it is you, choose **Yes, this is me**. That
   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. The first time, each person confirms who
they are once with their electronic ID. After that, their account at your provider is enough.

## 3. Require SSO (optional)

- **What it does:** when SSO is required, members get into your Parasend account only through your provider.
- **If your provider 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 your provider.
- **API keys** keep working.

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

## 4. Provisioning (SCIM 2.0)

1. In Parasend, under **Provisioning (SCIM)**, choose **Create token** and confirm with your electronic ID. Copy the
   token: it is shown only once.
2. At your provider, enter:
   - **Base URL:** the SCIM URL from Parasend;
   - **Authentication:** an HTTP header, `Authorization: Bearer` followed by the token;
   - **Unique user field:** `userName`.
3. Send **externalId** with the same value as the ID your provider sends in SAML. Parasend matches a provisioned
   person to their sign-in by it, never by e-mail.

What Parasend does with each change:

- **A new user:** listed under **Provisioned, not signed in yet** on the Team page, and joins your team at their first
  SSO sign-in.
- **`active: false`:** the member is suspended and signed out at once. They take no seat, and their SSO link ends. The
  owner gets an e-mail listing the live API keys the person held, to roll.
- **`active: true`:** the member is restored, if your plan has a free seat.
- **`DELETE`:** the member is removed from the team, and their API keys pass to the owner.
- **Never deleted:** deliveries, evidence and the audit trail.
- **Never suspended or removed by provisioning:** the owner.
- **Too many calls at once:** Parasend answers 429. Wait and try again.

### Roles from groups

Parasend has five groups, one for each role a member can have: Admin, Developer, Sender, Viewer and Billing. Their
IDs are the role names (`/Groups/admin`).

- **Names:** create or match a group by its role's name, alone or after "Parasend", for example "Parasend Admins".
  Other names are refused, and a rename is ignored.
- **Several groups:** a member in several groups gets the highest role, in the order Admin, Developer, Sender,
  Billing, Viewer.
- **No group:** a member in none gets the role set under **Without a group**.
- **Deleting a group** empties it. The group itself stays.

## Certificates

- **Warnings:** Parasend e-mails your owner and admins 30, 14 and 7 days before your provider's certificate expires.
- **With a metadata URL:** there is nothing to do in Parasend when the certificate changes.
- **With pasted XML:** when the new certificate starts signing, choose **Replace metadata** on the connection and
  paste the new metadata. Sign-ins fail in between.

## If something goes wrong

- **Parasend says the test failed:** the page explains why and gives a reason code. Common reasons:
  - the assertion isn't signed, or is signed with SHA-1;
  - the ACS URL or Entity ID doesn't match;
  - the clocks differ by more than two minutes;
  - the ID is missing.
- **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.