Single sign-on

What single sign-on does

Turn on single sign-on and the people in your organisation get into SkillsDB with the accounts your company already manages. One code path serves every provider: Zoho Directory, Okta, Microsoft Entra ID, Google Workspace, or anything else that speaks SAML 2.0. There is nothing provider-specific to buy or switch on.

Somebody signing in this way joins your organisation as a member, in that organisation only, with no workspace. Somebody an administrator removed is refused and stays removed; single sign-on is not a way back in past that decision. An invitation is.

• SAML 2.0 only. OpenID Connect is not supported.
• Both directions work. Your people can start from the tile in your identity provider, or type their work address on the SkillsDB log in page.
• The emailed six-digit code keeps working until you require single sign-on.

What you need

• The superadmin of the SkillsDB organisation. Single sign-on decides how everybody else gets in, so the page belongs to the one person who cannot be removed from the organisation.
• Administrator access to a SAML 2.0 identity provider, where you can create a custom application.
• An organisation with an email domain. SkillsDB takes the domain from the work address that created the organisation, and single sign-on admits only addresses on it, so one company’s identity provider can never mint a session for another company’s people.

Open Settings in your organisation and choose Single sign-on. If you do not see it, you are not the superadmin of this organisation.

What to give your identity provider

The Single sign-on page prints three values, each with a Copy button. They are built from your organisation’s slug, so they belong to your organisation alone and are safe to paste into your provider.

• Assertion Consumer Service URL, at https://skillsdb.so/api/sso/saml/your-org/acs. This is where your provider posts the assertion.
• Issuer, also called the Entity ID, at https://skillsdb.so/api/sso/saml/your-org/metadata. This is the name SkillsDB answers to.
• Service provider metadata, at the same https://skillsdb.so/api/sso/saml/your-org/metadata address. Providers that take a file can fetch or upload it from there. It is live from the moment your organisation exists, so you can hand it over before you have anything of your provider’s to save here.

Enlarge

Providers disagree about what to call these. Match them by meaning, not by wording: an Assertion Consumer Service URL is also called the Reply URL or the Single sign-on URL, and an Issuer is also called the Audience URI, the Identifier or the Entity ID.

Set up Zoho Directory

1. In the Zoho Directory Admin Panel, open Applications, choose Add Application, and create a Custom Application with SAML.
2. Type the SkillsDB Assertion Consumer Service URL into the field Zoho Directory calls Assertion Consumer Service URL.
3. Type the SkillsDB Issuer into the field Zoho Directory calls Issuer.
4. Save the application, then download its IdP metadata XML. Zoho Directory hands over a metadata.xml file and publishes no metadata URL.
5. Assign the application to the users or groups who should reach SkillsDB.
6. Back in SkillsDB, paste the contents of that metadata.xml into Your identity provider and save.

Set up Okta

1. In the Okta Admin Console, open Applications, choose Create App Integration, and choose SAML 2.0.
2. Put the SkillsDB Assertion Consumer Service URL in Single sign-on URL.
3. Put the SkillsDB Issuer in Audience URI (SP Entity ID).
4. Set the Name ID format to EmailAddress and the application username to the user’s email. Add firstName and lastName attribute statements if you want names filled in.
5. Assign the application to the people who should reach SkillsDB.
6. Copy the application’s identity provider metadata URL from the Sign On tab, paste it into Your identity provider in SkillsDB and save.

Okta signs the assertion and leaves the response unsigned, which SkillsDB accepts.

Set up Microsoft Entra ID

1. In the Microsoft Entra admin centre, open Enterprise applications, choose New application, then Create your own application, and create a non-gallery application.
2. Open Single sign-on and choose SAML.
3. Put the SkillsDB Issuer in Identifier (Entity ID).
4. Put the SkillsDB Assertion Consumer Service URL in Reply URL (Assertion Consumer Service URL).
5. Leave the unique user identifier claim as the user’s email address, and keep the givenname and surname claims if you want names filled in.
6. Assign the users and groups who should reach SkillsDB.
7. Copy the App Federation Metadata Url, paste it into Your identity provider in SkillsDB and save.

Set up Google Workspace

1. In the Google Admin console, open Apps, then Web and mobile apps, choose Add app, then Add custom SAML app.
2. On the Google Identity Provider details step, download the IdP metadata or copy its metadata URL. You will need it in the last step.
3. Put the SkillsDB Assertion Consumer Service URL in ACS URL.
4. Put the SkillsDB Issuer in Entity ID.
5. Map the primary email to the Name ID, and add first name and last name attributes as firstName and lastName if you want names filled in.
6. Turn the app on for the organisational units whose people should reach SkillsDB.
7. Back in SkillsDB, give Your identity provider the metadata URL you copied, or paste the metadata file you downloaded, and save.

Test the sign-in

Choose Test sign-in on the Single sign-on page. It runs the real flow against your real identity provider while the set-up is still switched off, so a mistyped URL or the wrong certificate costs nobody a sign-in. Nothing else can get in at that point: the button mints a ten-minute, one-use ticket, and only an assertion carrying that ticket is accepted against a set-up that is off.

1. Choose Test sign-in and complete the sign-in at your provider.
2. You come back to the Single sign-on page either way, and it says whether the test was accepted or refused.
3. If it was refused, the page names the reason, because you are the person who can fix it. Correct the set-up and run it again.
4. Once it is accepted, choose Turn on. Your identity provider now works for everybody in the organisation, and the emailed code still works too.

Status keeps two lines: Last sign-in, the time and address of the last assertion accepted here, and Last test, when you last ran Test sign-in and what it came to. A refused test is only ever explained to you. Everybody else sees the same sign-in failed message whatever went wrong, so a bad signature and an address on the wrong domain cannot be told apart from outside.

Require single sign-on

Require single sign-on when you want your identity provider to be the only way in. The emailed six-digit code stops working for that organisation’s members and administrators.

The superadmin keeps the emailed code whatever this switch says. That is the lock-out protection: an expired certificate or a sign-in URL that changed cannot shut an organisation nobody can reopen. The superadmin signs in with a code, fixes the set-up, and everybody else follows.

• Requiring single sign-on needs a real sign-in to have worked first.
• Switching single sign-on off switches the requirement off with it, so an organisation never sits with a requirement it cannot meet.
• Removing single sign-on entirely puts everybody back on the emailed code.

Rotate a certificate

SkillsDB holds up to two signing certificates for your organisation at once, which is how a provider rotates a signing key without costing anybody a sign-in. Add the new certificate while the old one is still listed, let your provider cut over, then save again with only the new one.

The simplest route is to save your provider’s metadata again once it advertises both certificates, since a metadata document carries them all. The Status card lists every certificate held: whose it is, and when it stops working. One inside thirty days of its end is marked Expires soon, and one already past it is marked Not usable, so a rotation that has been forgotten is visible before anybody is locked out.

Who gets an account

The first valid assertion for an address creates the SkillsDB login, if that person has none, and a member role in your organisation. That is all it creates: no workspace, no role above member, and nothing in any other organisation. Give someone a wider role, or access to a workspace, the way you always have, from Members.

The address must be on your organisation’s own domain. An assertion for an address on any other domain is refused, whoever signed it.

Troubleshooting

Every refusal answers the same way, a return to the log in page with a sign-in failed message, so that a bad signature, a stale assertion, a replayed one and an address on the wrong domain cannot be told apart from outside. Test sign-in is the exception: a run you started yourself comes back to the Single sign-on page and names the reason. The reason is written to the log either way.

• Sign-in fails for everybody, right after set-up. Check that the Issuer in SkillsDB matches the entityID your provider advertises, and that the certificate is the current signing certificate rather than an encryption one.
• Sign-in fails for one person. Check that their address is on your organisation’s domain, and that they were not removed from the organisation.
• The provider reports a bad audience or recipient. The Assertion Consumer Service URL and the Issuer must be pasted exactly as SkillsDB prints them, including the organisation in the path.
• Sign-in worked once and now fails. A posted assertion can be used once, and an assertion is only valid for a few minutes. Start the sign-in again rather than reloading or resubmitting.
• The provider signs nothing. SkillsDB accepts a signed assertion, a signed response, or both. It refuses a document with neither.
• The metadata URL will not load. It must be https, and it must not redirect off https. Paste the metadata document instead.
• Nothing at the address at all. The sign-in and assertion addresses answer not found until the set-up is complete, and for an organisation that has none. The metadata address is the exception: it answers for any organisation that exists, because everything in it is ours.