# Identity providers (https://docs.idra.zone/docs/admin/identity-providers)

Let people sign in with an external IdP or a social account, and decide who it can sign in as.

Go to **Security → Identity Providers** to add an OpenID Connect or SAML 2.0 provider, or a social preset for Google or Microsoft.

## Who a provider can sign in

A provider can only sign in email addresses on its own domains. Other addresses are refused with `EMAIL_DOMAIN_NOT_ALLOWED`.

| Setting | What it does |
|---|---|
| **Just-in-time provisioning** | Creates a person the first time they sign in |

## Account linking

Off for every provider unless you turn it on. Someone who already has an account and no link to the provider is refused with `ACCOUNT_NOT_LINKED`.

To turn it on, open the provider, go to **Account linking**, switch on **Link existing people** and list the **Domains allowed for linking**. Both are needed: an empty list links nobody. The list is separate from the provider's domains and can only name some of them, so a provider can route a domain without being able to reach its existing accounts.

- Anyone who controls the provider can sign in to accounts on those domains, so list only domains it's authoritative for.
- Administrators are never linked. Add their link by hand if an admin must sign in through a provider.
- Only a super admin can change these settings, and each change is logged as `system.idp.linking.update`.
- Removing a domain from the provider removes it from the list too. Adding it back doesn't restore it.
- A provider asserting that an email is verified never links an account by itself.
- An OpenID Connect provider must also say `email_verified: true` for a link to happen. If it leaves the claim out, the person is refused with `EMAIL_NOT_VERIFIED`, though the provider can still create new people. Check that your provider sends the claim before you rely on linking. SAML has no such claim.

These people are always refused:

- Anyone suspended, staged or deprovisioned, even with an existing link.
- Anyone whose OpenID Connect provider says `email_verified: false`. Social providers must explicitly say `true`.

## Social sign-in

A social preset adds a **Sign in with…** button to the sign-in page. Microsoft needs your directory (tenant) ID.

Domains are optional:

- **With domains**, it behaves like any other provider.
- **Without domains**, it can only create new people, and can never sign in to an account that already exists.

Just-in-time provisioning starts off for social presets, because otherwise anyone with a Google account could become a person in your directory.

Apple and GitHub aren't available as presets.

## Attribute and group mapping

On a provider's page, **Attribute and group mapping** runs at every sign-in.

- **Profile attributes:** one per line, as `department = dept`. That's the IdRa attribute, then the provider's claim or SAML attribute.
- **Group claim** and **Groups:** one per line, as `engineers = <group id>`. The value `*` means everyone from this provider.

A person leaves a mapped group when the claim stops listing it, but only if the mapping added them. Memberships from anywhere else stay. A partner's linked group can't be a target.

## Routing rules

Sign-in checks **Routing rules** first, lowest priority number first, then the provider that owns the email domain, then password. A rule can match on email domain, app client ID, network zone and platform.

Routing only picks where someone signs in. It doesn't grant anything: the provider's own domains and your sign-on policies still apply. Rules can't match on groups, because the step runs before anyone has signed in and would reveal who's in a group.

## SAML options

| Option | What it does |
|---|---|
| **Request signing key** | Signs the requests IdRa sends to the provider |
| **Assertion decryption key** | Decrypts assertions the provider encrypts to the matching certificate |
| **IdP-initiated sign-in** | Accepts sign-ins that start at the provider. Off by default. Each assertion works once |
| **Single logout** | Accepts logout requests from the provider, which must be signed. Off by default |

Set the keys when you add the provider. To change them, delete the provider and add it again.

**Not supported yet**

The sign-out menu doesn't send people through the provider's logout page. Decrypting assertions hasn't been tested against a provider that encrypts them.

## Secrets

Client secrets and private keys are encrypted with `ENCRYPTION_KEY`. A provider added before encryption keeps working and is encrypted the next time you save it.