> For the complete documentation index, see [llms.txt](https://docs.onepub.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.onepub.dev/guides/okta-single-sign-on.md).

# Okta single sign-on

Connect your OnePub organisation to Okta using SAML single sign-on.

**Release availability:** Automatic bookmark sign-in and the **Copy organisation sign-in link** control described below belong to the upcoming release being validated for beta. They are not yet confirmed available in production. Use the controls shown by your current OnePub version until that release is available.

Use Okta to sign in to your OnePub organisation. SSO is available on Enterprise plans.

SSO controls sign-in. [SCIM provisioning](https://docs.onepub.dev/guides/scim-provisioning.md) adds and deactivates members and manages access. You can use either separately.

## 1. Get your OnePub settings

Sign in to OnePub as an organisation administrator and select your organisation. Open **My OnePub > Account > SSO > Configure SSO**.

The **OnePub settings** section contains the **ACS URL**, **SP entity ID** and a generated, read-only **Organisation code**. The code is eight characters long and stays the same when you rename your organisation.

Copy the ACS URL and SP entity ID into Okta. **Download OnePub settings for your provider** exports these service-provider settings as SAML metadata for providers that support importing them. It does not contain your provider's signing certificate. Keep this window open while you create the Okta application.

## 2. Set up your Okta application

Contact [OnePub support](https://docs.onepub.dev/faq/how-do-i-get-support.md) to confirm which OnePub integration is available for your environment. OnePub's reusable integration is being prepared for the Okta Integration Network (OIN); this guide does not announce a published catalog listing.

For an application created directly in your own Okta tenant, follow [Private Okta application](https://docs.onepub.dev/guides/okta-single-sign-on/okta-private-application.md). That page contains the manual SAML fields and the additional prerequisites for private SCIM provisioning. Return here after downloading the application's SAML metadata and assigning your pilot users.

The integration must send a **Persistent** NameID using `user.getInternalProperty("id")` as the custom application username, with `email` sent separately as `user.email`. Keep this stable ID aligned with SCIM `externalId` if you use provisioning.

## 3. Save the connection in OnePub

Return to **Configure SSO** in OnePub:

1. In the identity-provider section, upload the Okta metadata XML. Alternatively, enter its issuer, sign-in URL and public signing certificate.
2. Keep **Email attribute** set to `email` and click **Save configuration**.

After saving, expand **Connection details** and use **Copy organisation sign-in link** to share the link with members, then test the connection below.

If you also use SCIM, configure its `externalId` to match the Okta user ID sent as SAML NameID. OnePub checks these IDs automatically. Resolve any conflicts in the [SCIM sync review](https://docs.onepub.dev/guides/scim-provisioning.md#3-review-and-approve).

## 4. Test and require SSO

Click **Test connection** and complete Okta sign-in using the same administrator account. OnePub shows **Test sign-in successful** when the connection and your administrator access have been verified.

Ask the pilot members to use the organisation sign-in link and check their package access. OnePub links existing members automatically within this organisation; their roles and teams stay intact. Other users need an invitation or SCIM provisioning before they can join.

Until you require SSO, members can use it or their existing sign-in method.

When ready, run **Test connection** again, select **Require enterprise SSO**, and click **Save sign-in policy** within five minutes. Human members must use SSO for new sign-ins to this organisation. Existing web sessions and CLI tokens remain valid.

## Signing in

Use the organisation link or select **Sign in with Enterprise SSO** in OnePub and enter the organisation code. Start sign-in from OnePub; launching the application directly from the Okta dashboard is not supported.

### Bookmarking the organisation link

Bookmark `https://onepub.dev/sso/<organisation-code>` using the link copied from **Account > SSO > Connection details**. Opening it starts your organisation's provider sign-in without asking for the code. Bookmark this OnePub link, not the provider's temporary request or the sign-in completion page.

The link works in a new browser session and can be reused after cancelling a sign-in. Back returns to the page before the automatic redirect instead of immediately restarting sign-in. Reopen the bookmark to start another attempt. The code is public routing information: authentication, provider MFA, membership and required-SSO policies still apply. It does not expand an existing session's organisation access.

Renaming an organisation does not change its code. If a code is replaced or retired, ask the administrator for the current link. Old codes remain reserved and never redirect to another organisation. Invalid codes and unavailable connections offer another organisation or sign-in method without listing customers.

Links supplied by OnePub can retain an internal destination after sign-in. External destinations are rejected, and the destination still checks your permissions. A link cannot replace a pending invitation or fixed-organisation CLI login with a different organisation or return destination. Finish or restart the original invitation or CLI flow instead.

### Remembered sign-in and CLI access

The browser remembers your last successful organisation. Choose **Sign in with Enterprise SSO** to enter another code, or **Forget this organisation** to remove the shortcut. If you forget the code, use **Forgot your organisation code?** to request it by email.

An SSO sign-in grants access only to that OnePub organisation. It does not sign you into other organisations or authorise account-wide changes, such as changing your login email. Use your original account sign-in method for those changes.

For the CLI:

```sh
onepub login sso acme2345
```

Replace `acme2345` with your organisation's code. Open the printed URL and finish sign-in within five minutes. Future `onepub login` commands remember your choice. Use `onepub login --choose` to choose again. See [CLI login](https://docs.onepub.dev/guides/cli-integration/cli-tools.md).

The resulting OnePub token works with `dart pub get` and `dart pub publish`. CI/CD authentication is separate.

## Renewing certificates and changing settings

OnePub displays each signing certificate's expiry. To overlap certificates, add the new public certificate alongside the existing certificate in **Configure SSO**, save, then test after Okta starts signing with the new certificate.

While SSO is required, OnePub allows certificates to be added but prevents changes that replace the working connection. To remove a certificate or change the issuer, sign-in URL or email attribute, first turn off **Require enterprise SSO** and save. Make the changes, test them, then require SSO again.

Saving connection changes clears the previous test result and ends existing sessions. When SSO is optional, the setup administrator keeps their ordinary sign-in session. OnePub never turns off required SSO automatically if Okta is unavailable.

## Removing access or disconnecting

Suspending a person in Okta prevents new Okta sign-ins. It does not notify OnePub to revoke existing sessions or CLI tokens. Use [SCIM deactivation](https://docs.onepub.dev/guides/scim-provisioning.md#removing-access), or deactivate the member in OnePub and revoke their tokens.

To allow other sign-in methods, clear **Require enterprise SSO** and save. **Disconnect SSO** also disables the connection. Both actions warn that members suspended only in Okta may regain access through another method. SCIM-deactivated members remain inactive.

After disconnecting, members signed in through SSO must sign in again using another method. An administrator using ordinary sign-in stays signed in. To reconnect, save the provider configuration and test it before requiring SSO again.

## Troubleshooting

| Problem                                 | Check                                                                                                                      |
| --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| The SSO tab is missing                  | The selected organisation needs an Enterprise plan and you need administrator access.                                      |
| A member cannot sign in                 | Check their Okta assignment, OnePub membership and matching email on first sign-in.                                        |
| Test connection fails                   | Use the administrator account that started the test. System Administrator and CI/CD accounts cannot be used for this test. |
| OnePub will not require SSO             | Test the current saved configuration with your administrator account, then save the policy within five minutes.            |
| A remembered organisation stops working | Choose **Sign in with Enterprise SSO** and enter the code supplied by your administrator.                                  |
| Okta is unavailable and SSO is required | Contact OnePub support for recovery.                                                                                       |

Give [OnePub support](https://docs.onepub.dev/faq/how-do-i-get-support.md) the error reference displayed by OnePub when reporting a failed sign-in.
