SAML¶

SAML 2.0 is browser single sign-on on the Professional package. It is off until an administrator configures it. It does not replace local login, personal access tokens, or OpenID Connect.

The Open Source package does not include the SAML routes. Its Administration → Authentication page states that SAML is in the Professional distribution.

On the Professional package the routes exist before a license is activated. Login and metadata stay unavailable until feature enterprise.sso.saml is entitled, which requires a valid Report Server Professional license. ACUGIS_EDITION does not enable it.

Routes¶

Method	Path	Role
`GET`	`/auth/saml/login`	Starts SP-initiated login
`POST`	`/auth/saml/acs`	Assertion Consumer Service
`GET`	`/saml/metadata`	SP metadata XML (`application/samlmetadata+xml`)

With JRS_BASE_PATH set, prefix each path. IdP-initiated login is not accepted. A response that did not start at /auth/saml/login fails.

Configure¶

Install the Professional package and activate a Report Server Professional license. See Licensing.
Open Administration → Authentication as a platform administrator.
Provide IdP metadata (URL or imported XML), then Import / Refresh Metadata and Test SAML Configuration.
Register the SP values shown on the page with the identity provider.

Value on the admin page	Give this to the IdP
SP Entity ID	Entity ID. Defaults to the public `/saml/metadata` URL when you do not set one.
ACS URL	Reply URL. Defaults to the public `/auth/saml/acs` URL.
SP metadata URL	Optional metadata download at `/saml/metadata`

The login button appears when SAML is enabled, the license feature is available, and the IdP entity ID, SSO URL, IdP certificate or metadata, SP private key, and SP certificate are all present. The default label is Sign in with plus the provider name, or Sign in with SAML SSO.

Fields¶

Field	Behavior
Provider name	Button label
IdP metadata URL or XML	Preferred source for entity ID, SSO URL, and signing certificates
IdP entity ID and SSO URL	Filled from metadata when import succeeds
NameID / subject attribute	Default `NameID`
Username, email, and display-name attributes	Email default `email`. Display name default `displayName`. When the configured value is empty, username also tries the Microsoft `claims/name` URI and then `userPrincipalName`; email tries `claims/emailaddress` and then `mail`; display name tries the Microsoft `claims/displayname` URI.
Groups attribute and JSON mappings	Optional. Default attribute name `groups`. If that attribute has no values, the server also reads the Microsoft `claims/groups` URI. It adds the user only to AcuGIS groups that already exist and are named in the mapping. It does not create groups.
Auto-provision	Default on
Allow email link	Default off
Clock skew	Default 120 seconds

If no SP key and certificate are stored, the server generates a self-signed pair and saves it when metadata or login is requested. ACUGIS_SAML_SP_KEY_FILE and ACUGIS_SAML_SP_CERT_FILE count as supplied only when that file is read successfully. A path that is set but cannot be read is ignored, and generation can still run. When one file of the pair was read and the other half is absent, that incomplete pair is an error. The server does not generate the missing half. Private keys are not returned by the admin UI.

At least one of local authentication, OIDC, or SAML must stay enabled.

The stable identity is the IdP entity ID plus the subject (NameID or the configured attribute).

Environment overrides¶

When set, these override the saved admin values: ACUGIS_SAML_ENABLED, ACUGIS_SAML_PROVIDER_NAME, ACUGIS_SAML_IDP_METADATA_URL, ACUGIS_SAML_IDP_ENTITY_ID, ACUGIS_SAML_IDP_SSO_URL, ACUGIS_SAML_SP_ENTITY_ID, ACUGIS_SAML_ACS_URL, ACUGIS_SAML_NAMEID_ATTRIBUTE, ACUGIS_SAML_USERNAME_ATTRIBUTE, ACUGIS_SAML_EMAIL_ATTRIBUTE, ACUGIS_SAML_DISPLAY_NAME_ATTRIBUTE, ACUGIS_SAML_CLOCK_SKEW, ACUGIS_SAML_SP_KEY_FILE, and ACUGIS_SAML_SP_CERT_FILE.

See Environment variables.

Local authentication stays on unless you turn it off. On a standalone server, SSO-only mode still accepts an existing local account and its password at /login?local=1 (same handler as /login.php?local=1). The server does not check an administrator flag. That login is audited as local_break_glass_login. The qcarta profile and a set JRS_CENTRAL_LOGIN_URL redirect /login to Central before local=1 is handled.

A successful SAML login creates the normal jrs_session cookie. Logout destroys that session. SAML single logout is not implemented. Personal access tokens and embed tokens are unchanged.

Public URL¶

Entity ID, ACS, and metadata URLs are built the same way as the OIDC callback: X-Forwarded-Host when that header is present, otherwise the request host, and https when TLS or X-Forwarded-Proto: https is present. Those header values are used as received. Report Server does not check that a trusted proxy set them. Register the public HTTPS URLs, including JRS_BASE_PATH when it is not /. Report Server does not terminate TLS. See Reverse proxy.

Refresh IdP metadata when the identity provider rotates signing certificates. The admin page lists the certificates it imported.

Troubleshooting¶

What you see	What to check
No SAML section	Open Source package.
Professional edition message	License missing, expired, or not valid.
No SAML button	Enabled flag, imported metadata, entity ID, SSO URL, signing certificate, and SP key material.
ACS failure	ACS URL and entity ID match the IdP, clock skew, and the login started at `/auth/saml/login`.
Metadata returns 404	License feature is off, or the Open Source package.
Metadata returns 503	SP key material could not be loaded or generated.
Locked out	On a standalone server, `/login?local=1` with an existing local account and its password. Central login does not honor `local=1`.
Groups missing	JSON mappings name groups that already exist in Report Server.

Audit actions include saml_login_success, saml_login_failed, saml_user_created, and saml_identity_linked. Assertions and private keys are not written into those events.