Other identity providers

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?). Single sign-on explains the By Dawn side of a connection once, so this page covers your provider’s side.

Before you start

• Verify your email domain 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).

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).
• 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).
• 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: let your identity provider add and remove your people in By Dawn.