Skip to content

Configuration - SSO (Single Sign-On)

Galigeo supports two SSO methods:

  • OAuth2 - configured via the administration interface
  • SAML V2 - configured via the gaia.properties file

OAuth2

Supported providers

  • Google
  • Microsoft (Azure AD / Entra ID)
  • Salesforce
  • Salesforce Sandbox
  • ArcGIS Online

Prerequisites

  • OAuth2 license activated on your Galigeo instance
  • Administrator access to Galigeo

Step 1: Create an application on the provider

Register a new OAuth2 application on the chosen provider's developer console:

Provider Developer console
Google Google Cloud Console
Microsoft Azure Portal - App registrations
Salesforce Salesforce Setup - App Manager
ArcGIS Online ArcGIS for Developers

When configuring the application, set the redirect URI (callback URL) to:

http(s)://<SERVER>:<PORT>/Galigeo/oauth/callback

Step 2: Configure OAuth2 in Galigeo

  1. Log in to Galigeo as an administrator
  2. Navigate to Administration > oauth2
  3. Check Enabled
  4. Select the provider type from the dropdown list
  5. Enter the Client ID obtained from the provider
  6. Enter the Client Secret obtained from the provider
  7. (Optional) Enter the Organization ID — required for Microsoft (this is the Azure AD Tenant ID)
  8. The Callback URI is displayed automatically — verify it matches the one configured on the provider
  9. Click Save

Result

  • A SSO button appears on the Galigeo login page
  • The user is redirected to the provider for authentication
  • After successful authentication, the user is redirected back to Galigeo

SAML V2

Prerequisites

  • A SAML 2.0 compatible Identity Provider (IdP): Keycloak, ADFS, CyberArk, PingIdentity, Okta, etc.

Step 1: Configure the Identity Provider

Register Galigeo as a Service Provider (SP) in your IdP with the following parameters:

  • Entity ID: value of SAML_SPID_FROM_IDP (default: Galigeo)
  • ACS URL (Assertion Consumer Service):
  • Single-organization: http(s)://<SERVER>:<PORT>/Galigeo/saml/acs
  • Multi-organization: http(s)://<SERVER>:<PORT>/Galigeo/feature/saml2/acs/<orgId>

Important: For multi-organization setups, the path must use saml2 (not saml). Using /feature/saml/acs/<orgId> will not work.

Step 2: Configure Galigeo

Navigate to Administration > Technical settings > Advanced parameters and set these parameters :

Property Required Default Description
SAML_ENABLED Yes false Enable SAML SSO
SAML_IDP_BINDING_URL Yes — SSO URL of the IdP
SAML_SPID_FROM_IDP Yes Galigeo SP Entity ID registered in the IdP
SAML_SP_ACS_URL Yes {scheme}://{server}:{port}/{context}/saml/acs ACS URL (must match the one declared in the IdP)
SAML_IDP_INITIATED No false true = IdP-initiated flow (no AuthnRequest sent)
SAML_REQUEST_RELAY_STATE No {appContext} RelayState sent in the SAML request
SAML_RESP_PARAM No SAMLResponse Name of the HTTP parameter containing the SAML response
SAML_USE_NAMEID_4_LOGIN No true true = use NameID as login, false = use a custom attribute
SAML_USER_ATTRIBUTE No userId SAML attribute to use as login (when SAML_USE_NAMEID_4_LOGIN=false)
SAML_AUTOMATIC_ADD_USER No true Automatically create the user in Galigeo if they don't exist
SAML_ASSERTION_SIGNATURE_CHECK No false Verify the SAML assertion signature
SAML_DIGITAL_SIGNATURE_CERT_FILE No — Path to the IdP public certificate (required if signature check is enabled)

note You can also edit the file <GALIGEO_HOME>/config/gaia.properties and modify the parameters

Minimal configuration example

SAML_ENABLED=true
SAML_IDP_BINDING_URL=https://idp.example.com/saml/sso
SAML_SPID_FROM_IDP=Galigeo
SAML_SP_ACS_URL=https://galigeo.example.com/Galigeo/saml/acs

Multi-organization

Each organization can have its own SAML configuration in:

<GALIGEO_HOME>/orgs/{orgId}/config/gaia.properties

Multi-organization ACS URL

For multi-org setups, the SAML_SP_ACS_URL must include the organization identifier so that Galigeo can route the user to the correct organization after authentication.

Use the /feature/saml2/acs/{orgId} endpoint:

SAML_SP_ACS_URL=http(s)://<SERVER>:<PORT>/Galigeo/feature/saml2/acs/<orgId>

Important: The path must use saml2 (not saml). Using /feature/saml/acs/<orgId> will result in a redirect loop through the login page with orgId=null.

Multi-organization authentication URL

To initiate authentication for a specific organization:

/Galigeo/saml/authn?orgId=<orgId>

If the orgId is not provided or cannot be resolved, Galigeo falls back to the default organization.

Authentication flow (SP-initiated)

Single-organization

  1. The user navigates to /Galigeo/saml/authn
  2. Galigeo generates an AuthnRequest and redirects to the IdP
  3. The user authenticates on the IdP
  4. The IdP sends the SAMLResponse to /Galigeo/saml/acs
  5. Galigeo validates the assertion, creates the session, and redirects to the portal

Multi-organization

  1. The user navigates to /Galigeo/saml/authn?orgId=<orgId>
  2. Galigeo loads the SAML configuration for the specified organization
  3. Galigeo generates an AuthnRequest with the org-specific ACS URL and redirects to the IdP
  4. The user authenticates on the IdP
  5. The IdP sends the SAMLResponse to /Galigeo/feature/saml2/acs/<orgId>
  6. Galigeo validates the assertion, creates the session, and redirects to the organization's portal

Assertion signature verification

Two types of signatures exist in SAML, serving different purposes:

Direction Who signs Who verifies Purpose
AuthnRequest (SP → IdP) Galigeo IdP Proves the request comes from the legitimate SP
Assertion (IdP → SP) IdP Galigeo Proves the assertion comes from the legitimate IdP

This is the most critical signature. It prevents an attacker from forging a SAML assertion to impersonate any user.

If SAML_ASSERTION_SIGNATURE_CHECK=true:

  1. Export the IdP's public signing certificate (.crt file in PEM format)
  2. Place it in <GALIGEO_HOME>/resources/
  3. Set SAML_DIGITAL_SIGNATURE_CERT_FILE to the full path of the certificate file

AuthnRequest signature (SP → IdP) — optional

Galigeo signs its AuthnRequest by default. The IdP must have Galigeo's public certificate to verify the signature. If the IdP rejects the signature, either: - Import Galigeo's SP certificate into the IdP, or - Disable AuthnRequest signature verification in the IdP (refer to your IdP documentation)

Troubleshooting

Symptom Cause Solution
"Invalid requester" on the IdP SAML_SPID_FROM_IDP does not match the Client ID in the IdP Ensure both values are identical (case-sensitive)
"Invalid signature on document" on the IdP The IdP cannot verify the AuthnRequest signature Disable AuthnRequest signature verification in the IdP, or import Galigeo's SP certificate
"Invalid redirect URI" on the IdP The ACS URL is not in the IdP's allowed redirect URIs Add the exact ACS URL to the IdP's Valid Redirect URIs
User lands on orgId=default after login The orgId is lost during the SAML flow Use /feature/saml2/acs/{orgId} as ACS URL (not /saml/acs/{orgId}). Ensure the path uses saml2 not saml
orgId=null in the redirect The SAML_SP_ACS_URL does not include the orgId Set SAML_SP_ACS_URL to …/feature/saml2/acs/{orgId} in the org's gaia.properties
404 on the ACS endpoint Wrong URL path (e.g., /feature/saml/acs/… instead of /feature/saml2/acs/…) The correct path is /feature/saml2/… — ensure the 2 is present
User not created after login SAML_AUTOMATIC_ADD_USER=false Set to true or manually create the user in Galigeo before login