# Connect your corporate identity provider

SecurySign can broker authentication to a corporate identity provider (IdP) while the application continues to use OpenID Connect (OIDC). Register the provider, configure its broker callback and pass its approved alias as `kc_idp_hint` in authorization requests.

The provider can use either of these protocols:

| Protocol | Typical providers |
|---|---|
| OpenID Connect | Any OIDC provider with a discovery document |
| SAML 2.0 | Entra ID, Okta, ADFS, Google Workspace SAML |

## What you need

To register a provider, you'll need:

- An approved relying party (RP) with the `signa:integrator` scope. You need it to see the **Integrations** panel on the [RP dashboard](https://cloud.securysign.com/#/rp/dashboard).
- Admin access to your IdP, to create a client or an application for SecurySign.

## Connect an OIDC provider

Create a client for SecurySign in the IdP's administration console and save its client ID and secret. The discovery document must expose `authorization_endpoint`, `token_endpoint`, `userinfo_endpoint` and `jwks_uri`. Configure the client as confidential and provide its secret when registering the IdP with SecurySign.

On the RP dashboard, choose **Integrations → Add provider → Enterprise OAuth2 / OIDC**. Enter the issuer URL and select **Discover endpoints**, then enter the IdP-issued client ID, secret and supported scopes, typically `openid email`.

After approval, the provider page displays its alias and broker callback. Register that callback as the redirect URI in the IdP client and add it to the RP's callback list. Then set `kc_idp_hint=<alias>` in the application's authorization URL.

A new provider registration receives a new alias and broker callback. Update both the IdP callback and the application's hint when replacing a registration.

## Connect a SAML 2.0 provider

For Security Assertion Markup Language (SAML) 2.0, obtain the IdP's metadata URL or its entity ID, single sign-on URL and signing certificate. Enter those values under **Integrations → Add provider → Enterprise SAML 2.0** and require signed assertions.

After approval, configure SecurySign as the service provider (SP) in the IdP with the following values:

| Setting | Value |
|---|---|
| SP entity ID | `https://securysign.com/auth/realms/signa` |
| ACS or reply URL | The broker callback, `https://securysign.com/auth/realms/signa/broker/<alias>/endpoint` |
| Signing | RSA-SHA256 or stronger |

Configure the IdP to release each attribute under one of the accepted names below. The assertion-consumer-service (ACS) callback receives the signed response.

| Field | Attribute names |
|---|---|
| Email | `email`, `mail`, `urn:oid:0.9.2342.19200300.100.1.3`, `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress` |
| First name | `firstName`, `givenName`, `urn:oid:2.5.4.42`, `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname` |
| Last name | `lastName`, `sn`, `urn:oid:2.5.4.4`, `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname` |

Providers that use claim-URI attribute names can use those entries directly in the mapping.

Set `kc_idp_hint=<alias>` in the application's SecurySign authorization URL to select the approved SAML provider.

## Troubleshooting

| Symptom | Fix |
|---|---|
| No **Integrations** panel | Your RP needs the `signa:integrator` scope |
| `invalid_scope` | Request only scopes your provider advertises |
| Login never reaches your IdP | Wait for approval, and send the current alias in `kc_idp_hint` |
| Login fails at the callback | Add the broker callback to your IdP client and to your RP's redirect URIs |
| `Invalid signature in response from identity provider` | Copy the IdP's current signing certificate again, and sign with RSA-SHA256, not SHA-1 |
| Blank email after a SAML login | Map an email attribute from the table above |

The [Identity providers API](#/docs/api-identity-providers) exposes the same configuration using the contact account's access token. `GET /auth/login-config` returns current aliases and login endpoints; see [Login configuration](#/docs/api-relying-parties#get-login-config).