Configure an OIDC connector

This guide configures an external corporate identity provider as an OIDC federation connector. Sudomimus is the relying party: it redirects the browser to your IdP, validates the returned ID token, and then runs the normal Layer 1, Layer 2, and issuance pipeline.

Before you begin

You need:

• an organization in the With portal;
• permission to create an application at your IdP;
• an IdP that supports OpenID Connect discovery, Authorization Code flow, confidential clients, PKCE S256, and RS256-signed ID tokens; and
• a client secret issued by that IdP.

Decide whether the connector will appear as an application-specific “Sign in with …” button, enforce SSO for a verified domain, or both. The same connector supports both modes.

1. Create the client at your IdP

Create a web or confidential OIDC application at your IdP. Provider terminology differs, but configure these values:

IdP setting	Value
Application type	Web / confidential client
Grant or flow	Authorization Code
Redirect URI	https://federation.sudomimus.com/oidc/callback
PKCE	Enabled; S256 must be accepted
Client authentication	Client secret
Scopes	At least openid; normally openid email profile

The redirect URI must match exactly. Do not register the Core UI URL: provider responses terminate at Auth API.

Record the following values before leaving the IdP:

• the exact issuer URL;
• the client ID; and
• the client secret.

Issuer and discovery

Sudomimus reads <issuer>/.well-known/openid-configuration when the connector is saved. The discovery document must report that exact issuer and expose safe HTTPS authorization, token, and JWKS endpoints.

2. Configure claims

Every ID token must contain a stable, non-empty sub. Sudomimus also validates iss, aud, exp, iat, the per-login nonce, the RS256 signature, and its kid against the discovered JWKS.

The following standard claims are optional but useful:

Claim	Use
email + email_verified: true	Candidate email for account matching and email ownership
given_name	First-name profile value
family_name	Last-name profile value

An IdP-verified email is not automatically trusted by Sudomimus. It becomes usable for email ownership and account matching only when the connector’s organization has a current verified claim for that email domain.

3. Create the connector in With

In the With portal:

1. Open your organization.
2. Open Federation connectors and choose New connector.
3. Select OpenID Connect.
4. Enter a display name, issuer URL, client ID, and client secret.
5. Enter space- or newline-separated scopes. openid is required; openid email profile is the usual starting point.
6. Create the connector.

Sudomimus immediately validates the issuer and discovery document. A failure to reach or validate it is reported as FederationConnectorDiscoveryFailed.

The client secret is write-only. It is encrypted when saved and never returned by the connector API or portal. Keep the original value in your secret manager; enter a new value only when rotating it.

4. Put the connector to work

Choose one or both modes:

Application-managed sign-inAdd an ENTERPRISE_FEDERATION_APPLICATION_MANAGED Layer 1 rule that names this connector.

Domain-managed SSOVerify a domain, bind this connector to SSO_ONLY, and allow ENTERPRISE_FEDERATION_DOMAIN_MANAGED on participating applications.

The protocol is already fixed by the connector. Neither Layer 1 rule needs a separate OIDC/SAML switch.

5. Test the login

Use a non-administrator test user whose IdP account has the claims you configured.

For application-managed sign-in, start an Inquiry for the application and choose the connector’s “Sign in with …” button. For domain-managed SSO, enter an email on the verified SSO_ONLY domain and continue through the required connector.

Verify that:

• the browser reaches the expected IdP tenant;
• the IdP returns to the fixed Auth API callback;
• the login reaches the application’s normal completion path; and
• Layer 2 admits the test identity. Use EVERYONE for a protocol smoke test, or ensure an EMAIL rule matches an email Sudomimus can trust.

If saving succeeds but login fails, first check the registered redirect URI, the ID token’s nonce, audience and issuer, RS256 signing, JWKS kid, and whether the configured scopes actually release the expected claims. Browser-facing federation failures are intentionally generic.

Related

Federation connector referenceField semantics, lifecycle rules, validation, and secret handling.

Configure a SAML connectorUse SAML 2.0 instead of OIDC for the same enterprise-federation modes.