Authentication

Auth client

An authentication client (an auth client for the remaining text) is a facility that allows you to define how an external application can use Corteza to authenticate and what access the authenticated users may have.

You can use Corteza to authenticate third-party applications which support OAuth2/OIDC.

The system auth clients user interface allows you to inspect and manage your auth clients.

From there you can:

list the auth clients created inside your Corteza instance.
create a new auth client by clicking on the new button,
edit an existing auth client by clicking on the edit icon next to the auth client,
manage global auth client permissions by clicking on the permissions button.

Listing auth clients

To list current system auth clients:

Navigate to system auth clients,
optionally insert the filtering parameters (the list refreshes automatically).

Creating auth clients

Permissions can only be defined on existing auth clients.

To create a new auth client:

navigate to system auth clients,
click on the new button in the top right corner,
provide the requested data,
press the submit button.

Editing auth clients

To edit an existing auth client:

navigate to system auth clients,
click on the edit icon next to the auth client you wish to edit,
update the parameters you wish to change,
press the submit button.

Deleting auth clients

To delete an existing auth client:

navigate to system auth clients,
click on the edit icon next to the auth client you wish to suspend,
press and confirm the delete button.

Default auth clients can not be deleted.

Grant types

Corteza authentication supports two OAuth2 grant types: authorization code and client credentials.

Table 1. Authentication grant types:

Authorization code

The authorization code grant type is used to authenticate users with the classic OAuth2 flow.

To enable this grant type, select the "will be used to authenticate users (grant type = authorization_code)" option.

Client credentials

The client credentials grant type is the simplified authentication flow, normally used to authenticate systems, such as external services or applications.

Client credentials grant type requires you to populate the "impersonate user" option. The impersonated user will be used to create the security context of the JWT token.

To enable the grant type, select the "will be used to authenticate machines (grant type = client_credentials)" option.

Defining password constraints

Corteza allows you to define custom password constraints which enable you to better conform to your security model.

Password constraints are configured on the Corteza Admin web application under system settings in the "password constraints" section.

Minimum length

The minimum length parameter allows you to restrict your users from using short, insecure passwords. You can not set the minimum length below 8.

The maximum password length is not configurable and is set to 256.

Minimum number of numbers

The minimum number of numbers allows you to require your users to use numerical values in their passwords. The requirement is disabled when the value is left at 0.

Minimum number of special characters

The minimum number of special characters allows you to require your users to use special characters in their passwords. The requirement is disabled when the value is left at 0.

The AUTH_PASSWORD_SECURITY .env variable allows you to disable password requirements checking by setting it to false. This is handy for local development where we may not wish to handle complex password constraints.

The option should be disabled for any production deployment. If the password security is disabled, a warning message is displayed in the UI.

Limit access

By default, any user can use any auth client. To limit access to specific auth clients, navigate to the auth client and set the "authorize client" access control rule.

If a specific role does not have the authorize client RBAC rule, the underlying users can not authenticate with the given auth client.

Define session duration

Corteza allows you to define how long the access tokens are to be considered valid.

Table 2. The three `.env` variables to control the authentication session:
AUTH_OAUTH2_ACCESS_TOKEN_LIFETIME	The `AUTH_OAUTH2_ACCESS_TOKEN_LIFETIME` `.env` variable allows you to define how long an access token will be valid for. The access token represents the credentials that allow users to access protected resources such as records, users, and workflows. An example of limiting the access token to two minutes: `AUTH_OAUTH2_ACCESS_TOKEN_LIFETIME=2m`
AUTH_OAUTH2_REFRESH_TOKEN_LIFETIME	The `AUTH_OAUTH2_REFRESH_TOKEN_LIFETIME` `.env` variable allows you to define how long a refresh token should be valid. The refresh token provides a mechanism which generates a new access token when the old one expires, removing the need to re-authenticate the user. An example of limiting the refresh token to two minutes: `AUTH_OAUTH2_REFRESH_TOKEN_LIFETIME=2m`
AUTH_SESSION_LIFETIME	The `AUTH_SESSION_LIFETIME` `.env` variable allows you to define how long the authentication session should be valid. The authentication session is generated when the user provides their credentials to the Corteza login page. The authentication session is independent of access tokens. An example of limiting the auth session to two minutes: `AUTH_SESSION_LIFETIME=2m`
AUTH_SESSION_PERM_LIFETIME	The `AUTH_SESSION_PERM_LIFETIME` `.env` variable allows you to define how long the authentication session should be valid when the login and remember me is used. The authentication session is generated when the user provides their credentials to the Corteza login page. The authentication session is independent of access tokens. An example of limiting the auth session to two minutes: `AUTH_SESSION_PERM_LIFETIME=2m`

Log out inactive users after two minutes

If you wish to log out inactive users, you need to set all three of the .env variables mentioned above.

AUTH_OAUTH2_ACCESS_TOKEN_LIFETIME=2m
AUTH_SESSION_LIFETIME=2m
AUTH_OAUTH2_REFRESH_TOKEN_LIFETIME=2m

When the user is considered inactive is determined by the user’s browser. Usually this is when they close the tab/window or when their computer enters rest mode.