---
title: Configure an OIDC connector
description: Register Sudomimus as a confidential OIDC client at your identity
  provider, create the connector, and verify enterprise sign-in end to end.
editUrl: true
head: []
template: doc
sidebar:
  order: 5
  hidden: false
  attrs: {}
pagefind: true
draft: false
---

import { CardGrid, LinkCard } from "@astrojs/starlight/components";

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](https://with.sudomimus.com/);
- 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**.

:::note[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:

<CardGrid>
<LinkCard
    title="Application-managed sign-in"
    description="Add an ENTERPRISE_FEDERATION_APPLICATION_MANAGED Layer 1 rule that names this connector."
    href="/en-us/domains-federation/sign-in-with-your-idp/#application-managed-sign-in"
/>
<LinkCard
    title="Domain-managed SSO"
    description="Verify a domain, bind this connector to SSO_ONLY, and allow ENTERPRISE_FEDERATION_DOMAIN_MANAGED on participating applications."
    href="/en-us/domains-federation/sign-in-with-your-idp/#forced-sso-domain-managed"
/>
</CardGrid>

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

<CardGrid>
<LinkCard
    title="Federation connector reference"
    description="Field semantics, lifecycle rules, validation, and secret handling."
    href="/en-us/domains-federation/federation-connectors/"
/>
<LinkCard
    title="Configure a SAML connector"
    description="Use SAML 2.0 instead of OIDC for the same enterprise-federation modes."
    href="/en-us/domains-federation/configure-saml-connector/"
/>
</CardGrid>