Skip to content

Single sign-on with another OpenID Connect provider

Canvus Server 26.11.1 and later can use any OpenID Connect provider for single sign-on, for example Okta or Keycloak. The steps are the same as for Microsoft Entra ID, with an issuer URL in place of the tenant ID. This page is for every provider that has no page of its own. It has worked examples for Okta and Keycloak.

The provider is one entry in the list in Admin > Authentication, and a server can offer up to five providers. See Use several sign-in providers. If you set up sign-in on a 26.11.1 preview build, see If you set up sign-in on a 26.11.1 preview build.

Note

Microsoft Entra ID is the provider MultiTaction tests with. The steps on this page were written from the provider's own documentation and have not been run by MultiTaction against that provider. For Entra ID, use Set up single sign-on with Microsoft Entra ID. For Google Workspace, use Set up single sign-on with Google Workspace.

Warning

Do not use the Other OpenID Connect provider type for Google. It does not check the Google organisation, so anyone with a Google account could pass the sign-in. Use the Google Workspace type instead.

Before you start

You need Canvus Server 26.11.1 or later, administrator access, and the server's external URL set to the address users type. See Before you start in the Entra ID guide. The server must be able to reach your provider over HTTPS. If you use a proxy or an internal certificate authority, see Behind a proxy or with an internal certificate authority.

Set up the provider

  1. In Canvus, open Admin > Authentication and copy the Redirect URI. It is at the bottom of the page and reads <external-url>/users/login/oidc/callback. Every provider on the server uses the same address.
  2. In your provider, create a web application (a confidential client) that uses the authorization code flow.
  3. Add the redirect URI from step 1.
  4. Allow the scopes openid, profile and email.
  5. Copy the Client ID.
  6. Create the credential:
    • A client secret: copy it when your provider shows it.
    • Or a certificate: in Canvus, select Certificate under How the server proves its identity, select Generate certificate, select Download certificate (.cer) and upload the file to your provider. Your provider must support private_key_jwt client authentication. The certificate is valid for 365 days.
  7. Find the issuer URL. It is the address your provider serves /.well-known/openid-configuration from, for example https://idp.example.com/realms/canvus.

Configure Canvus

  1. In Admin > Authentication, under Sign-in providers, select Add provider, then select Other OpenID Connect provider.
  2. Enter the Issuer URL. It must start with https://. The server reads the provider's settings from this URL followed by /.well-known/openid-configuration.
  3. Enter the Client ID.
  4. Under How the server proves its identity, select Client secret and paste the secret. To use a certificate instead, save the provider first (select Add provider with Offer this provider on the sign-in page cleared), select Edit on its card, select Certificate and Generate certificate, and download the .cer file as described above.
  5. Enter a Button name. The login button reads Sign in with <button name>. If you leave it empty, the button reads Sign in with SSO.
  6. Decide on Allowed e-mail domains and Require a verified e-mail address (see The form fields).
  7. Decide whether to select Allow new accounts.
  8. Select Test connection. A working setup reports Connection works. The test checks that the server can read your provider's settings and signing keys. It does not check the client ID or the credential.
  9. Select Offer this provider on the sign-in page, then Add provider (or Save for a provider that is already in the list). The change applies without a restart.
  10. Test the sign-in in a private browser window.

The form fields

Field What it does
Issuer URL The address of the provider, starting with https://. Enter it exactly as the provider reports it.
Allowed e-mail domains One domain per line, for example example.com. Help text in the form: "Leave empty to accept any address the provider vouches for." With domains listed, only addresses on those domains can sign in or create an account.
Client ID From your provider.
How the server proves its identity Client secret or Certificate. A certificate needs a provider that supports private_key_jwt client authentication.
Button name The login button reads Sign in with <button name>, or Sign in with SSO when empty.
Require a verified e-mail address On by default for a new provider. Only people whose e-mail address the identity provider has confirmed can sign in.
Allow new accounts Creates a Canvus account the first time someone signs in. The e-mail domain allow list and the admin approval setting of the server still apply.
Offer this provider on the sign-in page Turns the provider on. Off, the provider stays in the list but has no button.

What turning off the verified e-mail switch means

Canvus links a person to an existing Canvus account by e-mail address on the first sign-in. With Require a verified e-mail address on, the provider must say that it has confirmed the address. With it off, Canvus accepts the address as the provider reports it. Then anyone who can put any e-mail address on their account at your provider can sign in as the person who owns that address in Canvus, including an administrator.

The form shows this notice when the switch is off: "Recommended: turn this on. Without it, anyone who can put any e-mail address on their account at your identity provider can sign in as that person."

Turn it off only when your provider does not send the email_verified claim and you control who can create accounts there. Keycloak, for example, sets the claim only when the realm verifies e-mail addresses.

A provider that you set up on a 26.11.1 preview build keeps its old behaviour after the upgrade, with the switch off, so that nothing that works stops working. The form recommends turning it on.

Example: Okta

This example uses the Okta Admin Console. Canvus has no Okta preset, so you use the Other OpenID Connect provider type.

  1. In Canvus, open Admin > Authentication and copy the Redirect URI.
  2. Sign in to your Okta Admin Console. Go to Applications, then Applications, and select Create App Integration.
  3. For Sign-in method, select OIDC - OpenID Connect.
  4. For Application type, select Web Application, then select Next.
  5. Enter an App integration name, for example Canvus Server. The grant type is Authorization Code and cannot be changed for a web app.
  6. In Sign-in redirect URIs, enter the redirect URI from Canvus.
  7. Under Assignments, choose who may use the app: everyone in the organisation or selected groups. You can change this later on the Assignments tab of the app.
  8. Select Save.
  9. On the General tab of the new app, copy the Client ID and the Client secret.
  10. In Canvus, add an Other OpenID Connect provider and enter:
    • Issuer URL: https://<your Okta domain>, for example https://example.okta.com. This is the Okta org authorization server, which Okta recommends for plain sign-in. Do not add /oauth2/default.
    • Client ID: the Client ID from Okta.
    • Client secret: the Client secret from Okta. Or use a certificate: Okta supports private_key_jwt client authentication. Generate the certificate in Canvus (see Set up the provider) and upload the .cer file as the app's public key in Okta.
    • Button name: Okta.
    • Require a verified e-mail address: Okta's own guidance says not to rely on the email_verified claim to prove ownership of an address. Turn this switch off if sign-in fails with Your e-mail address has not been verified by your organisation's sign-in service. Read What turning off the verified e-mail switch means first.
  11. Select Test connection, then Offer this provider on the sign-in page and Add provider.
  12. Test the sign-in in a private browser window with an assigned user.

Example: Keycloak

This example uses the Keycloak Admin Console.

  1. In Canvus, open Admin > Authentication and copy the Redirect URI.
  2. In the Keycloak Admin Console, select the realm that holds your users.
  3. Select Clients, then Create client.
  4. For Client type, select OpenID Connect. Enter a Client ID, for example canvus. Select Next.
  5. Turn Client authentication on, so the client is confidential and has a secret. Make sure Standard flow is enabled. Select Next.
  6. In Valid redirect URIs, enter the redirect URI from Canvus. Select Save.
  7. Open the Credentials tab of the client and copy the Client secret.

  8. Find the issuer. In the realm, open Realm settings, and on the General tab select the link OpenID Endpoint Configuration. The page it opens is the provider's discovery document. Copy the value of issuer. It usually looks like https://keycloak.example.com/realms/canvus.

    Older or customised Keycloak installs have /auth in the path, for example https://keycloak.example.com/auth/realms/canvus. Keycloak 17 removed it by default. Always copy the issuer from the discovery document and do not build it by hand. 9. In Canvus, add an Other OpenID Connect provider and enter: - Issuer URL: the issuer you copied. - Client ID: the client ID from step 4. - Client secret: the secret from step 7. - Button name: for example Keycloak. - Require a verified e-mail address: leave it on if your realm verifies e-mail addresses. Keycloak sets the claim only then. If sign-in fails with Your e-mail address has not been verified by your organisation's sign-in service., either verify the users' addresses in Keycloak or turn this switch off (see What turning off the verified e-mail switch means). 10. Select Test connection, then Offer this provider on the sign-in page and Add provider. 11. Test the sign-in in a private browser window.

Claims Canvus uses

Claim Use
sub Identifies the person at the provider. Canvus links it to a Canvus account.
email Matches an existing Canvus account, or becomes the e-mail of a new one. Required. Canvus rejects a token whose email_verified claim is false.
name The display name of a new account.

Your provider must include email in the ID token. The rules for linking, creating and approving accounts are the same as for Entra ID. See What happens on first sign-in. Administrator rights are granted in Canvus, not by the provider.

Troubleshooting

The login page messages and the Test connection messages are the same as for Entra ID. See Troubleshooting. Two points apply to other providers:

  • The identity provider reports the issuer ..., not ... means that the issuer URL you entered differs from the issuer value in the provider's discovery document. Enter the issuer exactly as the provider reports it.
  • The provider's own error page is shown before the user returns to Canvus. Look up its code in your provider's documentation.

Where Canvus stores the settings, and how to move from SAML, is described in Where the settings are stored and Moving from SAML.

Returning to an earlier preview build is described in If you set up sign-in on a 26.11.1 preview build.