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

External Authentication 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.

Annotated image

To enable an external authentication provider, you must register Corteza as a client using the provider’s 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.

Authentication Providers


To enable Google authentication, you need to retrieve your application credentials:
  1. Go to Google Sign-in Guide and click on "Configure a project" button.

  2. Select an existing or create a new project.

  3. Set a product name.

  4. On "Configure your OAuth client" screen select "Web browser" and paste the URL where your Corteza system is running (including https://).

  5. Copy and paste both Client ID and Client Secret fields to Corteza Admin.


To enable Facebook authentication, you need to retrieve your application credentials:
  1. Go to Facebook for developers website, click on "Add a new app" or select an existing app.

  2. On the list of available products search for "Facebook Login" and click on the "Set Up" button.

  3. Select "Web" platform and paste the URL where your Corteza system is running.

  4. Go to "Settings" and then "Basic" in the left sidebar.

  5. Copy and paste both App ID and App Secret fields to Corteza Admin; app ID maps to client key, app secret maps to secret.


To enable GitHub authentication, you need to retrieve your application credentials:
  1. Go to GitHub and create a new OAuth application.

  2. Copy and paste both Client ID and Client Secret fields to Corteza Admin.


To enable LinkedIn authentication, you need to retrieve your application credentials:
  1. Go to LinkedIn, fill out the form and click on "Create app".

  2. Go to Auth section and copy and paste both the Client ID and Client Secret fields to Corteza Admin.


To enable SAML authentication, you need to exchange credentials from your identity provider (IdP in the following text). The configuration process involves the optional key generation and setting up IdP in the Admin panel.

Generating Private and Public Key Pair

The example credentials displayed in this document should not be used in your instances.

This step is optional. You can use your existing key pair to set up SAML.

Minimum required commands for generating private and public keys used for SAML authentication:
openssl req -x509 -sha256 -nodes -days 365 -newkey rsa:2048 \
  -keyout private.key \
  -out certificate.crt \
  -subj "/" (1)

openssl rsa -in private.key -out private-rsa.key (2)

cat certificate.crt private-rsa.key (3)
1 The command generates a new key pair.
2 The command converts the private key to RSA format.
3 The command prints out the relevant keys you can copy.

The example credentials displayed in this document should not be used in your instances.

The following snippet shows an example of a public key.
The following snippet shows an example of a private RSA key.

Using Signed and Encrypted Requests

The AuthNRequest to the IdP can be signed and encrypted with the provided certificate and sent via HTTP-Post binding to the IdP of choice. Refer to more examples for help on the samltool webpage.

The assertion coming back from IdP can be signed and encrypted, provided that the certificate on the service provider side (Corteza) is included in the SAML metadata. Corteza supports signed message and signed and encrypted assertions. Refer to more examples for help on the samltool webpage.

Enabling signed requests and responses:
  1. The "Sign requests" checkbox under "Certificate" section should be enabled (refer to the admin ui screenshot).

  2. "Signature method" should be set and depends on the kind of algorithm was specified on the certificate creation (in this example, SHA256 was used).

For more information on AuthNRequest and assertion in metadata refer to the developer notes.

SAML Bindings

Corteza supports HTTP POST and HTTP Redirect SAML 2.0 bindings.

Specifying SAML binding:

The "binding" dropdown should be selected, specifying either HTTP POST or HTTP Redirect binding (refer to the admin ui screenshot).

The fallback choice is HTTP Redirect.

For more information on bindings in metadata refer to the developer notes.

Setting up the IdP in the Administration Panel

Open your administration panel and navigate to system  settings.

Screenshot of the configuration window.
Figure 1. The screenshot shows the SAML settings in the administration panel under system  settings.
Notes on the SAML configuration form:
  1. If you disable your SAML IdP, all settings are kept in Corteza. Users will no longer be able to use SAML for login. All active login sessions created using SAML are kept; users are not logged out.

  2. The name is displayed on the login form (refer to the below screenshot).

  3. Identity provider URL must point to the URL of the server which provides the metadata. The metadata is an XML document providing machine-readable instructions for SAML configuration.

  4. Name, handle and identifier fields need to be specified in order for the user to be created. When a user successfully logs in using SAML, Corteza performs a lookup using a value from the identifier field, which is expected to be an email. Values from name and handle are used when creating a new user.

Corteza tries to guess the identifier among one of the following:
  • default identifier as defined in settings

  • emailAddress

  • urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress

  • urn:oasis:names:tc:SAML:attribute:subject-id

  • email

  • mail

The above values follow the industry standard, but you should consult your IdP-specific documentation on what is provided as a part of user data.

Login Screen with SAML Enabled

Screenshot of the login screen.
Figure 2. The screenshot shows the login screen when SAML authentication is enabled.

When clicking on the appropriate button (in this case, this is "Login with Example IdP"), the user enters the SAML authentication flow where the service (Corteza) and the identity providers (IdP) exchange information. The user is automatically redirected back to Corteza after successful login on the IdP.

Developer Notes

When setting up the SAML authentication provider, there is some information that can be read from the SP metadata that is generated from the configuration.

The metadata URL resides at $BASE_URL/auth/external/saml/metadata.

Fetching metadata with curl example:
curl $BASE_URL/auth/external/saml/metadata
Table 1. Depending on the configuration, the following information can be read:

Logout info

<SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="$BASE_URL/auth/external/saml/slo" ResponseLocation="$BASE_URL/auth/external/saml/slo"></SingleLogoutService>

AuthNRequest signed enabled / disabled.

<SPSSODescriptor xmlns="urn:oasis:names:tc:SAML:2.0:metadata" protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol" AuthnRequestsSigned="true" WantAssertionsSigned="true">

Adjust user role membership

Each of the external authentication providers supports restricting and adjusting the user’s role membership when a specific external authentication provider is used.

When using in combination with security settings on authentication client, settings from the authentication client are applied first, then settings from external authentication provider.

To configure role membership, click on the edit icon next to the external authentication provider.

Annotated image

On the bottom of the modal you should see three inputs for permitted, prohibited, and forced roles.

Annotated image

Permitted roles

List of roles that users are allowed to keep.

Prohibited roles

List of roles that are removed from user.

Forced roles

List of roles that are added to user when authenticating with this external provider.