Package com.cloudforge.core.interfaces

Interface OidcIntegration

All Known Implementing Classes:
GitLabOidcIntegration, GrafanaOidcIntegration, JenkinsOidcIntegration, MattermostGitLabOidcIntegration, MattermostOidcIntegration, MattermostSamlIntegration, MetabaseSamlIntegration
public interface OidcIntegration
Application-level OIDC integration interface.

This interface defines how applications integrate with OIDC providers for authentication. Each application implements this to configure its specific OIDC plugin/module.

CloudForge supports two separate authentication systems:

  • Amazon Cognito - Standalone user directory with OIDC
  • IAM Identity Center - Enterprise SSO with SAML/OIDC

These are completely separate systems and cannot be mixed.

See Also:

  • Method Details

    • isSupported

      boolean isSupported()
      Returns whether this application supports OIDC integration.
      Returns:
      true if application has OIDC support

    • getIntegrationMethod

      String getIntegrationMethod()
      Returns the OIDC integration method for this application.

      Examples:

      • jenkins: OIDC Plugin
      • gitlab: Built-in OmniAuth
      • grafana: Built-in generic_oauth
      • sonarqube: OIDC Plugin
      Returns:
      integration method description

    • getEnvironmentVariables

      Map<String,String> getEnvironmentVariables(OidcConfiguration config)
      Returns environment variables needed for OIDC configuration.

      These are passed to the container or EC2 userdata script.

      Example for Grafana:

       GF_AUTH_GENERIC_OAUTH_ENABLED=true
 GF_AUTH_GENERIC_OAUTH_NAME=Cognito
 GF_AUTH_GENERIC_OAUTH_CLIENT_ID=${clientId}
 GF_AUTH_GENERIC_OAUTH_AUTH_URL=${authUrl}
      Parameters:
      config - OIDC configuration from provider
      Returns:
      map of environment variable name to value

    • getConfigurationFile

      default String getConfigurationFile(OidcConfiguration config)
      Returns configuration file content for OIDC setup.

      Some applications require configuration files instead of environment variables.

      Example for GitLab gitlab.rb:

       gitlab_rails['omniauth_enabled'] = true
 gitlab_rails['omniauth_providers'] = [
   {
     name: 'openid_connect',
     args: { ... }
   }
 ]
      Parameters:
      config - OIDC configuration from provider
      Returns:
      configuration file content (optional)

    • getConfigurationFilePath

      default String getConfigurationFilePath()
      Returns the file path where configuration should be written.

      Only used if getConfigurationFile() returns non-null.

      Returns:
      configuration file path (optional)

    • getUserDataCommands

      List<String> getUserDataCommands(OidcConfiguration config, Ec2Context context)
      Returns UserData commands for setting up OIDC integration.

      These commands are added to the EC2 userdata script to configure OIDC integration during instance initialization.

      Parameters:
      config - OIDC configuration from provider
      context - EC2 context with stack information
      Returns:
      list of shell commands

    • getPostDeploymentInstructions

      default String getPostDeploymentInstructions()
      Returns post-deployment instructions for completing OIDC setup.

      Some applications require manual steps after deployment (e.g., installing plugins).

      Returns:
      human-readable instructions (optional)

    • getContainerStartupCommand

      default String getContainerStartupCommand()
      Returns the application startup command for Fargate containers.

      This command is used to start the application after the OIDC configuration file has been created. Each application has a different startup script.

      Examples:

      • Jenkins: /usr/local/bin/jenkins.sh
      • GitLab: /assets/wrapper
      • Grafana: /run.sh
      • Mattermost: /mattermost/bin/mattermost (distroless - Go binary)
      Returns:
      startup command path

    • getOidcCallbackPath

      default String getOidcCallbackPath()
      Returns the OIDC callback path for this application.

      This is the path where the OIDC provider redirects after authentication. Each application has a different callback path based on its OIDC implementation.

      Examples:

      • Jenkins: /securityRealm/finishLogin
      • Mattermost: /signup/gitlab/complete (uses GitLab OAuth provider for OIDC)
      • GitLab: /users/auth/openid_connect/callback
      • Grafana: /login/generic_oauth
      Returns:
      callback path (e.g., "/securityRealm/finishLogin")

    • isDistroless

      default boolean isDistroless()
      Returns whether the container image is distroless (has no shell).

      Distroless images contain only the application binary and dependencies, without a shell (/bin/sh). This affects how OIDC configuration is applied:

      • Normal images: Use /bin/sh -c to write config files at startup
      • Distroless images: Must use environment variables only

      Examples of distroless images:

      • mattermost/mattermost-team-edition - Go binary, no shell
      • gcr.io/distroless/* - Google distroless images
      Returns:
      true if the container is distroless and has no shell

    • supportsAlbOidc

      default boolean supportsAlbOidc()
      Returns whether this application supports ALB-level OIDC authentication.

      ALB-level auth means authentication is handled by the ALB before traffic reaches the application. The application sees already-authenticated users via headers (X-Amzn-Oidc-*).

      Most applications support this as it's transparent to the application.

      Returns:
      true if ALB-level OIDC is supported (default: true)

    • supportsCognito

      default boolean supportsCognito()
      Returns whether this application supports Cognito as an identity provider.

      Cognito provides:

      • User pool with email/password authentication
      • MFA support (TOTP, SMS)
      • OAuth 2.0 / OIDC endpoints
      • Hosted UI for login
      Returns:
      true if Cognito OIDC is supported (default: true)

    • supportsIdentityCenterSaml

      default boolean supportsIdentityCenterSaml()
      Returns whether this application supports IAM Identity Center SAML.

      IAM Identity Center (formerly AWS SSO) provides:

      • SAML 2.0 authentication
      • Enterprise directory integration
      • Group-based access control
      • Centralized user management

      Applications that use SAML (Mattermost, Metabase) support this. Applications that only use OIDC may not.

      Returns:
      true if IAM Identity Center SAML is supported (default: false)

    • supportsApplicationOidc

      default boolean supportsApplicationOidc()
      Returns whether this application supports application-level OIDC.

      Application-level OIDC means the application handles authentication itself using its built-in OIDC/OAuth support. The application needs:

      • Client ID and secret
      • OIDC endpoints (issuer, auth, token, userinfo)
      • Redirect URL configuration

      Examples: Jenkins OIDC plugin, GitLab OmniAuth, Grafana generic_oauth

      Returns:
      true if application-level OIDC is supported (default: true if integration exists)

    • getAuthenticationType

      default String getAuthenticationType()
      Returns the authentication type this integration uses.
      Returns:
      "OIDC" or "SAML"

    • needsSamlCertificate

      default boolean needsSamlCertificate()
      Returns whether this application needs a SAML IdP certificate at startup.

      SAML applications typically need the IdP's X.509 certificate to verify SAML assertions. This certificate is fetched from the IdP metadata URL and mounted into the container via an init container.

      Returns:
      true if SAML certificate is required (default: true for SAML apps)

    • getSamlCertificateMountPath

      default String getSamlCertificateMountPath()
      Returns the directory path where SAML certificate should be mounted.

      This path is used by the init container to write the certificate and by the main container to read it.

      Examples:

      • Mattermost: /mattermost/saml (NOT /mattermost/config to avoid conflicts)
      • Metabase: /metabase/saml
      Returns:
      mount path for SAML certificate directory

    • getSamlCertificateFilePath

      default String getSamlCertificateFilePath()
      Returns the full file path for the SAML IdP certificate.

      This is the complete path including filename where the certificate will be written. Applications reference this path in their SAML configuration.

      Returns:
      full path to the certificate file

    • getSamlCertificateEnvVar

      default String getSamlCertificateEnvVar()
      Returns the environment variable name for the SAML certificate path.

      Applications configure SAML via environment variables. This returns the variable name that holds the certificate file path.

      Examples:

      • Mattermost: MM_SAMLSETTINGS_IDPCERTIFICATEFILE
      • Metabase: MB_SAML_IDENTITY_PROVIDER_CERTIFICATE
      Returns:
      environment variable name for certificate path, or null if not applicable