Skip to content

IVAAP Authentication

Introduction

IVAAP has it's own managed local authentication, but is also flexible and supports several identity providers such as AWS Cognito, Azure Entra ID (AD), etc. Aside from the external authentication configuration that is needed, IVAAP does have different options for external viewer tags to help control this.

This can be seen and is expressed in the template's values.yaml. 

######################################
##         IVAAP Frontend           ##
######################################
ivaapFrontend:
  viewerName: ivaap-dashboard
  viewer2Name: ivaap-dashboard-publish
  adminName: ivaap-admin
  osdu: false
  images:
    viewer:
      repoName: ivaap/frontend/dashboard-standard
      tag: ivaap-dashboard-standard-3.4.0
      externalTag: ivaap-dashboard-standard-external-3.4.0
      osduTag: osdu-standard-3.4.0
    viewer2:
      repoName: ivaap/frontend/dashboard-publish
      tag: ivaap-dashboard-publish-3.4.0
      externalTag: ivaap-dashboard-publish-external-3.4.0
      osduTag: osdu-publish-3.4.0
    admin:
      repoName: ivaap/frontend/admin-client
      tag: ivaap_admin-3.0.1

By default, the helm template is configured to use local authentication and local frontend viewer images. However, if .Values.environment.authentication.externalAuthEnabled equals true, the frontend externalTag will be used. If the additional flag .Values.ivaapFrontend.osdu is also set to true, the osduTag will be used.

Local Authentication

Within the values.yaml local authentication typically does not need any configuration besides the frontend viewer components utilizeing the intial tags, as shown above with their respective version. These are excellent when being used for development or on-premises environments, where user credentials are managed directly within IVAAP via the adminserver, and stored to the postgres database.

External Authentication

IVAAP supports external authentication mechanisms such as AWS Cognito, Azure Entra ID (AD) and other identity providers. This integration is configured through environment varibles that are enabled for the adminserver to authenticate. The initial location for the environment variables are located in the virtual file sytem (VFS).

The externalTag and osduTag shown in the Introduction are reserved for IVAAP deployments utilizing different Identity providers and plays a big part in external authentication. The externalTag can only be strickly used by external authentication. Similarly the osduTag is specfically for IVAAP OSDU deployments which IVAAP uses to have a specific OSDU GUI and only valid during deployment with external Authentication.

Authentication Environment Variable Overview

This section provides a list of all the IVAAP configurable environment variables related to external authentication from the virutla file system (VFS). Each variable is accompanied by a brief description explaining it's purpose. Values for these environment variables work best when placed within quotes("").

Adminserver Authentication Specific

  • IVAAP_AUTHENTICATION_RESET_ENABLED: indicates whether current authentication must be reset to the default vanilla PostgreSQL authentication (see IVAAP API for Authentication). Default is false.
  • IVAAP_AUTH_SECRET_KEY: specifies a private key to encrypt authentication tokens
  • IVAAP_REDIRECT_ON_CALLBACK_DISABLED: indicates whether a redirect to the referer URL during login callback is disabled. Default is true, planned to be false for the 2.11.2 release
  • IVAAP_ALLOWED_NUMBER_OF_FAILED_LOGIN_ATTEMPTS: specifies the maximum number of unsuccessful logins before account inactivation. Default is 5
  • IVAAP_FAILED_LOGIN_ATTEMPTS_TIME_OUT_IN_MINUTES: specifies the time range for counting unsuccessful logins. Default is 5 minutes
  • IVAAP_REQUIRE_EXTERNAL_AUTH: Will make external authentication a requirement. If used with local authentication, it will prevent login and put java admin in an unworkable state. Set to true or false.
  • IVAAP_IGNORE_NEWLINE_IN_ENV_VARIABLES: Will recognize spaces used in adminserver authentication configuration values. Set to true or false.

VFS Azure Entra ID (AD)

  • IVAAP_AZURE_AD_DISCOVERY_URL: URL for Azure Entre ID's OpenID Connect discovery document to retrieve authentication endpoints and configuration.
  • IVAAP_AZURE_AD_CLIENT_ID: The client ID of the registered application in Azure Entre ID.
  • IVAAP_AZURE_AD_ENCRYPTED_CLIENT_SECRET: Encrypted client secret for the Azure AD application, used for secure communication.
  • IVAAP_AZURE_AD_SCOPE: Scopes defining access levels (e.g., openid, profile, offline_access) required by the application.
  • IVAAP_AZURE_AD_CALLBACK_URL: Redirect URL to handle authentication responses after the user logs in through Azure Entre ID.
  • IVAAP_AZURE_AD_VIEWER_URL: URL for the IVAAP viewer application, used after successful authentication.
  • IVAAP_AZURE_USER_DOMAIN_NAME: The domain name for the organization or tenant.
  • IVAAP_AZURE_USER_GROUP_NAME: Name of the user group, used for role-based access control.
  • IVAAP_AZURE_ADMIN_USERS: List of admin user emails with elevated privileges in the application.
  • IVAAP_AZURE_AD_TENANT_ID: The unique ID of the tenant for the organization.
  • IVAAP_AZURE_AD_USE_USER_INFO_ENDPOINT: Boolean flag to indicate if the Azure AD user info endpoint should be used to retrieve user attributes.
  • IVAAP_AUTH_SECRET_KEY: Secret key used for additional security in authentication flows.
  • IVAAP_AZURE_AD_USER_EMAIL_FIELD: Field mapping to the user's email address in Azure AD.
  • IVAAP_AZURE_AD_USER_NAME_FIELD: Field mapping to the user's last name.
  • IVAAP_AZURE_AD_LAST_NAME_FIELD: Field mapping to the user's last name.
  • IVAAP_AZURE_AD_FIRST_NAME_FIELD: Field mapping to the user's first name.
  • IVAAP_AZURE_SUPER_ADMIN_USERS: List of super admin users with the highest level of privileges in the application.
  • IVAAP_AZURE_ADMIN_USERNAMES: Specific usernames that are granted admin privileges.
  • IVAAP_AZURE_SUPER_ADMIN_USERNAMES: Specific usernames that are granted super admin privileges.
  • IVAAP_AZURE_PKCE_ENABLED: Boolean flag to indicate whether PKCE (Proof Key for Code Exchange) is enabled for improved authentication security.

Below is a configuration example from our deployment-examples directory in the helm template. 

secrets:
  type:
    # All secrets defined in this section must be base64 encoded.
    k8sSecrets:
      adminserver-conf-secrets:
        # ----- Azure AD Authentication
        # ----- Only use this section if .Values.environment.authentication.ifExternal.externalAuthType equals azureAD
        ####### 
        # ----- https://ivaap-domain.com/IVAAPServer/api/v2/callback
        IVAAP_AZURE_AD_CALLBACK_URL: "aHR0cHM6Ly9pdmFhcC1kb21haW4uY29tL0lWQUFQU2VydmVyL2FwaS92Mi9jYWxsYmFjaw=="
        # ----- https://ivaap-domain.com/ivaap/viewer/ivaap.html
        IVAAP_AZURE_AD_VIEWER_URL: "aHR0cHM6Ly9pdmFhcC1kb21haW4uY29tL2l2YWFwL3ZpZXdlci9pdmFhcC5odG1s"
        # ----- user1@email.com,user2@email.com,user3@email.com
        IVAAP_AZURE_AD_ADMIN_USERS: "dXNlcjFAZW1haWwuY29tLHVzZXIyQGVtYWlsLmNvbSx1c2VyM0BlbWFpbC5jb20="
        # -----  https://login.microsoftonline.com/TENANT_ID/v2.0/.well-known/openid-configuration
        IVAAP_AZURE_AD_DISCOVERY_URL: "aHR0cHM6Ly9sb2dpbi5taWNyb3NvZnRvbmxpbmUuY29tL1RFTkFOVF9JRC92Mi4wLy53ZWxsLWtub3duL29wZW5pZC1jb25maWd1cmF0aW9u"
        IVAAP_AZURE_AD_CLIENT_ID: "BASE64_ENCODED_CLIENT_ID"
        IVAAP_AZURE_AD_ENCRYPTED_CLIENT_SECRET: "BASE64_ENCODED_ENCRYPTED_CLIENT_SECRET"
        # ----- CLIENT_ID/.default openid profile offline_access
        IVAAP_AZURE_AD_SCOPE: "Q0xJRU5UX0lELy5kZWZhdWx0IG9wZW5pZCBwcm9maWxlIG9mZmxpbmVfYWNjZXNz"
        IVAAP_AZURE_AD_TENANT_ID: "BASE64_ENCODED_TENANT_ID"
...
...
...
configmap:
  adminserver:
    IVAAP_SERVER_ADMIN_AUTO_MIGRATE: "false"
    IVAAP_REQUIRE_EXTERNAL_AUTH: "true"
    IVAAP_AZURE_AD_USE_USER_INFO_ENDPOINT: "true"
    IVAAP_AZURE_AD_USER_DOMAIN_NAME: "DefaultDomain"
    IVAAP_AZURE_AD_USER_GROUP_NAME: "DefaultGroup"
    IVAAP_AZURE_AD_USER_NAME_FIELD: "name"

VFS AWS Cognito

  • IVAAP_AWS_COGNITO_DISCOVERY_URL: URL for Cognito's OpenID Connect discovery document, used for retrieving endpoints and configuration.
  • IVAAP_AWS_COGNITO_CLIENT_ID: The client ID of the application registered in AWS Cognito.
  • IVAAP_AWS_COGNITO_ENCRYPTED_CLIENT_SECRET: Encrypted client secret associated with the Cognito app client for secure communication.
  • IVAAP_AWS_COGNITO_SCOPE: Scopes defining the access levels (e.g., openid, email) for authentication and authorization.
  • IVAAP_AWS_COGNITO_CALLBACK_URL: Redirect URL for handling authentication responses after login.
  • IVAAP_AWS_COGNITO_VIEWER_URL: URL for the IVAAP viewer, used post-authentication for accessing the application.
  • IVAAP_AWS_COGNITO_END_SESSION_URL: URL for logging out of the AWS Cognito session.
  • IVAAP_AWS_COGNITO_USER_DOMAIN_NAME: Name of the user domain in Cognito, used to categorize users.
  • IVAAP_AWS_COGNITO_USER_GROUP_NAME: Name of the user group in Cognito, defining access permissions and roles.
  • IVAAP_AWS_COGNITO_ADMIN_USERS: List of admin users, typically emails, with elevated privileges in the application.
  • IVAAP_AWS_COGNITO_USER_LAST_NAME_FIELD: Field in Cognito mapping to the user's last name attribute.
  • IVAAP_AWS_COGNITO_USER_FIRST_NAME_FIELD: Field in Cognito mapping to the user's first name attribute.
  • IVAAP_AWS_COGNITO_SUPER_ADMIN_USERS: List of super admin users with the highest level of privileges.
  • IVAAP_AWS_COGNITO_ADMIN_USERNAMES: Specific usernames granted admin privileges.
  • IVAAP_AWS_COGNITO_SUPER_ADMIN_USERNAMES": Specific usernames granted super admin privileges.
  • IVAAP_AWS_COGNITO_USER_NAME_FIELD: Field in Cognito mapping to the user's username attribute.
  • IVAAP_AWS_COGNITO_USER_EMAIL_FIELD: Field in Cognito mapping to the user's email address attribute.
  • IVAAP_AWS_COGNITO_PKCE_ENABLED: Boolean flag indicating whether PKCE (Proof Key for Code Exchange) is enabled for enhanced security during authentication.

Below is a configuration example from our deployment-examples directory in the helm template. 

secrets:
  type:
    # All secrets defined in this section must be base64 encoded.
    k8sSecrets:
      adminserver-conf-secrets:
        # ----- AWS Cognito Authentication
        # ----- Only use this section if .Values.environment.authentication.ifExternal.externalAuthType equals awsCognito        
        ####### 
        # ----- https://ivaap-domain.com/IVAAPServer/api/v2/callback
        IVAAP_AWS_COGNITO_CALLBACK_URL: "aHR0cHM6Ly9pdmFhcC1kb21haW4uY29tL0lWQUFQU2VydmVyL2FwaS92Mi9jYWxsYmFjaw=="
        # ----- https://ivaap-domain.com/ivaap/viewer/ivaap.html
        IVAAP_AWS_COGNITO_VIEWER_URL: "aHR0cHM6Ly9pdmFhcC1kb21haW4uY29tL2l2YWFwL3ZpZXdlci9pdmFhcC5odG1s"
        # ----- user1@email.com,user2@email.com,user3@email.com
        IVAAP_AWS_COGNITO_ADMIN_USERS: "dXNlcjFAZW1haWwuY29tLHVzZXIyQGVtYWlsLmNvbSx1c2VyM0BlbWFpbC5jb20="
        # -----  https://cognito-idp.REGION.amazonaws.com/REGION_aa1b2c3D4/.well-known/openid-configuration
        IVAAP_AWS_COGNITO_DISCOVERY_URL: "aHR0cHM6Ly9jb2duaXRvLWlkcC5SRUdJT04uYW1hem9uYXdzLmNvbS9SRUdJT05fYWExYjJjM0Q0Ly53ZWxsLWtub3duL29wZW5pZC1jb25maWd1cmF0aW9u"
        IVAAP_AWS_COGNITO_CLIENT_ID: "BASE64_ENCODED_CLIENT_ID"
        IVAAP_AWS_COGNITO_ENCRYPTED_CLIENT_SECRET: "BASE64_ENCODED_ENCRYPTED_CLIENT_SECRET"
        # ----- openid email
        IVAAP_AWS_COGNITO_SCOPE: "b3BlbmlkIGVtYWls"
...
...
...
configmap:
  adminserver:
    IVAAP_SERVER_ADMIN_AUTO_MIGRATE: "false"
    IVAAP_REQUIRE_EXTERNAL_AUTH: "true"
    IVAAP_AWS_COGNITO_USER_DOMAIN_NAME: "DefaultDomain"
    IVAAP_AWS_COGNITO_USER_GROUP_NAME: "DefaultGroup"

Virtual File System Configuration Files

The configuration set up for which necessary environment variables are needed for IVAAP's usage of external authentication can be found internally at the Virtual File System (VFS). VFS can be found when logging in as a superadmin, in the "Configuration Files" tab on the left in the "root" domain. The path to the config.properties with the necessary envars needed for the adminserver is located at /configs/backend/admin//main/config.properties.

These confiuration files are the default values and variables, and should not necessarily require modification.

Azure Entra ID (AD) VFS Config

There is a wide selection of environment variables that are needed for Azure Entra ID (AD) and need to be configured for the adminserver. Some are optional.

Example of all default available environment variables in azuread/main/config.properties 

discoveryURL.fromenvironment=IVAAP_AZURE_AD_DISCOVERY_URL
clientId.fromenvironment=IVAAP_AZURE_AD_CLIENT_ID
clientSecret.withaesencryption.fromenvironment=IVAAP_AZURE_AD_ENCRYPTED_CLIENT_SECRET
scope.fromenvironment=IVAAP_AZURE_AD_SCOPE
callbackURL.fromenvironment=IVAAP_AZURE_AD_CALLBACK_URL
viewerURL.fromenvironment=IVAAP_AZURE_AD_VIEWER_URL
userDomainName.fromenvironment=IVAAP_AZURE_USER_DOMAIN_NAME
userGroupName.fromenvironment=IVAAP_AZURE_USER_GROUP_NAME
adminUsers.fromenvironment=IVAAP_AZURE_ADMIN_USERS
tenantId.fromenvironment=IVAAP_AZURE_AD_TENANT_ID
useUserInfoEndpoint.fromenvironment=IVAAP_AZURE_AD_USE_USER_INFO_ENDPOINT
authSecretKey.fromenvironment=IVAAP_AUTH_SECRET_KEY
userEmailField.fromenvironment=IVAAP_AZURE_AD_USER_EMAIL_FIELD
userNameField.fromenvironment=IVAAP_AZURE_AD_USER_NAME_FIELD
userLastNameField.fromenvironment=IVAAP_AZURE_AD_LAST_NAME_FIELD
userFirstNameField.fromenvironment=IVAAP_AZURE_AD_FIRST_NAME_FIELD
superAdminUsers.fromenvironment=IVAAP_AZURE_SUPER_ADMIN_USERS
adminUserNames.fromenvironment=IVAAP_AZURE_ADMIN_USERNAMES
superAdminUserNames.fromenvironment=IVAAP_AZURE_SUPER_ADMIN_USERNAMES
userNameField.fromenvironment=IVAAP_AZURE_AD_USER_NAME_FIELD
userEmailField.fromenvironment=IVAAP_AZURE_AD_USER_EMAIL_FIELD
isPkceEnabled.fromenvironment=IVAAP_AZURE_PKCE_ENABLED

AWS Cognito VFS Config

There is a wide selection of environment variables that are needed for AWS Cognito and need to be configured for the adminserver. Some are optional.

Example of all default available environment variables in awscognito/main/config.properties. 

discoveryURL.fromenvironment=IVAAP_AWS_COGNITO_DISCOVERY_URL
clientId.fromenvironment=IVAAP_AWS_COGNITO_CLIENT_ID
clientSecret.withaesencryption.fromenvironment=IVAAP_AWS_COGNITO_ENCRYPTED_CLIENT_SECRET
scope.fromenvironment=IVAAP_AWS_COGNITO_SCOPE
callbackURL.fromenvironment=IVAAP_AWS_COGNITO_CALLBACK_URL
viewerURL.fromenvironment=IVAAP_AWS_COGNITO_VIEWER_URL
endSessionURL.fromenvironment=IVAAP_AWS_COGNITO_END_SESSION_URL
userDomainName.fromenvironment=IVAAP_AWS_COGNITO_USER_DOMAIN_NAME
userGroupName.fromenvironment=IVAAP_AWS_COGNITO_USER_GROUP_NAME
adminUsers.fromenvironment=IVAAP_AWS_COGNITO_ADMIN_USERS
userLastNameField.fromenvironment=IVAAP_AWS_COGNITO_USER_LAST_NAME_FIELD
userFirstNameField.fromenvironment=IVAAP_AWS_COGNITO_USER_FIRST_NAME_FIELD
superAdminUsers.fromenvironment=IVAAP_AWS_COGNITO_SUPER_ADMIN_USERS
adminUserNames.fromenvironment=IVAAP_AWS_COGNITO_ADMIN_USERNAMES
superAdminUserNames.fromenvironment=IVAAP_AWS_COGNITO_SUPER_ADMIN_USERNAMES"
userNameField.fromenvironment=IVAAP_AWS_COGNITO_USER_NAME_FIELD
userEmailField.fromenvironment=IVAAP_AWS_COGNITO_USER_EMAIL_FIELD
isPkceEnabled.fromenvironment=IVAAP_AWS_COGNITO_PKCE_ENABLED

For details on Helm Template configuration for external authentication, refer to the Authentication section of the General Helm Configuration guide.

External Authentication Troubleshooting

Reviewing the adminserver deployment pod logs will elaborate of any missing environment variables that are not authenticating correctly or missing any values. This is exceptionally usefull for troubleshooting any external authentication connection.