Connecting your identity provider

In short

This page tells whoever runs your identity provider (IdP) what SpeculaPro needs. It lists only the values SpeculaPro shows you and what it expects to receive. Menus differ between IdP versions, so the steps on the IdP side are described in general terms: follow your IdP’s own guide for “register an OpenID Connect web application” or “add a SAML application”.

Every connection follows the same pattern:

1. Copy SpeculaPro’s values from Settings → Single sign-on.
2. Register SpeculaPro at the IdP with them.
3. Copy the IdP’s values back into SpeculaPro and save.
4. Claim your email domains.
5. Run Test connection and read what arrived: email, groups and multi-factor.

What SpeculaPro gives you

Value	Where it’s shown	Used by
Redirect URI	OpenID Connect panel	OIDC. It is your SpeculaPro address followed by /api/v1/auth/sso/oidc/callback
Post-logout redirect URI	OpenID Connect panel	OIDC, optional. Your SpeculaPro address followed by /login
SP entity ID (audience)	SAML panel	SAML. Your SpeculaPro address followed by /api/v1/auth/sso/saml/<workspace>/metadata
ACS URL (HTTP-POST)	SAML panel	SAML. Your SpeculaPro address followed by /api/v1/auth/sso/saml/<workspace>/acs
Single logout URL (HTTP-Redirect or HTTP-POST)	SAML panel	SAML, optional. Your SpeculaPro address followed by /api/v1/auth/sso/saml/<workspace>/slo. See Signing out
SP metadata	Download SP metadata, once SAML settings are saved	SAML. Contains the entity ID, the ACS URL, the single logout URL and SpeculaPro’s signing certificate
SCIM base URL (tenant URL) and a token	SCIM provisioning panel	Optional, either protocol. Lets the IdP create and deactivate accounts and push groups. See SCIM provisioning

Always copy these from Settings rather than typing them: the workspace name and your address must match exactly.

What SpeculaPro needs back

	OpenID Connect	SAML 2.0
The IdP’s identity	The issuer URL. SpeculaPro reads /.well-known/openid-configuration from it	The IdP metadata, as a URL or pasted XML. It must offer an HTTP-Redirect single sign-on service
Credentials	A client ID and client secret for a web application using the authorization code flow	None: trust comes from the signing certificate in the metadata
Who the person is	sub (always present)	A persistent or email NameID. Transient NameIDs are refused
Email	The email claim, with email_verified set to true (or turn that check off; see the caution)	An email attribute (mail, email, emailaddress and their common long forms are found automatically) or an email NameID
Groups (only if you map groups to roles)	A claim listing them, often groups	An attribute listing them
Multi-factor (optional)	amr or acr values	AuthnContextClassRef, or Microsoft’s authnmethodsreferences attribute
Signing	Tokens signed with an asymmetric key (RSA, ECDSA or EdDSA). Tokens signed with the client secret (HMAC) are refused	Each assertion signed. Signing only the response isn’t enough

Microsoft Entra ID (OpenID Connect)

1. In Entra ID, register a web application. Add SpeculaPro’s Redirect URI as a web redirect URI, and the Post-logout redirect URI as the front-channel sign-out destination if you want sign-out to reach Entra ID too.
2. Create a client secret and note when it expires.
3. In SpeculaPro, enter:
   • Issuer URL: Entra ID’s v2.0 issuer for your tenant, in the form https://login.microsoftonline.com/<your tenant ID>/v2.0;
   • the application’s client ID and the client secret.
4. Make sure the token carries the user’s email. Entra ID doesn’t always include email and email_verified in ID tokens. Run Test connection: if the email is missing (email_missing) or not marked verified (email_not_verified), add the optional email claim in Entra ID, or, if only your IT team can set users’ addresses, turn off Require a verified email.
5. For groups, configure Entra ID to emit the groups claim and set Groups claim or attribute to groups. Entra ID sends group object IDs by default: put those IDs in the Group → role table.
6. Entra ID reports multi-factor with mfa in amr, which is in the default list.

Client secrets expire

Entra ID client secrets have an expiry date. Diary it, and save a new secret in SpeculaPro before the old one expires, or every SSO sign-in will fail with token_exchange_failed. Break-glass administrators can still sign in with their password.

Provisioning (optional). Under the enterprise application’s Provisioning, choose automatic mode, enter SpeculaPro’s SCIM base URL as the Tenant URL and a SpeculaPro SCIM token as the Secret Token. Whatever attribute you map to userName must hold the person’s email address. Groups arrive over SCIM by name, so put group names in the Group → role table if you provision groups. See SCIM provisioning.

Okta

Okta supports both protocols. Choose one.

OpenID Connect

1. In Okta, create an OIDC web application with the authorization code grant. Add SpeculaPro’s Redirect URI as a sign-in redirect URI and the Post-logout redirect URI as a sign-out redirect URI.
2. In SpeculaPro, enter the issuer of the Okta authorization server you use (your Okta domain, or an authorization server under it), the client ID and the client secret.
3. For groups, add a groups claim to the ID token in Okta, add its scope to SpeculaPro’s Scopes if your Okta setup requires one, and enter the claim name under Groups claim or attribute.

SAML

1. In Okta, create a SAML 2.0 application. Use SpeculaPro’s ACS URL as the single sign-on URL and the SP entity ID as the audience.
2. Make sure assertions are signed, and choose an email-address NameID.
3. Add a group attribute statement if you map groups to roles.
4. In SpeculaPro, give the application’s metadata URL, or paste its metadata XML.

Provisioning (optional, either protocol). In the Okta application’s provisioning settings, use SpeculaPro’s SCIM base URL as the SCIM connector base URL, userName as the unique identifier, and a SpeculaPro SCIM token as the bearer token (HTTP header authentication). The Okta username sent as userName must be the person’s email address. See SCIM provisioning.

Okta’s urn:okta:loa:2fa:any and the OIDC values mfa and otp are in the default multi-factor list.

Google Workspace (SAML)

1. In Google Workspace, add a custom SAML application. Download Google’s IdP metadata.
2. Use SpeculaPro’s ACS URL and SP entity ID for the service provider details, and choose email as the NameID format, with the primary email as its value.
3. If you want group membership, map it to an attribute and enter that attribute’s name under Groups claim or attribute. Otherwise add people in SpeculaPro and give them roles there, or use a Default role.
4. Turn the application on for the people who need SpeculaPro.
5. In SpeculaPro, paste the downloaded metadata XML.

Google doesn’t usually send an authentication context that SpeculaPro recognises as multi-factor. Unless you add a value that your setup really sends, people who have a SpeculaPro authenticator enter their code after Google, and Require multi-factor at the IdP would refuse everyone. Enforce 2-step verification in Google Workspace, and keep SpeculaPro’s own two-factor in place.

Keycloak (often self-hosted)

1. In your Keycloak realm, create an OpenID Connect client with client authentication on and the standard (authorization code) flow. Add SpeculaPro’s Redirect URI as a valid redirect URI and the Post-logout redirect URI as a valid post-logout redirect URI.
2. In SpeculaPro, enter the realm’s issuer, in the form https://<keycloak host>/realms/<realm>, the client ID and the client’s secret.
3. Make sure users have a verified email in Keycloak, or the sign-in is refused with email_not_verified.
4. For groups, add a group-membership mapper that puts groups in the ID token, and enter its claim name. Keycloak can send full group paths such as /compliance/mlro: map exactly what Test connection shows.
5. Keycloak’s acr and amr values depend on your authentication flows. Check what a test sign-in sends before adding values to Values that mean multi-factor.

Self-hosted IdPs on your own network

SpeculaPro refuses to contact identity providers at private network addresses unless your operator sets SP_SSO_ALLOW_PRIVATE=true. On a self-hosted installation with Keycloak or ADFS inside your network, ask them to turn it on. The IdP must still use HTTPS. See Configuration: single sign-on.

ADFS and other SAML IdPs

Import SpeculaPro’s SP metadata (or enter the SP entity ID and ACS URL), and give SpeculaPro the IdP’s federation metadata URL. Then check the three settings that most often cause a failed test:

• assertions must be signed, not only the response (saml_signature_invalid);
• the NameID must be persistent or email (saml_transient_nameid);
• the IdP must accept sign-in requests with the HTTP-Redirect binding.

ADFS reports multi-factor with http://schemas.microsoft.com/claims/multipleauthn, which is in the default list.

Related

• Single sign-on
• SCIM provisioning
• Single sign-on security