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

Authentication of External Applications

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.

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 — the access token is valid for 2 hours and the refresh token is valid for 3 days. You can control the token expiry using AUTH_OAUTH2_ACCESS_TOKEN_LIFETIME and AUTH_OAUTH2_REFRESH_TOKEN_LIFETIME .env variables. Refer to define session duration for more details.

You can use our corteza-vue plugins/auth to manage this for you.

Configuration of Corteza

Access Corteza Admin panel and navigate to system  auth clients. Create a new auth client which your external application is going to use to authenticate.

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

  1. a combination of a client ID and a client secret (the client ID is located in the URL address bar),

  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.

Make sure to select the appropriate grant type based on your use-case. Refer to here for more details.

Configuring External Applications

DevNote todo; expand on this section.

Copy the parameters obtained from the auth client into tour external application. The client ID is the long number at the end of the URL address.

Authentication Lifecycle

DevNote todo; expand on this section.

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.

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.

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

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

Tips for Debugging

If your external application is unable to authenticate, check the following:

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

Glossary

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 is assigned to the user when accessing the Corteza API.