Setting up single sign-on for Nanoru

This guide is for the IT team connecting Nanoru to your identity provider. When you've finished, your people sign in to Nanoru with their work account, and you can make that the only way into your organisation.

Single sign-on comes with the Team and Scale plans. An owner of your Nanoru organisation does the Nanoru side, at Admin → Single sign-on. Each step there that changes who can sign in asks them to confirm it's them first.

Nanoru connects to your provider with OpenID Connect, which Okta, Microsoft Entra ID and Google Workspace all offer. SAML isn't available yet.

1. Prove you control your email domain

  1. In Nanoru, under Your email domains, add your domain, for example example.com.
  2. Nanoru shows a TXT record. Publish it in your domain's DNS. The name is _nanoru-verification.example.com and the value starts nanoru-verification=.
  3. Press Verify. DNS changes can take up to an hour to be seen.

Nanoru checks the record again every day. Leave it in place: if it's gone for three days in a row, the domain stops counting as yours and the page says so.

Domains of free email services (Gmail, Outlook.com and the like) can't be verified. If another organisation has already verified your domain with Nanoru, remove their record from your DNS and press Verify again.

2. Create an app in your identity provider

Nanoru shows the values to copy under Add a connection, in your provider's own words. The redirect address is the same for every provider:

https://<your Nanoru address>/api/auth/sso/callback

Okta

  1. Applications → Create App Integration → OIDC - OpenID Connect → Web Application.
  2. Grant type: Authorization Code only.
  3. Sign-in redirect URIs: the redirect address above.
  4. Assign the app to the people or groups who use Nanoru.
  5. Copy the Client ID and Client secret into Nanoru. The issuer is your Okta address, for example https://your-company.okta.com.
  6. Once the connection exists, Nanoru shows its start address. Put it in Initiate login URI and set Login initiated by to Either Okta or App if you want an Okta dashboard tile.
  7. To give roles by group, add a groups claim to the ID token, and enter groups as the group claim in Nanoru.

Microsoft Entra ID

  1. App registrations → New registration. Platform: Web.
  2. Redirect URI (Web): the redirect address above.
  3. Certificates & secrets → New client secret. Copy its Value into Nanoru as the client secret, and the Application (client) ID as the client ID.
  4. The issuer is https://login.microsoftonline.com/<your tenant ID>/v2.0. Use your own tenant ID, not common or organizations.
  5. Token configuration → Add optional claim → ID: add email and xms_edov. Entra ID doesn't otherwise confirm that an address is verified, and Nanoru won't match sign-ins to accounts without that.
  6. For a My Apps tile, put Nanoru's start address in Branding & properties → Home page URL.
  7. To give roles by group, add the groups claim and enter groups in Nanoru.

Google Workspace

  1. In the Google Cloud console for your Workspace: APIs & Services → OAuth consent screen, user type Internal, so only your Workspace's accounts can sign in.
  2. Credentials → Create credentials → OAuth client ID → Web application.
  3. Authorized redirect URIs: the redirect address above.
  4. Copy the Client ID and Client secret into Nanoru. The issuer is https://accounts.google.com.

Nanoru accepts a Google sign-in only for an address on your own domain. Google doesn't tell Nanoru whether someone used a second factor, so if your organisation requires one in Nanoru, your people also set up a passkey or an authenticator app in Nanoru.

Another OpenID Connect provider

Create a confidential web application using the authorization code flow, with the redirect address above. It must sign ID tokens with a public key (RS256, ES256 or similar) and send email and email_verified. The issuer is the one in your provider's /.well-known/openid-configuration.

3. Choose who gets in, and as what

In Nanoru, when you add the connection:

  • Domains it serves: your verified domains whose people sign in through this provider.
  • Add people the first time they sign in: with this on, anyone your provider lets in, on those domains, gets a Nanoru account and joins your organisation. With it off, only people already in your organisation can sign in this way; invite the others.
  • Role for new people: viewer or editor.
  • Groups and roles: optionally, map group names to roles, one per line, such as Nanoru Editors = editor. A group you don't list gives the default role. Nobody becomes an owner unless a line says so. Roles are set the first time someone signs in; change them later on the Members page.

People outside your domains, such as freelancers, can still be invited by email and sign in with a password, an emailed link or a passkey.

4. Test, then switch it on

Press Test sign-in. You go to your provider, sign in, and come back to Nanoru. If it worked, press Switch on. If it didn't, Nanoru says why: usually a mistyped issuer or secret, or an address that isn't on a domain the connection serves.

Changing the issuer, client ID, secret or scopes later switches the connection off until you test it again.

5. Require single sign-on (optional)

When it's required, your members reach your organisation in Nanoru only after signing in through your provider. Their passwords, emailed links and passkeys still work for any other organisations they belong to.

Before you can require it, exempt at least one owner who has a Nanoru second factor (a passkey or an authenticator app). Exempt owners can still get in with their password or passkey and that second factor, so a provider outage or a broken setting doesn't lock you out.

When someone leaves

Remove them in your identity provider. They can't sign in again, but a Nanoru session they already have lasts until it ends: 12 hours unused, or 14 days at most. To shorten that, set Ask members to confirm it is them after this many hours on the Organisation page; after that time, people sign in through your provider again. You can also remove them on the Members page, which signs them out at once. With SCIM set up (below), unassigning or deactivating them in your provider removes them from your Nanoru organisation straight away.

Add and remove people automatically (SCIM)

With SCIM, your identity provider adds people to your Nanoru organisation when you assign them the app, and removes them when you unassign or deactivate them. SCIM comes with the Scale plan.

  1. An owner presses Set up SCIM on the Single sign-on page, on the connection whose people it should manage. Nanoru shows a base URL and a token. Copy both now: Nanoru keeps only a fingerprint of the token and can't show it again.
  2. Give them to your provider.
    • Okta: in the app's General settings, turn on SCIM provisioning. Under Provisioning → Integration, put the base URL in SCIM connector base URL, enter userName as the unique identifier field, tick Push New Users and Push Profile Updates, and choose HTTP Header authentication with the token. Then, under Provisioning → To App, turn on Create Users and Deactivate Users.
    • Microsoft Entra ID: open the app under Enterprise applications, then Provisioning, and set the mode to Automatic. Put the base URL in Tenant URL and the token in Secret Token, press Test Connection, save, and start provisioning.
    • Another provider: Nanoru speaks SCIM 2.0 for users and groups, with the token sent as a bearer token.

Nanoru adds people only on verified domains the connection serves, at the connection's role for new people, and only while your plan has room for them. When your provider removes someone, they leave your organisation and are signed out of it at once; their Nanoru account stays, as it may belong to other organisations too.

To give roles by group, push the groups to Nanoru as well and list them in the connection's Groups and roles, by name or by your provider's id for the group. Each person then gets the most powerful role any of their groups maps to, or the role for new people if none does, and their role follows as you move them between groups. Without a mapping, SCIM leaves roles alone and you set them on the Members page.

SCIM never removes an owner or changes an owner's role, so whoever holds the token can't take the organisation from its owners. Owners are removed, or made something else, on the Members page.

A new token replaces the old one straight away. Turn off SCIM stops your provider adding or removing anyone, and removes nobody.

Who has signed in

The Single sign-on page lists who has signed in through which connection and when. Every sign-in attempt through your connections, including ones Nanoru refused, is in your audit log's sign-ins, kept for a year.