Company login¶

With a company login, the people of your organisation sign in to OS with the account they already have at your own identity provider, such as Microsoft Entra ID, Google Workspace or Okta, through OpenID Connect or SAML. This page shows how to set up a company login, try it, require it, who may sign in without it, who may join by themselves and how to remove it again. There is no screen for this yet: an administrator uses OS's API, with the routes below.

Who may do what¶

An org-admin of the organisation can set up, change and remove the company login. Whoever sets it up must also be allowed to manage the domain it belongs to (Manage roles). Every member can read how the login stands.

An organisation has at most one company login. It belongs to one domain your organisation has proved, for example jansen.com (Domains and addresses). So prove the domain first.

Setting up an OpenID Connect login¶

1. At your identity provider, create an application for OS. You get a client id and a secret.

2. Set up the login with PUT /api/v1/organisations/{id}/company-login and the header If-Match: "0":

   Field	What you fill in
   kind	oidc
   display_name	the name on the sign-in page, at most 64 characters, for example Jansen
   domain	the proved domain, for example jansen.com
   authorization_url, token_url, jwks_url, issuer	your provider's addresses; they are in the provider's discovery document (/.well-known/openid-configuration)
   client_id, client_secret	what your provider gave you
   client_auth_method	client_secret_basic or client_secret_post, as your provider asks

3. OS answers 202 with the login, status pending. Read redirect_uri in the answer and add that address at your provider as the application's redirect address. It ends in /broker/os-<your organisation's id>/endpoint.

Every address must start with https://, name a host name (not an IP address), have no port but 443 and be at most 2,048 characters long. No answer ever contains the secret: OS keeps it encrypted until the login is active and then throws it away.

Setting up a SAML login¶

Set up the login with the same route and kind: saml:

Then give your provider the address in metadata_url in the answer: it holds everything your provider needs to know about OS. OS asks for signed answers and for the e-mail address as the NameID.

What the status says¶

OS puts the login into Keycloak, OS's sign-in service, and then reads it back. GET /api/v1/organisations/{id}/company-login shows how far that is:

When the sign-in service refuses a change to a login that already worked, the previous version keeps working: applied_version names that version. When it accepted the new settings and a later step failed, the new settings already apply; check them and set the login up again, with the secret.

Trying the login¶

OS never calls your provider itself, so there is no button that tests the login. Try it yourself: open a private window, go to OS and sign in with an address in your domain. The answer also names sign_in_hint; with it OS sends someone straight to your provider. Do this before you require the login.

Requiring the login¶

When the login is required, a member reaches your organisation only when they signed in through the company login. Switch it on with PATCH /api/v1/organisations/{id}/company-login and {"required": true}, with the version you read in If-Match.

OS refuses that (409) while the login is not active, or when you did not sign in through the login yourself, are not an exemption and do not manage the organisation from above. That way you cannot lock yourself out with a login that does not work.

A member who signed in another way gets 403 with the problem type company-login-required and your login's sign_in_hint; OS then signs them out and in again through the company login. An administrator of a partner who manages your organisation from above falls under the rule of their own organisation, not yours.

Exemptions¶

For the day your provider does not work, you may name at most three members who may also sign in another way. PUT /api/v1/organisations/{id}/company-login/exemptions/{membership_id} adds a member, DELETE on the same address takes them off. The answer lists them under exemptions. An exemption ends when its membership is deactivated or removed. Every time an exemption signs in another way is in the audit trail.

You may also invite someone whose address is outside the domain your login steers, such as an outside adviser, with one of the three exemptions: "company_login_exempt": true in the body of POST /api/v1/organisations/{id}/invitations. The invitation then counts against the three and is listed under exemptions straight away; the person keeps it when they accept, and it ends when the invitation is revoked or expires.

Joining by themselves¶

joining decides what happens to someone who signs in through the company login with an address in your domain but is not a member yet:

Change it with PATCH and {"joining": "automatic"}. Joining also works for someone who signs in through the company login for the first time: OS accepts their address for it because it lies in your proved domain and they came in through your own login.

Changing the login¶

Send the whole login again with PUT, with the version you read in If-Match, and the secret with it. The kind (oidc or saml) cannot change; remove the login then and set up a new one. Until the sign-in service accepts the change, the previous version keeps working.

Removing the login¶

DELETE /api/v1/organisations/{id}/company-login, with If-Match, removes the login. It is then no longer required straight away, and the exemptions end. Members and their accounts stay: whoever also has a password signs in with it; whoever signed in only through the company login sets a password through Forgot password? on the sign-in page. If you give the domain up, the login goes with it (Domains and addresses).

When OS refuses¶

What OS watches¶

Every five minutes OS checks that your login in the sign-in service still stands as OS set it, and puts back what anyone outside OS changed. You need do nothing for it. Every change you make is in the audit trail, without the secret.