Skip to content

Single sign-on

Single sign-on (SSO) is a section of a company’s Settings tab: People on your company’s email domains sign in to Plune through your identity provider (SAML). It works by email domain. Once the company has proved that a domain is its own, a person with an address on that domain signs in through the company’s identity provider, and the company’s owner can make that the only way in.

Single sign-on is an add-on of the Team plan and is included in Enterprise. A company without it reads not in your plan beside the section’s title, with Request a change. The add-on, +$5 a person a month, is not part of the card payment for Team: it is switched on by hand. Your company’s plan is on its Plan & usage; prices are on Plans and limits.

Company roleThe section
Ownersets it up: everything on this page
Managerreads it: whether Sign in through SSO and Require SSO are on, and the email domains, each verified or not verified. No field, switch or button
Member, Read-onlyno Settings tab; its address opens the company’s Projects

A manager reads The owner of Acme QA sets single sign-on up. You see whether it is on.

The Single sign-on (SSO) section as a manager sees it, marked on: The owner of Acme QA sets single sign-on up. You see whether it is on.; Sign in through SSO On; Require SSO Off; Email domains: example.com, verified. The Single sign-on (SSO) section as a manager sees it, marked on: The owner of Acme QA sets single sign-on up. You see whether it is on.; Sign in through SSO On; Require SSO Off; Email domains: example.com, verified.

Plune’s side of SAML asks four things of the identity provider:

  • It signs its responses or its assertions, with SHA-256. An unsigned response is refused, and so is one signed with an algorithm Plune does not accept, such as SHA-1.
  • It sends the person’s email address, as the NameID or as an attribute.
  • The sign-in starts at Plune: Plune sends the request, and the provider answers it. A response that answers no request of Plune’s is refused, so a tile in the provider’s portal opens Plune’s start address (see How people sign in).
  • It returns the RelayState that Plune sent, unchanged.

The domain is your company’s own: a mail provider’s domain, such as gmail.com, cannot be added.

  1. Open the company, then Settings. The section reads Single sign-on (SSO), marked not set up.

  2. 1 · Give these to your identity provider holds two addresses, each with copy: the Entity ID (Audience) — also the metadata address and the ACS URL (Reply URL). Make a SAML application for Plune in your identity provider with them. Plune makes both from its own address and the company’s id, so there is nothing to type; the entity ID is also where the provider can read Plune’s metadata.

  3. In 2 · Your identity provider, paste the provider’s metadata into Metadata XML (optional): Paste it and Plune fills the three fields below. Plune keeps the fields, not the XML. The three are IdP entity ID (Issuer), IdP sign-in URL (an https address; from the metadata, the HTTP-Redirect sign-in address, else the first one listed) and IdP certificate. XML that Plune cannot read says Plune could not read this XML. Fill the three fields below by hand., and you fill them from the provider’s page.

  4. Choose what a newcomer gets. New people join as is Member or Read-only, never Manager or Owner. Add people on first sign-in, off at first: Someone from a verified domain who is not in Acme QA yet joins it as Member the first time they sign in. Off: only people already in the company or invited get in.

  5. In 3 · Email domains, type a Domain and press Add domain. A company holds up to 20.

  6. Press Save.

The Single sign-on (SSO) section marked not set up. 1 · Give these to your identity provider: Entity ID (Audience) — also the metadata address, https://beta-api.plune.ai/v1/auth/sso/ and the company's id, /metadata, and ACS URL (Reply URL), the same address ending in /acs, each with copy. 2 · Your identity provider: Metadata XML (optional) with the provider's XML pasted; IdP entity ID (Issuer) https://idp.example.com/saml/metadata and IdP sign-in URL https://idp.example.com/saml/sso, filled from it; IdP certificate, a PEM certificate; New people join as Member; Add people on first sign-in, off. The Single sign-on (SSO) section marked not set up. 1 · Give these to your identity provider: Entity ID (Audience) — also the metadata address, https://beta-api.plune.ai/v1/auth/sso/ and the company's id, /metadata, and ACS URL (Reply URL), the same address ending in /acs, each with copy. 2 · Your identity provider: Metadata XML (optional) with the provider's XML pasted; IdP entity ID (Issuer) https://idp.example.com/saml/metadata and IdP sign-in URL https://idp.example.com/saml/sso, filled from it; IdP certificate, a PEM certificate; New people join as Member; Add people on first sign-in, off.
The metadata pasted: Plune filled the three fields from it.

The certificate is the provider’s X.509 certificate, PEM or base64, never a private key. The field takes up to five at once, so a new certificate goes in next to the old one before the old one is removed. One Plune cannot read is refused under the field: This is not a certificate Plune can read. Paste the identity provider’s X.509 certificate (PEM or base64) — never a private key.

After Save the section shows the Identity provider card: the IdP entity ID, each Certificate with its subject and the day it is valid until, and what new people join as. Edit opens the fields again.

A domain that is not verified shows the DNS record that proves it is the company’s: Add this TXT record at your DNS provider, then check again.

TypeTXT
Name_plune-sso. and the domain — _plune-sso.example.com
Valueplune-sso-verification= and a token of that domain — copy it from the section

Add the record at your DNS provider, then press Check again. While DNS has not got it yet, the section says The TXT record was not found yet. DNS can take a while to update — check again later.; when DNS cannot be asked, The DNS record could not be read. Try again later. A record that is found marks the domain verified.

The Single sign-on (SSO) section marked off. The Identity provider card with Edit: IdP entity ID https://idp.example.com/saml/metadata, Certificate CN=idp.example.com · valid until Oct 31, 2028, New people join as Member. Email domains: example.com, not verified, with Remove; Add this TXT record at your DNS provider, then check again.; Type TXT, Name _plune-sso.example.com and Value plune-sso-verification= and a token, each with copy; Check again. Below, the Sign in through SSO switch, greyed: Verify a domain of the company before switching single sign-on on. The Single sign-on (SSO) section marked off. The Identity provider card with Edit: IdP entity ID https://idp.example.com/saml/metadata, Certificate CN=idp.example.com · valid until Oct 31, 2028, New people join as Member. Email domains: example.com, not verified, with Remove; Add this TXT record at your DNS provider, then check again.; Type TXT, Name _plune-sso.example.com and Value plune-sso-verification= and a token, each with copy; Check again. Below, the Sign in through SSO switch, greyed: Verify a domain of the company before switching single sign-on on.
A domain waits for its TXT record; the switch waits for the domain.
  • A domain another company has already verified cannot be verified again.
  • Keep the record. About once an hour Plune asks DNS again about the domains verified more than a day ago. A domain whose record has gone loses its verification, and when the company has no verified domain left, Require SSO goes off.
  • Remove takes a domain off the list. When it was the last verified one, single sign-on and Require SSO both go off.
  1. Turn on Sign in through SSO. Until a domain is verified the switch is grey: Verify a domain of the company before switching single sign-on on. Press Save.

  2. Test sign-in appears under the switch. Press it: Plune sends you to your identity provider. Sign in there as yourself, with your own address on a verified domain.

  3. Back in Plune, Test sign-in reads passed: You signed in through your identity provider as the owner. A change to the identity provider asks for it again.

A refused test reads refused, with the reason in one sentence: Your test sign-in at the time was refused: and the reason from the table below. Until your own test passes, the section shows the last refused sign-in since the settings were saved.

A change to the IdP entity ID, the IdP sign-in URL or the certificates asks for the test again, and it switches Require SSO off until the test passes again.

Require SSO turns on only after your test has passed: Sign in through the identity provider as the owner before requiring single sign-on. Turned on, it says what it does: People on example.com then sign in only through your identity provider, and their email-link sessions end. Guests invited by name with other addresses keep the email link. Like the other switch, it waits for Save.

The Single sign-on (SSO) section marked on. The Identity provider card as above, with Edit. Email domains: example.com, verified, with Remove. Sign in through SSO on; Test sign-in, passed: You signed in through your identity provider as the owner. A change to the identity provider asks for it again., with Test sign-in again. Require SSO switched on: People on example.com then sign in only through your identity provider, and their email-link sessions end. Guests invited by name with other addresses keep the email link.; a note: You, the owner, keep the email link as an emergency way in. Each such sign-in is written to the company’s log and mailed to its managers.; a ticked box: Also revoke the 3 API tokens of people on example.com — their CLI and CI uploads stop until they make new ones.; Save below. The Single sign-on (SSO) section marked on. The Identity provider card as above, with Edit. Email domains: example.com, verified, with Remove. Sign in through SSO on; Test sign-in, passed: You signed in through your identity provider as the owner. A change to the identity provider asks for it again., with Test sign-in again. Require SSO switched on: People on example.com then sign in only through your identity provider, and their email-link sessions end. Guests invited by name with other addresses keep the email link.; a note: You, the owner, keep the email link as an emergency way in. Each such sign-in is written to the company’s log and mailed to its managers.; a ticked box: Also revoke the 3 API tokens of people on example.com — their CLI and CI uploads stop until they make new ones.; Save below.
Require SSO, switched and not yet saved, with the domain's API tokens to revoke.

Once it is saved, for a person with an address on a verified domain:

  • The email link is not sent, and the sign-in form answers as it always does. The code from the mail does not open a session either, nor does sign-in with Google or GitHub where Plune offers it.
  • Sessions that did not start through single sign-on end. A request with one is answered 401 with the code sso_required and a startUrl, the address to sign in through the company.
  • API tokens keep working: a token is not a session. When the people of the domain hold tokens, a box under the switch offers to end them in the same save, ticked: Also revoke the N API tokens of people on the domain — their CLI and CI uploads stop until they make new ones. Untick it to keep them.

People invited with addresses on other domains keep the email link.

The owner’s session from the email link survives Require SSO for as long as they are the owner. The same holds for the owner’s code from the mail, and for Google or GitHub sign-in where Plune offers it.

Sign-in through the company starts at Plune’s start address for the domain, the one Test sign-in opens: Plune’s API address followed by /v1/auth/sso/start?domain= and the domain (or ?email= and the person’s address). It sends the browser to the identity provider; after the provider, the person lands in Plune signed in. Give that address to the Plune tile in your provider’s portal.

  • The session ends no later than the identity provider says the provider’s own session ends.
  • A person whose name is empty in Plune takes the name the provider sends.
  • Waiting invitations of the address are accepted at the first sign-in, as with an email link. With Add people on first sign-in on, somebody who is not in the company yet joins it with the role of New people join as.
  • When the company has no free seat for that newcomer, the sign-in is refused, and the person reads Your company has no free seat for you in Plune, so you were not signed in. Ask the owner of your company in Plune for a seat.
  • A browser still signed in to Plune as somebody else is refused too: This browser is still signed in to Plune as someone else. Choose Open Plune, then Sign out in Account (the avatar), and sign in through your company again.

Any other refusal reads the same for the person: Sign-in through your company was refused. The reason is not shown here: ask the owner of your company in Plune to check its single sign-on (SSO). The owner finds the reason under Test sign-in.

What Test sign-in says after was refused:, by the reason Plune keeps in the company’s log:

ReasonWhat the owner reads
tierthe company’s plan no longer includes single sign-on.
disabledsingle sign-on was off when the response came. Switch it on, then test again.
no_pending_requestPlune was not waiting for this sign-in. Start the test with the button below.
relay_statethe response did not bring back the RelayState Plune sent. The identity provider must return it unchanged.
login_bindingthe response came to a browser that did not start the sign-in. Start the test with the button below, in this browser.
session_conflictthis browser was signed in to Plune as someone else. Sign out, then test again.
suppressedmany refused sign-ins came in a short time, and not every one was written down. Test again in a few minutes.
signaturethe response was not signed with a certificate Plune has. Add the identity provider’s current certificate, then test again.
unsignedthe response was not signed. Make the identity provider sign its responses or assertions.
weak_algorithmthe response was signed with an algorithm Plune does not accept, such as SHA-1. Switch the identity provider to SHA-256.
issuerthe response came from an issuer other than the IdP entity ID saved here. Check the IdP entity ID.
audiencethe response was meant for another service. Give the identity provider the Entity ID (Audience) above.
destinationthe response was sent to another address. Give the identity provider the ACS URL above.
recipientthe response named another recipient. Give the identity provider the ACS URL above.
in_response_tothe response answered a request Plune did not send. Start the test with the button below.
expiredthe response, or the identity provider’s session, had expired. Check the identity provider’s clock, then test again.
not_yet_validthe response was dated in the future. Check the identity provider’s clock.
too_oldthe response was too old when it came. Check the identity provider’s clock, then test again.
replaythe same response came twice. Test again.
statusthe identity provider refused the sign-in itself. Check that you are assigned to the Plune app there.
no_emailthe response carried no email address. Send the email as the NameID or as an attribute.
unverified_domainthe email address is not on a verified domain of the company. Verify its domain above.
public_domainthe email address is on a mail provider’s domain, such as gmail.com. Sign in with a work address.
doctypethe response held a DOCTYPE, which Plune never accepts. Check the identity provider’s SAML settings.
malformedPlune could not read the response. Check the identity provider’s SAML settings.
too_largethe response was larger than Plune accepts. Send fewer attributes.
account_deletedthe account of that address is in the Bin. Restore it, then test again.
no_seatthe company had no free seat for the person who signed in. Free a seat or change the plan, then test again.

Single sign-on works while the company’s plan includes it: an active plan, or the 14 days after a plan ends. When the plan no longer includes it, sign-in through the identity provider and Require SSO stop by themselves, so nobody is locked out: the people of the domain sign in with the email link again.

The section’s routes take your signed-in session, not an API token: a token could otherwise point the company’s sign-in at another identity provider. A request without a session is 401 sign in required.

RouteWhoWhat
GET /v1/companies/{id}/ssoowner, managerthe owner gets every value — the two addresses, the provider’s fields and certificates, the switches, the domains with their TXT records; a manager gets configured, enabled, enforced and the domains, each with verified
PUT /v1/companies/{id}/ssoownersaves the provider: idpEntityId, idpSsoUrl and idpCerts are sent whole every time; enabled, enforced, defaultRole (member or reader), jit, emailAttribute, nameAttribute and signRequests are kept as they are when left out; revokeTokens: true also revokes the domain’s API tokens when the call leaves Require SSO on
POST /v1/companies/{id}/sso/domainsowner{ "domain": "example.com" } adds a domain → 201 with its record
POST /v1/companies/{id}/sso/domains/verifyowner{ "domain": "example.com" } asks DNS → 200; 409 sso_record_not_found with the record; 424 sso_dns_error
DELETE /v1/companies/{id}/sso/domains/{domain}ownerremoves a domain → 204
GET /v1/companies/{id}/sso/tokensowner, managerthe API tokens of the people on the verified domains
DELETE /v1/companies/{id}/sso/tokensowner, manager{ "confirm": N } revokes them all, N being the number you were shown; a list that changed since is 409 sso_confirm_mismatch with the new count
GET /v1/auth/sso/{companyId}/metadataanyonePlune’s SAML metadata for the company; 404 while its plan does not include single sign-on

The refusals:

AnswerWhen
403 company owner onlya write by somebody who is not the owner
403 company owner or manager onlya read by a member or a read-only person
403 tier_option_requiredthe company’s plan does not include single sign-on
400 sso_bad_certificatea certificate Plune cannot read
400 sso_public_mail_domaina mail provider’s domain
409 sso_domain_takena domain another company has verified
409 sso_limita 21st domain
409 sso_domain_requiredenabled with no verified domain
409 sso_enabled_requiredenforced while single sign-on is off
409 sso_test_login_requiredenforced before the owner’s test sign-in has passed
503 sso_signing_unavailablesignRequests on a server that cannot sign requests