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

Authentication and authorization

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

Terminology

The user

In OAuth2 terminology, this is a resource owner. The user authenticates themselves and authorizes the <<,auth-client,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 currently 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 currently 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 the user can use to authenticate.

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.

Defining external providers

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 server as a client using their 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.

Using Corteza as an authentication provider

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.

It is advised that you create a separate Auth client for each application you wish to integrate with. This allows you to have full control over all integrated applications and the clients' scope.

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.

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

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

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 allow you to specify what roles the user is allowed to have when accessing the Corteza API resources from a specific client.

Prohibited roles

Prohibited roles allow you to specify what roles the user is not allowed to have when accessing the Corteza API resources from a specific client.

Forced roles

Forced roles allow you to specify what roles the user must have when accessing the Corteza API resources from a specific client. If the user does not have a forced role, a role will be automatically added.

Notes on security

First and above all, 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

Things to check when authentication does not work:

  • 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).