You are reading the documentation for an outdated Corteza release. 2024.9 is the latest stable Corteza release.

Authentication

Corteza implements the OAuth2 authentication protocol, where it can act both as a OAuth2 server and as an OAuth2 client, allowing both internal and external authentications.

DevNote add a diagram outlining the entire flow.
Table 1. Terminology:

The user

In OAuth2 terminology, this is a resource owner.

The user authenticates themselves and authorizes the client on the authorization server.

Corteza auth server

In OAuth2 terminology this is a authorization server.

The Corteza auth authenticates users, authorizes clients and issues access tokens.

Corteza auth runs side-by-side with Corteza API server.

Corteza API

In OAuth2 terminology, this is a resource server

A client must obtain an access token in order to access the resources on the the Corteza API.

Corteza auth runs side-by-side with Corteza API server.

Client, Auth Client, Third-Party Application

A client is any application that is used to interact with the Corteza API.

Local credentials

Local credentials are the email and the password that authenticate the user.

External identity providers

An external identity provider is any provider that supports the OpenID Connect (OIDC) protocol such as Google, LinkedIn, and GitHub.

Security context

Security context is a set of roles that are assigned to the user when accessing the Corteza API.

Authenticate Corteza with external providers

Corteza does not yet support authentication via other Corteza instances.

The use of external authentication providers allows your users to use external services (such as Google and GitHub) for authentication purposes. External providers can be defined in the Corteza Admin panel, under the System  Settings  External authentication providers.

To enable an external authentication provider, you must register Corteza as a client using their user interface. Once you’ve obtained the user key and secret, you can configure Corteza using the admin panel. External providers become effective immediately without server restart.

Refer to the administrator guide for details.

Authenticate external application with Corteza

You can allow external applications to use Corteza as an authentication provider as long as they support authentication using OAuth2/OIDC protocols.

After a successful authorization with local credentials or an external provider, an access token along with a refresh token is issued. This should be done automatically by the client.

The access token is short lived and should be automatically refreshed. You can use our corteza-vue plugins/auth to manage this for you.

The session on the Corteza auth is different from the one on the client application. This separation allows the Corteza auth session to be used when authorizing additional clients.

Since the authentication sessions between different clients are different, each session must be revoked in order for the user to be, in fact, signed-out.

Auth clients

An auth client offers a high-level access control over the use of Corteza API and it’s resources. Auth clients can be defined in the Corteza Admin panel, under the System  Auth clients.

We advise you create a separate auth client for each application that you wish to integrate with. Reusing the same client may grant some integrations access permissions that they should not have.
The Auth client consists of:

  1. a combination of a client ID and a client secret,

  2. a list of scopes to limit access based on the used Auth client,

  3. a list of redirection URIs that can be used with authorization code grant,

  4. a trusted flag to force users to confirm authentication,

  5. an Auth client validity based on the date.

You can specify what users are allowed to authorize the client by setting the corresponding "Authorize client" access control operation.

Mark the client as "trusted" to skip the extra authorization step.

Authorization scope

The scope is defined as a series of role memberships that are either permitted, prohibited, or forced on the user when using a specific Corteza auth server.

Permitted roles

Permitted roles define what roles the user is allowed to have when authenticating with this client.

Prohibited roles

Prohibited roles define what roles the user is not allowed to have when authenticating with this client.

Forced roles

Forced roles define what roles the user will have have when authenticating with this client. If the user does not have a forced role, a role will be automatically added.

Notes on security

Use HTTPS with valid SSL certificates.

Authentication forms and endpoints are protected against brute-force and cross-site request attacks. You can also set your own secrets for JWT, CSRF and cookie value encryption.

Different expiration durations may be set on sessions temporary and permanent sessions to support your organization’s security policies.

If any of the secrets are changed, users will receive various warnings and will get logged-out.

Please see the full list of options. These changes take affect after server restart.

Tips for debugging

If your external application is unable to authenticate:

  • client’s ID and secret must match,

  • at least one of client’s redirect URIs must match (by prefix),

  • client’s grant flow must match,

  • client’s scope must match (requested group of scopes must intersect with scopes on the client),

  • user authorizing the client must be a carrier of a role that is able to authorize the client,

  • the user must be valid (confirmed email, unsuspended, undeleted).