# Other identity providers

> Connect By Dawn to any SAML 2.0 identity provider, such as ADFS, PingFederate, OneLogin or JumpCloud, or to any OpenID Connect provider.

This page helps you connect By Dawn to an identity provider we don't have a page for, such as Active
Directory Federation Services (ADFS), PingFederate, OneLogin, JumpCloud or Keycloak. At the end,
your people sign in to By Dawn through it, and you'll know exactly what By Dawn expects from your
provider, so you can check its settings against the list.

Most providers speak SAML 2.0, and many also speak OpenID Connect (OIDC). If yours does both, use
OIDC (see [OIDC or SAML?](https://docs.bydawn.com/sso/#oidc-or-saml)).
[Single sign-on](https://docs.bydawn.com/sso/#add-a-connection) explains the By Dawn side of a connection
once, so this page covers your provider's side.

## Before you start

- [Verify your email domain](https://docs.bydawn.com/sso-domains/) in By Dawn.
- You need to be the organization's owner in By Dawn and an admin in your identity provider.

## SAML 2.0

1. In By Dawn, pick **SAML 2.0**, name the connection and choose **Create draft**.

2. In your identity provider, create an app, which some providers call a **service provider**
   or a **relying party**. If it can import metadata from a URL, give it By Dawn's **SP metadata URL**
   and skip to step 3. Otherwise, enter By Dawn's values by hand:

   | By Dawn value | What your provider may call it |
   | --- | --- |
   | **SP entity ID (audience)** | Audience, Audience URI, SP entity ID, relying party identifier |
   | **ACS URL (single sign-on URL)** | Assertion consumer service URL, Reply URL, Single sign-on URL, Recipient |

3. Make your provider send the person's email (see [What By Dawn expects](#what-by-dawn-expects)).

4. Give By Dawn your provider's details. The quickest way is its metadata XML: paste it into **Paste your IdP's
   metadata XML (optional)** and choose **Fill in from metadata**. If your provider only publishes a metadata
   URL, open it in a browser and copy the XML from there. By Dawn fills in the three values it needs, which you can
   also type by hand:

   | By Dawn field | What your provider may call it |
   | --- | --- |
   | **IdP entity ID (issuer)** | Issuer, entity ID, IdP identifier |
   | **IdP sign-in URL** | SSO URL, sign-on URL, SingleSignOnService with the HTTP-Redirect binding |
   | **IdP signing certificate** | X.509 certificate, signing certificate (PEM, starting `-----BEGIN CERTIFICATE-----`) |

   Choose **Save changes**.

5. Allow the people or groups who should use By Dawn, then choose **Test connection** in By Dawn and
   **Activate**.

### What By Dawn expects

Check your provider's settings against this list. A sign-in that misses any of these is refused.

- **By Dawn starts the sign-in.** By Dawn sends your provider a sign-in request and only accepts the
  answer to that request, once. An answer nobody asked for (an IdP-initiated sign-in, from a
  dashboard tile) is refused, because it's easier to replay or forge. If your provider has a
  dashboard, point its tile at your organization's SSO address (see
  [How your people sign in](https://docs.bydawn.com/sso/#how-your-people-sign-in)).
- **The assertion is signed** by a certificate you gave By Dawn. Signing only the outer response isn't
  enough, but most providers sign the assertion by default, and signing both is fine.
- **The person's email** is the NameID, with the `emailAddress` format. Otherwise By Dawn reads it from the
  attribute you name in **Email attribute (optional)**, or, if you leave that empty, from the standard
  `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress` claim, then an attribute named `email`.
  It must be at one of your verified domains ([the email rule](https://docs.bydawn.com/sso/#the-email-rule)).
- **The request goes out by HTTP-Redirect and the answer comes back by HTTP POST** at By Dawn's ACS URL, which are
  the usual bindings. By Dawn signs its requests, and its SP metadata carries the certificate to check them with.

Names are optional. By Dawn reads a `name` or `displayName` attribute (or Microsoft's `displayname` claim), or joins
the standard `givenname` and `surname` claims.

### Certificates

Your provider signs with a certificate that eventually expires, and when it does, sign-in stops.
A connection holds up to two certificates, so you can replace one without a gap:

1. Create the new certificate in your provider, without making it active yet.
2. In By Dawn, choose **Add a second certificate**, paste the new one and choose **Save changes**. By Dawn now trusts
   both.
3. Make the new certificate active in your provider.
4. In By Dawn, remove the old certificate and choose **Save changes**, so the connection stops trusting it.

### ADFS

In ADFS Management:

1. Under **Relying Party Trusts**, choose **Add Relying Party Trust**, pick **Claims aware**, and
   choose **Import data about the relying party published online**. Paste By Dawn's **SP metadata URL**.

2. Pick an **access control policy**, such as **Permit specific group**, to choose who may sign
   in to By Dawn.

3. Edit the trust's **claim issuance policy** and add two rules:
   - **Send LDAP Attributes as Claims**: from Active Directory, map **E-Mail-Addresses** to
     **E-Mail Address**.
   - **Transform an Incoming Claim**: transform **E-Mail Address** into **Name ID**, with the
     **Email** format.

4. Give By Dawn your ADFS metadata. Open
   `https://<your ADFS host>/FederationMetadata/2007-06/FederationMetadata.xml`, copy the XML, and paste it
   into By Dawn as in step 4 above.

ADFS signs the assertion by default, which is what By Dawn needs.

## OpenID Connect

Any provider that follows OpenID Connect Discovery works. By Dawn reads your provider's settings and
signing keys from `<issuer>/.well-known/openid-configuration`, so you give By Dawn only three values.

1. In By Dawn, pick **OpenID Connect (OIDC)**, name the connection and choose **Create draft**.

2. In your provider, create a **web** (confidential) client that uses the **authorization code**
   flow, and add By Dawn's **Redirect URI** to its allowed redirect URIs.

3. Paste the provider's issuer into **Issuer URL** and the client's ID into **Client ID**, and choose **Save
   changes**. The issuer must match the `iss` value in your provider's ID tokens exactly, down to a trailing
   slash. Paste the client secret into the client secret box and choose **Save secret**.

4. Allow the people or groups who should use By Dawn, then choose **Test connection** in By Dawn and
   **Activate**.

What By Dawn asks for and checks:

- **Scopes** `openid email profile`, unless you set **Scopes (optional)**. By Dawn reads the `email` claim from the
  ID token, or from your provider's userinfo endpoint when the token has none. It must be at one of your
  verified domains, and if your provider says `email_verified` is `false`, By Dawn refuses the sign-in.
- **How By Dawn authenticates to the token endpoint**: **Token endpoint authentication** is
  `client_secret_basic (default)`. Pick `client_secret_post` if your provider only accepts the secret in the
  request body.
- **PKCE** (`S256`) and a **nonce** on every sign-in, so a stolen code or token can't be replayed.
  Most current providers support both, and older ones may need PKCE switching on.
- **A signed ID token** whose issuer and audience match the connection, signed with RS256, PS256 or ES256 using
  a key your provider publishes.

> **Use your own issuer:** Some providers offer a shared, multi-company issuer as well as one for your organization alone.
> Always use your organization's own. A shared one would accept sign-ins from accounts that aren't
> yours.

## Where to go next

- [SCIM provisioning](https://docs.bydawn.com/scim/): let your identity provider add and remove your people in By Dawn.

Source: https://docs.bydawn.com/sso-generic-saml/