# Okta

> Connect By Dawn to Okta with OIDC (recommended) or SAML, so your people sign in to By Dawn with their Okta account.

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 › Organization › Single sign-on** in By Dawn. [Single sign-on](https://docs.bydawn.com/sso/#add-a-connection)
explains the By Dawn side once, so this page only says which value goes where.

## 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 Okta admin who can create app integrations.
- Pick OIDC unless you have a reason to use SAML (see [OIDC or SAML?](https://docs.bydawn.com/sso/#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](https://docs.bydawn.com/sso/#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](https://docs.bydawn.com/sso/#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](https://docs.bydawn.com/sso-domains/). |
| 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](#the-okta-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](https://docs.bydawn.com/scim/): let Okta add and remove your people in By Dawn, and map Okta groups to By Dawn roles.

Source: https://docs.bydawn.com/sso-okta/