This guide connects Nokku to your company’s identity provider, like Okta, Entra ID, Google Workspace or Keycloak. Afterwards people sign in with their company account, and leaving the company also ends their Nokku access.
You need to be the workspace owner. A provider vouches for every account that signs in through it, so no other role can change these settings. Everyone from viewer up can look at them.
Add your identity provider
A workspace can have several providers, all OpenID Connect. Create an app in your identity provider, then add it on the Single sign-on settings page:
- Issuer URL is where the provider’s discovery document lives, at
/.well-known/openid-configurationunder it. - Client ID and client secret come from the app you created.
- Name is the button label on the sign-in page.
- Redirect URI is
<your workspace address>/oidc/callback. The settings page shows it, register it with the provider.
Once it’s set up, the provider shows up as a button on the sign-in page.
Who can sign in through it
What happens on the first sign-in depends on Create accounts on first sign-in:
- On: someone the provider knows but Nokku does not gets a
memberaccount. Leave it on for a company provider, so onboarding is one sign-in. - Off: only people who already have an account here get in. Invite them first.
An existing account is matched by email address, but only when the provider says it verified that address. Some providers, like Entra ID, never say so. For a directory you run yourself, the provider’s settings let the owner trust its addresses anyway. Never do that for a provider where people pick their own address. After the first sign-in the provider’s account is linked to the Nokku account, and the email no longer matters.
The owner account is never linked by email. The owner links a provider once, while signed in, on their profile.
One workspace, one set of accounts
Accounts belong to the workspace. A person in two companies has two accounts, one per workspace, and your provider only ever sees yours.
Require single sign-on
With Require single sign-on turned on, your providers become the only way in. Passkeys and email links stop working for everyone but the owner, and the sessions they started are signed out, in the browser and in nk.
Turn it on once your own account has signed in through the provider, so you know it works. It may not be enabled on every instance.
The owner is the way back in
The owner keeps their passkey and email links, so a broken provider never locks the workspace. Protect the owner’s mailbox and passkey like the provider itself. See Locked out by required SSO.
SCIM
SCIM lets your identity provider manage people in Nokku automatically. Create a SCIM token on the SCIM tab of the single sign-on page and give your provider the base URL and token it shows. Then:
- New people in your provider get a Nokku account.
- Groups in your provider become teams in Nokku, with the same members. Grant access to a team and it follows your provider.
- Deactivating or removing someone in your provider switches their account off. They can’t sign in, and servers running
nokkudstop accepting them right away. Their grants stay, so reactivating them restores the access they had. - The workspace owner is the exception. Transfer ownership first.
SCIM may not be enabled on every instance.
Under the hood
- The SCIM endpoint is
<your workspace address>/scim/v2. A token only works on the workspace that issued it. - OIDC uses the authorization code flow with PKCE and a nonce, and checks the issuer on the way back. Client secrets are stored encrypted.
- A self-hosted core reaches a provider on a private address, like one on your own network. The hosted service only reaches public addresses.
- On a self-hosted core, Google and Microsoft can be seeded as providers through the environment, see the core README.