# Okta (https://docs.fuser.studio/docs/teams/sso/okta)

Okta works with Fuser over either protocol. **SAML 2.0** is the more common choice for workforce identity; **OIDC** is simpler to configure and rotates its secret rather than a certificate. Either is fine — pick one, not both.

        ### Create the application [#create-the-application]

        In the Okta Admin Console, go to **Applications** → **Applications** → **Create App Integration**. Choose **SAML 2.0** and continue.

        Name it (for example, `Fuser`) and continue to **Configure SAML**.

        ### Configure SAML with temporary URLs [#configure-saml-with-temporary-urls]

        Okta will not let you finish the wizard without a **Single sign-on URL** and an **Audience URI**, and you cannot get Fuser's real values until the provider exists. Break the loop on Okta's side — these two fields stay editable afterwards, and Fuser's do not.

        Put a placeholder in both for now:

        | Okta field                      | Temporary value                         |
        | ------------------------------- | --------------------------------------- |
        | **Single sign-on URL**          | `https://example.fuser.studio/acs`      |
        | **Audience URI (SP Entity ID)** | `https://example.fuser.studio/audience` |

        Leave **Use this for Recipient URL and Destination URL** checked. Set **Name ID format** to **EmailAddress** and **Application username** to **Email**.

        Everything else on this screen is final, so fill it in properly now. Add three **Attribute Statements** — the **Name** column is what Fuser reads, matched exactly:

        | Name        | Value            | Required |
        | ----------- | ---------------- | -------- |
        | `email`     | `user.email`     | Yes      |
        | `givenName` | `user.firstName` | No       |
        | `surname`   | `user.lastName`  | No       |

        Leave the **Name format** as **Unspecified**. Finish the wizard.

        ### Collect Okta's details [#collect-oktas-details]

        Open the application's **Sign On** tab and click **View SAML setup instructions**. It gives you:

        | Fuser field             | Okta calls it                            |
        | ----------------------- | ---------------------------------------- |
        | **Sign-on URL**         | **Identity Provider Single Sign-On URL** |
        | **Issuer**              | **Identity Provider Issuer**             |
        | **Signing certificate** | **X.509 Certificate**                    |

        > [!NOTE] An `http://` issuer is correct
>
> Okta emits entity IDs like `http://www.okta.com/exk1a2b3c4`. That is an identifier, not a URL Fuser fetches, so the `http://` scheme is expected. Paste it exactly — the match is byte for byte.

        ### Register the provider in Fuser [#register-the-provider-in-fuser]

        In Fuser, open **Settings** → **Workspace** → **Security** → **Single Sign-On**, choose **SAML**, and enter your email domain along with the three values above. Click **Add provider**.

        Enter the real values here — a registered provider cannot be edited, and replacing it changes Fuser's endpoint URLs. See [Provider settings are final](https://docs.fuser.studio/docs/teams/sso.md#provider-settings-are-final).

        ### Replace Okta's placeholder URLs [#replace-oktas-placeholder-urls]

        Back in Okta, go to the application's **General** tab → **SAML Settings** → **Edit**, and swap the two placeholders for the real values from Fuser's provider card:

        | Okta field                      | Paste from Fuser's provider card |
        | ------------------------------- | -------------------------------- |
        | **Single sign-on URL**          | **ACS URL**                      |
        | **Audience URI (SP Entity ID)** | **Entity ID / Audience URI**     |

        Fuser does not support IdP-initiated sign-in, so the Fuser tile on the Okta dashboard will not work — members sign in from Fuser.

        ### Assign people [#assign-people]

        On the application's **Assignments** tab, assign the users or groups who should have access.

        ### Create the application [#create-the-application-1]

        In the Okta Admin Console, go to **Applications** → **Applications** → **Create App Integration**. Choose **OIDC - OpenID Connect**, then **Web Application**, and continue.

        Name it (for example, `Fuser`) and leave **Authorization Code** as the grant type.

        ### Register the provider in Fuser [#register-the-provider-in-fuser-1]

        You need three values from Okta:

        | Fuser field       | Where to find it                                                                                                                                         |
        | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
        | **Issuer**        | Your Okta domain, `https://acme.okta.com`, for the org authorization server — or `https://acme.okta.com/oauth2/<authorizationServerId>` for a custom one |
        | **Client ID**     | The application's **General** tab                                                                                                                        |
        | **Client secret** | The application's **General** tab                                                                                                                        |

        In Fuser, open **Settings** → **Workspace** → **Security** → **Single Sign-On**, choose **OIDC**, enter your email domain and these three values, and click **Add provider**.

        Fuser reads the issuer's discovery document during registration, so the issuer must be reachable over public HTTPS.

        ### Add the redirect URI [#add-the-redirect-uri]

        Copy **Redirect URI** from Fuser's provider card into the Okta application's **Sign-in redirect URIs** field, and save.

        Fuser does not support IdP-initiated sign-in. Set **Login initiated by** to **App Only** and leave **Initiate login URI** empty — clearing the URI alone is not enough, since the other setting is what offers the Okta dashboard tile. Members sign in from Fuser.

        ### Assign people [#assign-people-1]

        On the application's **Assignments** tab, assign the users or groups who should have access.

    > [!NOTE] Custom authorization servers
>
> `default` is the id of the authorization server Okta pre-creates, not a keyword — a custom server has its own id, and the issuer must carry that id. A custom server also enforces its own **access policy**, so it must have a rule that admits this application, or the token request is refused even with correct credentials.

    Fuser always requests the `openid`, `email`, `profile`, and `offline_access` scopes. Grant the first three on the application, and enable the **Refresh Token** grant type so `offline_access` is permitted — an application that refuses the scope fails the authorization request.

## Verify the domain and test [#verify-the-domain-and-test]

Whichever protocol you chose, add the TXT record shown on Fuser's provider card, wait for the card to flip to **Verified — SSO active**, then sign in from Fuser with an Okta-managed address on that domain.

See [Verifying the domain with DNS](https://docs.fuser.studio/docs/teams/sso.md#verifying-the-domain-with-dns) for the details.

## Rotating credentials [#rotating-credentials]

* **SAML** — Fuser stores the certificate you pasted and does not follow Okta's metadata, and holds only one. When Okta's signing certificate rolls, remove the provider and add it again with the new one; expect an interruption, since Okta publishing both certificates does not help a service provider that trusts one.
* **OIDC** — Fuser never shows a saved client secret again. To rotate it, generate a new secret in Okta and re-add the provider.

Removing and re-adding mints new endpoint URLs and a new DNS record, so plan on re-pasting them in your IdP and verifying the domain again — see [Provider settings are final](https://docs.fuser.studio/docs/teams/sso.md#provider-settings-are-final).

## Troubleshooting [#troubleshooting]

    Okta rejects the sign-in before it reaches Fuser. Add the member on the application's **Assignments** tab.

    Use **Identity Provider Issuer** from the SAML setup instructions, including its `http://` scheme. Do not substitute your Okta org URL.

    The `givenName` and `surname` attribute statements are missing from the SAML app, or — on OIDC — the `profile` scope was removed from the application's grants.

    Fuser fetches the discovery document, so the issuer must resolve publicly over HTTPS. A custom authorization server URL must include the `/oauth2/<id>` path; the bare org URL only works with the org authorization server.

## What's Next? [#whats-next]

  - [SSO overview](https://docs.fuser.studio/docs/teams/sso.md): Domain verification, enforcement, and what members see.

  - [Members](https://docs.fuser.studio/docs/teams/members.md): Roles, invitations, and seat management.