diff --git a/admin/team-management/microsoft-azure-ad.mdx b/admin/team-management/microsoft-azure-ad.mdx deleted file mode 100644 index efaa6ffc..00000000 --- a/admin/team-management/microsoft-azure-ad.mdx +++ /dev/null @@ -1,26 +0,0 @@ ---- -title: "Using Microsoft Entra ID for Single Sign-on in Checkly" -description: "This page illustrates the standard procedure to follow in order to get started with Microsoft Entra ID SSO (formerly Azure AD) on Checkly. " -sidebarTitle: "Microsoft Entra ID" -canonical: 'https://www.checklyhq.com/docs/admin/team-management/microsoft-azure-ad/' ---- - -## Initial SSO configuration - -Setting up SSO for your organisation starts with providing [Checkly Support](mailto:support@checklyhq.com) with the following information: - -- Microsoft Entra ID Domain (e.g. company.com) -- [Client ID](https://auth0.com/docs/connections/enterprise/azure-active-directory) -- Client Secret - -## Testing the SSO integration - -After configuration has taken place on Checkly's side, you will receive confirmation via e-mail. Once that has happened, you should be able to log in to Checkly via SSO already. Entering an email address associated with the domain you have provided in the login prompt should result in the password field disappearing: - -![checkly login prompt without password screenshot](/images/docs/images/single-sign-on/checkly-login-prompt-sso.png) - -After submitting the Checkly login form, you should be redirected to your SSO login interface. Completing the login procedure will then lead you to your existing Checkly account, if you have one, or to the new account creation screen, in case you don't. - - -Once Microsoft Entra ID has been set up, you will still need to invite new users from your organization to your Checkly account, as they will not be added automatically. - \ No newline at end of file diff --git a/admin/team-management/saml.mdx b/admin/team-management/saml.mdx deleted file mode 100644 index 5a8a30ef..00000000 --- a/admin/team-management/saml.mdx +++ /dev/null @@ -1,70 +0,0 @@ ---- -title: "SAML for Single Sign-on in Checkly" -description: "Learn how to configure SAML SSO integration with Checkly for your organization" -sidebarTitle: "SAML" -canonical: 'https://www.checklyhq.com/docs/admin/team-management/saml/' ---- - -## Initial SSO setup - -Setting up SSO for your organisation starts with providing [Checkly Support](mailto:support@checklyhq.com) with the following information: - -- name / type / brand of your identity provider -- email domain -- sign in URL -- sign out URL -- public X509 certificate - -## IdP configuration - -After your configuration has been processed on Checkly's side, you'll receive the following information to configure your IdP: - -- a redirect URL (e.g. `https://auth.checklyhq.com/login/callback?connection=`) -- a signout URL (normally `https://auth.checklyhq.com/logout`) -- XML metadata (e.g. `https://auth.checklyhq.com/samlp/metadata?connection=`) - -Ensure your SSO IdP is sending Checkly the correct email address. Checkly can then map the existing user to your IdP user. The object returned should have an "email" field, e.g.: - -```json -{ - "email": "", - ... -} -``` - - -In case of issues, you might want to double-check your **Entity ID**, which should be: `urn:auth0:checkly:` - - -## Testing the integration - -Once that is taken care of, logging in to Checkly via SSO is ready. Entering an email address associated with the domain you have provided in the login prompt should result in the password field disappearing: - -![checkly login prompt without password screenshot](/images/docs/images/single-sign-on/checkly-login-prompt-sso.png) - -After submitting the Checkly login form, you should be redirected to your SSO login interface. Completing the login procedure will then lead you to your existing Checkly account, if you have one, or to the new account creation screen, in case you don't. - -## JIT User Provisioning - -Just-in-time user provisioning is now enabled for Enterprise customers using a single Checkly account. - -This allows all users from your SSO organisation to join your Checkly account by simply by logging in. You don't need to invite anyone manually (although you still can). - -There are two ways your users can access Checkly: - -- Go through your SSO provider and access Checkly from the list of your approved apps. -- Access the [Checkly Login Page](https://app.checklyhq.com/) directly. - - This requires a user to enter their email in the email field, and then click Continue. - -Both approaches seamlessly allow the user to be added to your Checkly account. - -### Default user roles - -By default, all users provisioned via SSO receive Read & Write permission within Checkly. You are able to modify this behaviour by going to the [SSO Configuration](https://app.checklyhq.com/settings/account/sso-saml) and choosing a different role. - -### Removing users - -If you want to remove users that have been previously provisioned through SSO, there is a two-step process: - -1. Remove their access within your SSO provider. -2. Remove them from your [Checkly Team](https://app.checklyhq.com/settings/account/team). \ No newline at end of file diff --git a/admin/team-management/single-sign-on.mdx b/admin/team-management/single-sign-on.mdx index 46460839..2c902cfe 100644 --- a/admin/team-management/single-sign-on.mdx +++ b/admin/team-management/single-sign-on.mdx @@ -1,17 +1,182 @@ --- title: "Single Sign-on in Checkly" -description: "Overview of Single Sign-On (SSO) options available in Checkly for enterprise security" -sidebarTitle: "Overview" +description: "Overview of Single Sign-On (SSO) in Checkly for enterprise customers, including setting up the connection and other frequently asked questions" +sidebarTitle: "Single Sign-On" canonical: 'https://www.checklyhq.com/docs/admin/team-management/single-sign-on/' --- -Single Sign-On (SSO) enables businesses to secure employee access across a variety of third-party services. Currently, Checkly supports the following SSO protocols: + +SSO is only available for Checkly's [enterprise plans](https://www.checklyhq.com/pricing/). + + +## Setting up the connection + +The general process is detailed below, but please reach out to your customer success team or to [support@checklyhq.com](mailto:support@checklyhq.com) if you have questions or concerns. We're flexible and are more than happy to work with you on your specific use case. + + + + To get started with SSO, email [support@checklyhq.com](mailto:support@checklyhq.com). We'll review your account and ask you a few questions. + + + We'll send you a self-serve link to set up the SSO connection. This includes instructions for configuring the connection in your IdP, plus a place to upload your connection metadata to Checkly. + + + The self-serve link is valid for 5 days. After accessing the link, you'll have five hours to complete the setup and can access it up to 10 times. This limit is pre-set by our authentication tool and isn't controlled by us. + + If your self-serve link expires, let us know, and we'll generate another one for you. Alternatively, you can follow the manual setup process below. + + + + If you need our logo for the Checkly IdP tile, we provide several [here](/assets/checkly-logos-for-sso-tiles.zip). + + + + We highly recommend using the self-serve link process mentioned above. If that doesn't work for any reason, we can manually configure the connection. + + The information provided is for the SAML protocol — let us know if you need something other than SAML. + + First, send us your: + + * email domain(s) + * sign in URL + * sign out URL (optional) + * public X509 certificate + + Then, we'll send configuration details for your end: + + * Postback URL + * Logout URL (optional) + * XML metadata + * Entity ID + + The most important thing is that we get the email address back from your SSO Idp. This way we can map the existing Checkly user to your Idp user. + + Thus, please make sure the attributes returned include an "email" and "name" field, e.g. + + ``` + { + "email": , + "name": + } + ``` + + For how to configure a SAML connection with your IdP, please refer to your IdP's documentation: + + * [Google Workspace](https://knowledge.workspace.google.com/admin/apps/set-up-your-own-custom-saml-app) + * [Microsoft Entra ID](https://learn.microsoft.com/en-us/entra/identity/enterprise-apps/add-application-portal-setup-sso) + * [Okta](https://support.okta.com/help/s/article/How-To-Configure-A-Custom-SAML-App) + + + + + Test the connection by logging in to Checkly through your IdP dashboard. + + Once logged in to Checkly, verify the SSO connection worked by going to the [Members page](https://app.checklyhq.com/accounts/settings/account/members) (Click the profile picture in the top right, select **Members**) and make sure there is a checkmark in the SSO column for your user: + + ![checkly members page SSO check mark screenshot](/images/sso-check-mark.png) + + If you see that SSO checkmark, congratulations! The connection works. If not, no worries — let us know and we can set up a call to troubleshoot. + + + When existing users log in via SSO, a new user will be created. This is expected, as detailed [here](/admin/team-management/single-sign-on#migrating-existing-users-to-sso). + + + + If you would like [SP-initiated SSO](/admin/team-management/single-sign-on#service-provider-sp-initiated) enabled, let us know. We'll update the connection with your company's email domains. + + + We recommend [migrating your existing users to SSO](/admin/team-management/single-sign-on#migrating-existing-users-to-sso). + + This is not required, but we highly recommend it to prevent any confusion with duplicate users. + + + If you have any questions or need to modify your SSO connection, please reach out to [support@checklyhq.com](mailto:support@checklyhq.com). + + + + +## Logging in with SSO + +We support both IdP- and SP-initiated SSO. + +### Identity provider (IdP) initiated + +IdP-initiated SSO happens when you login to Checkly through your IdP. Typically, this means going to your IdP dashboard and selecting the "Checkly" application. -1. [SAML](/admin/team-management/saml) -2. [Microsoft Entra ID](/admin/team-management/microsoft-azure-ad) (formerly Azure AD) +Checkly enables this by default, though there may be extra configuration needed on your IdP's side. -If you are interested in using Checkly with a different SSO protocol, please [reach out to Support](mailto:support@checklyhq.com). +### Service provider (SP) initiated + +SP-initiated SSO happens when you login to Checkly directly by going to [app.checklyhq.com](https://app.checklyhq.com/) and entering your email address. + + +Using the "Continue with Google" or "Continue with Github" buttons will not redirect to SSO — you must use the email address field. + + +To check if SP-initiated SSO is enabled for your account, go to your [SSO configuration page](https://app.checklyhq.com/accounts/settings/account/sso-saml) and make sure the **Tenant Domain** field is filled. Email logins from those domains will route to your SSO connection. + +To update this setting, reach out to [support@checklyhq.com](mailto:support@checklyhq.com) with the email domain(s) that you'd like added. + +## Just-in-time (JIT) provisioning + +When JIT is enabled, new users who sign in through your SSO connection will be automatically added to your account. + +Users will be created with the default role specified on your [SSO settings page](https://app.checklyhq.com/settings/account/sso-saml), which the account owner can change at any time. + +We enable JIT by default when we set up your SSO connection. If you'd like JIT disabled, please let [our Support team](mailto:support@checklyhq.com) know. -SSO is only available for Checkly's [enterprise plans](https://www.checklyhq.com/pricing/). - \ No newline at end of file + We only support JIT for a single tenant. If you have multiple tenants, our team will confirm which account you want JIT enabled for. + + +## Migrating existing users to SSO + +When you log in with SSO for the first time, our system creates a new user. If you already have a Checkly user through a different login method, you will see duplicate users (one created through SSO and another with your previous login method) until your remove the non-SSO user. + + + Users logging in with SSO have a check mark in the SSO column on your [Members page](https://app.checklyhq.com/settings/account/members): + ![checkly members page SSO check mark screenshot](/images/sso-check-mark.png) + + +If you have users created outside of SSO, we recommend migrating them to SSO: + +1. Have the team member log out. +2. Have the team member log in with SSO. + * If [JIT](/admin/team-management/single-sign-on#just-in-time-jit-provisioning) is enabled, they will automatically be added to your Checkly account. + * Otherwise, you will need to send them an invite via the [Members page](https://app.checklyhq.com/settings/account/members). +3. Update the team member's role via the [Members page](https://app.checklyhq.com/settings/account/members). +4. Remove the team member's old non-SSO user. + * If there are any API keys tied to this user, you will need to re-generate them. We recommend using [Service API keys](https://app.checklyhq.com/settings/account/service-api-keys) instead, since they are tied to your account and not individual users. + + + If you're migrating an account owner to SSO, please [contact support](mailto:support@checklyhq.com) once they've logged in through SSO, and we'll transfer ownership to their new user. + + +If you need assistance with this, we encourage you to contact [our Support team](mailto:support@checklyhq.com). + +## Frequently asked questions + +### Why do I see duplicate users? + +See [Migrating existing users to SSO](/admin/team-management/single-sign-on#migrating-existing-users-to-sso). + +### Do you support SCIM? + +Currently, SCIM is not supported. If you'd like to add SCIM support, please let us know so we can record your interest as feedback. + +### How can I manage user roles? + +Currently, we do not support SCIM or any IdP-based role mapping. + +Admins and Owners can manually set user roles on the [Members page](https://app.checklyhq.com/settings/account/members), or you can programmatically manage roles using our [CLI](/cli/checkly-members#checkly-members-update) or [public API](/api-reference/accounts/update-a-current-account-member-role). + +### How can we enforce SSO for all team members? + +You can take several steps to make sure only SSO users are in your account: + +* Make sure [SP-initiated logins](/admin/team-management/single-sign-on#service-provider-sp-initiated) are enabled. +* [Migrate all users to SSO.](/admin/team-management/single-sign-on#migrating-existing-users-to-sso) +* Periodically remove non-SSO users. You can do this manually on the [Members page](https://app.checklyhq.com/settings/account/members) or automatically using our [CLI](/cli/checkly-members#checkly-members-update) or [public API](/api-reference/accounts/update-a-current-account-member-role). +* Do not send invitations to users, since they can accept invitations with a non-SSO login. Instead, they should [login through SSO](/admin/team-management/single-sign-on#logging-in-with-sso) and be automatically [JIT provisioned](/admin/team-management/single-sign-on#just-in-time-jit-provisioning) to you account. + +Currently, there is no option to require SSO for account members. If you’d like to see this added, please let us know so we can record your interest as feedback. diff --git a/assets/checkly-logos-for-sso-tiles.zip b/assets/checkly-logos-for-sso-tiles.zip new file mode 100644 index 00000000..5ba21a3e Binary files /dev/null and b/assets/checkly-logos-for-sso-tiles.zip differ diff --git a/docs.json b/docs.json index 511eb511..559cff57 100644 --- a/docs.json +++ b/docs.json @@ -119,14 +119,7 @@ "admin/team-management/overview", "admin/team-management/adding-team-members", "admin/team-management/multi-factor-authentication", - { - "group": "Single Sign-On", - "pages": [ - "admin/team-management/single-sign-on", - "admin/team-management/microsoft-azure-ad", - "admin/team-management/saml" - ] - } + "admin/team-management/single-sign-on" ] }, "admin/changing-your-email-password" @@ -1453,6 +1446,14 @@ } }, "redirects": [ + { + "source": "/admin/team-management/saml", + "destination": "/admin/team-management/single-sign-on" + }, + { + "source": "/admin/team-management/microsoft-azure-ad", + "destination": "/admin/team-management/single-sign-on" + }, { "source": "/quickstarts/general", "destination": "/quickstart" diff --git a/images/sso-check-mark.png b/images/sso-check-mark.png new file mode 100644 index 00000000..a42c030d Binary files /dev/null and b/images/sso-check-mark.png differ diff --git a/sitemap.xml b/sitemap.xml index 0b4efe02..c27c631b 100644 --- a/sitemap.xml +++ b/sitemap.xml @@ -12,18 +12,12 @@ https://www.checklyhq.com/docs/admin/team-management/adding-team-members/ - - https://www.checklyhq.com/docs/admin/team-management/microsoft-azure-ad/ - https://www.checklyhq.com/docs/admin/team-management/multi-factor-authentication/ https://www.checklyhq.com/docs/admin/team-management/overview/ - - https://www.checklyhq.com/docs/admin/team-management/saml/ - https://www.checklyhq.com/docs/admin/team-management/single-sign-on/