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

Authentication and authorization

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

Refer to the OAuth2 spec for a complete reference to the protocol.

Outline of the common authorization flow with {PRODUCT_NAME} Auth:
Figure 1. Outline of the common authorization flow with Corteza Auth:

Why OAuth2 rework?

  • OAuth2 is a proven and well-accepted authentication standard.

  • Corteza becomes more open and easier to integrate with different applications.

  • It fits well into the existing RBAC security model.

  • Personalized authentication page lets users feel safe when entering their credentials.

  • Trivial Corteza authentication user interface modification.

Terminology

The user

In OAuth2 terminology, this is a resource owner The user authenticates themselves and authorize the <<,auth-client,client>> on the authorization server.

Corteza auth server

In OAuth2 terminology, this is an *authorization server* The Corteza Auth authenticates users, authorizes clients, and issues access tokens.

More details can be found here.

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 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 being 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

The security context is a set of roles assigned to the user when accessing the Corteza API.

More in the auth scope section.

Corteza Auth server

Enables users to allow applications access to the Corteza API resources without sharing their actual credentials. This happens through the secure exchange of credentials, codes, secrets and tokens following the OAuth2 protocol.

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

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, you must revoke each session for the user to be "truly signed-out".

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.

Corteza Auth security features

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

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

Future improvements

  • more fine-grain scopes

  • per-client allow/deny list of IP addresses

  • per-client access and refresh token expiration control

  • per-client refresh token use

  • per-client credentials use (only local-login, require 2fa, the only login via specific provider)