Okta

This page helps you connect By Dawn to Okta. At the end, people at your company sign in to By Dawn with their Okta account, and the people you assign to the app in Okta are the ones who can.

You’ll work in two places at once: the Okta Admin Console, and Settings›, then Organization›, then Single sign-on in By Dawn. Single sign-on explains the By Dawn side once, so this page only says which value goes where.

Before you start

• Verify your email domain in By Dawn.
• You need to be the organization’s owner in By Dawn, and an Okta admin who can create app integrations.
• Pick OIDC unless you have a reason to use SAML (see OIDC or SAML?).

Set up OIDC (recommended)

1. In By Dawn, under How does your identity provider connect?, pick OpenID Connect (OIDC), name the connection Okta and choose Create draft. Keep the page open, because you’ll need its Redirect URI (sign-in redirect / callback URL).

2. In the Okta Admin Console, go to Applications › Applications and choose Create App Integration. Pick OIDC - OpenID Connect, then Web Application, and choose Next.

3. Fill in the new app:

   • App integration name: SAW, or whatever your people will recognise.
   • Grant type: leave Authorization Code ticked. By Dawn doesn’t need any other.
   • Sign-in redirect URIs: replace the example with By Dawn’s Redirect URI.
   • Sign-out redirect URIs: remove the example. By Dawn doesn’t use one.
   • Assignments: choose who may sign in to By Dawn. Limit access to selected groups keeps it to the groups you pick.

   Choose Save.

4. On the app’s General tab, copy the Client ID into By Dawn’s Client ID. Paste the Client secret into By Dawn’s client secret box and choose Save secret.

5. For By Dawn’s Issuer URL, use your Okta domain with https:// in front, such as https://acme.okta.com. That’s what you see in the Admin Console’s address bar, without -admin. If your team uses a custom authorization server instead, use its issuer, which looks like https://acme.okta.com/oauth2/default. Choose Save changes.

6. In By Dawn, choose Test connection, then Activate.

Leave Scopes (optional) empty. By Dawn then asks Okta for openid email profile, which every Okta app may use without extra setup.

Set up SAML

1. In By Dawn, pick SAML 2.0, name the connection and choose Create draft. Keep the page open, because you’ll need its ACS URL (single sign-on URL) and SP entity ID (audience).

2. In the Okta Admin Console, go to Applications › Applications, choose Create App Integration, pick SAML 2.0 and choose Next. Give the app a name and choose Next.

3. Under SAML Settings, fill in:

   Okta field	Value
   Single sign-on URL	By Dawn’s ACS URL, with Use this for Recipient URL and Destination URL ticked
   Audience URI (SP Entity ID)	By Dawn’s SP entity ID
   Name ID format	EmailAddress
   Application username	Email

   Leave Show Advanced Settings as it is. Okta signs the assertion by default, and By Dawn requires that.

4. Under Attribute Statements, add email → user.email. To have By Dawn fill in people’s names, add name → user.firstName + " " + user.lastName too.

5. Choose Next, answer Okta’s feedback question, and choose Finish.

6. On the app’s Sign On tab, open the Metadata URL and copy the XML it shows. In By Dawn, paste it into Paste your IdP’s metadata XML (optional) and choose Fill in from metadata. By Dawn fills in the IdP entity ID (issuer), IdP sign-in URL and IdP signing certificate. Check them, then choose Save changes.

7. On the Assignments tab, assign the people or groups who may sign in to By Dawn.

8. In By Dawn, choose Test connection, then Activate.

When Okta’s certificate changes

Okta signs with a certificate that eventually expires. Before it does, generate a new one on the app’s Sign On tab under SAML Signing Certificates. In By Dawn, choose Add a second certificate, paste the new one and choose Save changes. By Dawn then trusts both, so nobody is turned away while you switch Okta over to the new certificate. Once Okta uses it, remove the old one in By Dawn.

The Okta dashboard tile

Okta shows a SAML app on your people’s dashboard, and that tile starts the sign-in from Okta, which By Dawn refuses (see How your people sign in). So:

• on the SAML app’s General tab, under App Settings, tick Do not display application icon to users;
• if you’d like a tile, add a Bookmark App that opens your organization’s SSO address (see How your people sign in).

An OIDC app has no tile while Login initiated by is left at App Only, so leave it there and use a Bookmark App for the tile.

If something goes wrong

What happens	What to check
Okta says the person isn’t assigned to the app	Assign them, or one of their groups, on the app’s Assignments tab.
By Dawn says Okta “signed you in with an email address outside this organization’s verified domains”	Check the person’s Primary email in Okta, or verify that domain.
Okta says the redirect URI isn’t valid	The Sign-in redirect URI must match By Dawn’s Redirect URI exactly. Copy it again.
By Dawn “couldn’t accept the identity provider’s response” for a SAML app	By Dawn has an old certificate. Paste the app’s metadata again, or add the new certificate.
By Dawn refuses a sign-in started from the Okta dashboard	Expected: start from By Dawn instead. See the dashboard tile.

Tip

Test connection in By Dawn signs you in through the connection without affecting anyone else, so try it before asking people to sign in.

Where to go next

• SCIM provisioning: let Okta add and remove your people in By Dawn, and map Okta groups to By Dawn roles.