Identity providers

Register an application at your provider, a web application with a client secret, and give it this redirect URI:

https://<alias>.sso.ezgh.app/federation/oidc/callback

Then create the identity provider:

curl -X POST https://sso.ezghcloud.com/v1/organizations/$ORG_ID/sso/identity-providers \
  -H "Authorization: Bearer $EZGH_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "name": "Okta",
    "protocol": "oidc",
    "oidc": { "issuer": "https://acme.okta.com", "clientId": "0oa…", "clientSecret": "…" },
    "domains": ["acme.com"]
  }'

The answer adds redirectUri and, once fetched, the validated discovery. ID tokens must be signed with RS256–512, PS256–512 or ES256–512.

SAML needs the identity provider’s metadata to create it, and the service provider values your identity provider needs contain its ID. So:

1. Create a SAML application at your identity provider. If it insists on an ACS URL and entity ID before it gives you metadata, enter temporary values.

2. Create the identity provider with metadataUrl (the provider’s metadata URL) or metadataXml (the metadata document, up to 256 KiB):

   curl -X POST https://sso.ezghcloud.com/v1/organizations/$ORG_ID/sso/identity-providers \
     -H "Authorization: Bearer $EZGH_API_KEY" -H "Content-Type: application/json" \
     -d '{ "name": "Entra ID", "protocol": "saml",
           "saml": { "metadataUrl": "https://login.microsoftonline.com/…/federationmetadata.xml?appid=…" } }'

3. Enter the answer’s saml.serviceProvider at your identity provider: entityId as the entity ID (audience), and acsUrl as the ACS (reply) URL. metadataUrl serves the same as SAML metadata.

   Value	Form
   Entity ID, metadata	https://<alias>.sso.ezgh.app/federation/saml/metadata/<identity provider ID>
   ACS URL	https://<alias>.sso.ezgh.app/federation/saml/acs/<identity provider ID>

4. Route the domains: UpdateIdentityProvider with domains.

The metadata must describe one identity provider with an https HTTP-Redirect single sign-on URL and 1 to 10 RSA (2048 bits or more) or ECDSA signing certificates. The answer shows its entityId, ssoUrl and certificates with their expiry.

Requirements for responses:

• Both the response and its assertion must be signed, with SHA-256 or stronger (SHA-1 is refused). Encrypted assertions are refused.
• Only SP-initiated sign-in: a response that EZGH SSO didn’t ask for (IdP-initiated) is refused.
• The assertion must name the service provider’s entity ID as its audience, and a NameID that isn’t transient.

OIDC (recommended):

1. In the Okta Admin Console, create an app integration: OIDC - OpenID Connect, Web Application.
2. Sign-in redirect URIs: https://<alias>.sso.ezgh.app/federation/oidc/callback. Assign the people or groups who should use it.
3. Copy the Client ID and Client secret. The issuer is your Okta domain, such as https://acme.okta.com (or a custom authorization server’s issuer).
4. For groups, add a groups claim named groups to the ID token (in the app’s Sign On settings, a groups claim filter). If your setup puts it behind the groups scope, add groups to scopes.

SAML: create a SAML 2.0 app integration. Single sign-on URL is the ACS URL and Audience URI the entity ID; Name ID format EmailAddress, Application username Email. Keep the response and the assertion signed. Add a group attribute statement named groups. Use the app’s metadata URL as metadataUrl.

OIDC:

1. In the Entra admin center, App registrations > New registration, with a Web redirect URI https://<alias>.sso.ezgh.app/federation/oidc/callback.
2. Certificates & secrets: create a client secret. The client ID is the Application (client) ID.
3. The issuer is https://login.microsoftonline.com/<tenant ID>/v2.0.
4. Token configuration: add the optional email claim to the ID token, and a groups claim. Entra sends group object IDs, so use those as idpGroup in group mappings.

SAML:

1. Enterprise applications > New application > Create your own application (non-gallery), then Single sign-on > SAML.
2. Identifier (Entity ID) is the entity ID and Reply URL the ACS URL.
3. Under SAML Certificates, set Signing option to Sign SAML response and assertion. Entra signs only the assertion by default, which EZGH SSO refuses.
4. For groups, add a group claim, and set groupsAttribute to its name (http://schemas.microsoft.com/ws/2008/06/identity/claims/groups unless you rename it).
5. Use the App Federation Metadata Url as metadataUrl.

SAML (sends groups):

1. In the Google Admin console, Apps > Web and mobile apps > Add custom SAML app.
2. Download the IdP metadata, and use it as metadataXml (Google doesn’t publish a metadata URL, so update it when Google’s certificate changes).
3. ACS URL is the ACS URL and Entity ID the entity ID. Select Signed response. Name ID format EMAIL, Name ID the primary email.
4. Under Group membership, map the groups to an app attribute named groups.
5. Turn the app on for the people who should use it.

OIDC (no groups): create an OAuth client in the Google Cloud console, type Web application, with the redirect URI above. The issuer is https://accounts.google.com. Make the OAuth consent screen Internal so only your Workspace’s accounts can sign in. Google’s ID tokens carry no groups, so group mappings other than * don’t apply.