Authentication

Guide on integrations with user authentication providers

1. Introduction

Ketryx supports different ways of authenticating users, including custom authentication providers specific to some organizations. This guide describes how to configure authentication providers at an organization level, as well as authentication options from a user perspective.

2. Supported authentication methods

By default, Ketryx supports the following authentication methods:

• Login via email (by clicking a "magic login link" in an email)

• Login via Google

• Login via GitHub

Individual organizations may also configure additional authentication methods, including:

• Login via Okta

• Login via any OpenID Connect-compliant authentication provider (based on OAuth 2.0)

If you care about other authentication methods, please talk to us.

2.1. Custom authentication methods based on company domain

Once Ketryx Support verifies and configures a specific email domain for your organization, users trying to log in with an email address under that domain can use authentication methods defined specifically for your organization. Moreover, any new user logging in with a matching email address will automatically join your organization as a member.

Custom authentication methods include Okta as well as any OpenID Connect-compliant authentication provider. Organizations may also enable or disable authentication via email ("magic login links").

Once a custom authentication method is configured (e.g., for an organization with an email domain of example.com), the login process would look like the following:

1. User enters [e-mail] on the Ketryx login page and presses Continue with email

2. Custom authentication methods are determined based on the email domain example.com

3. If there is only a single authentication method, that is initiated immediately without further user interaction (e.g., redirecting to Okta for login, and then back to Ketryx)

4. If there are multiple authentication methods configured for the organization, the user can choose one of them (which may include a button to retrieve a login link via email, as well as other authentication providers)

5. Once a new user is authenticated, they automatically become a member of the organization based on the email domain

Organization-specific authentication methods are configured using the advanced setting Authentication providers. Contact Ketryx Support for assistance with this configuration.

2.2. Authentication via Okta

For authentication via Okta, in addition to having Ketryx Support configure an email domain for your Ketryx organization, create a new App Integration in your Okta instance and configure it in the following way:

• Use "OIDC - OpenID Connect" authentication with the application type "Web Application"

• For Grant type, choose "Client acting on behalf of a user" via an "Authorization Code"

• Set the Sign-in redirect URL to https://app.ketryx.com/api/auth/callback/okta

• Set the Sign-out redirect URL to https://app.ketryx.com

• Make sure that all desired members of the organization are assigned to the app in Okta

• Configure the authentication provider in Ketryx using Okta's client ID, client secret, and issuer URL, as in the example below

In the advanced setting Authentication providers, set the following (based on a CLIENT_ID and CLIENT_SECRET retrieved from Okta, and an appropriate ORGNAME in the Okta URL):

{
  "okta": {
    "clientId": "CLIENT_ID",
    "clientSecret": "CLIENT_SECRET",
    "issuer": "https://ORGNAME.okta.com",
    "allowDangerousEmailAccountLinking": true
  }
}

The flag allowDangerousEmailAccountLinking can be set to allow users to authenticate via Okta even after they have created an account by logging in via email. This is secure as long as you trust your Okta instance to verify and report accurate email addresses.

Okta can also be configured to allow users to initiate a login to Ketryx directly from an Okta dashboard. Please contact Ketryx Support for assistance.

3. Authentication process

3.1. Signing up

When trying to log into Ketryx, you might see a message "No user found for email ..., requiring to sign up first".

The reason is that Ketryx requires some data for each new user, including your full name and organization. When trying to log in with an email address that is not known to the system yet, Ketryx asks you to sign up and provide this data. Please fill out the sign-up form, accept the Terms of Service, and press Sign up and receive a login link to complete the signup process.

Sign-up form when trying to log in with an email address that is not known to the system yet

3.2. Inviting other users

As an organization member with the Invite members permission, you can invite other members to your organization based on their email address. This works even if that email address does not match your organization's email domain, e.g., auditors.

By default, newly invited members will have read-only access to the organization and its projects. Organization owners can change the permission of users or groups at the organization and project level.

3.3. Audit log for system access

All relevant actions of organization members are logged in an audit change log, which can be accessed by organization owners at the organization level and by anyone with the Manage project permission at the project level. Audit logs can also be downloaded as MS Excel files.