SAML applications

A saml application is a SAML 2.0 service provider, such as Slack, Zoom or your own app, that signs your directory’s people in with your directory as its identity provider (IdP). Only users you assign to the application, directly or through a group, can sign in to it.

SAML applications count against the same limit as other applications: up to 200 per directory. You need sso.applications.create.

Create a SAML application

Start from one of three places:

• The catalog: a common SaaS application with its settings filled in. You enter the values that are yours, such as your Slack domain. See The catalog.
• The service provider’s metadata: a metadata URL or the XML document. EZGH SSO imports the entity ID, the HTTP-POST ACS URLs, the single logout URL and the certificates from it, once. It doesn’t refresh them later.
• The details: the service provider’s entity ID and ACS URLs.

# From the catalog
ezgh sso applications create --catalog slack --param slackDomain=acme.slack.com

# From the service provider's metadata
ezgh sso applications create --name Grafana --kind saml --metadata-url https://grafana.acme.com/saml/metadata

# From the details
ezgh sso applications create --name Tool --entity-id https://tool.acme.com --acs-url https://tool.acme.com/saml/acs \
  --attribute 'email=${user.email}' --attribute 'groups=${user.groups}'

{
  "name": "Grafana",
  "kind": "saml",
  "saml": { "metadataUrl": "https://grafana.acme.com/saml/metadata" }
}

{
  "name": "Tool",
  "kind": "saml",
  "saml": {
    "entityId": "https://tool.acme.com",
    "acsUrls": ["https://tool.acme.com/saml/acs"],
    "attributes": [{ "name": "email", "value": "${user.email}" }]
  }
}

Then assign users or groups, and register the IdP at the service provider.

Register the IdP at the service provider

Each SAML application has its own IdP: its own entity ID and metadata, with your directory’s signing certificate. So you can add the same service provider twice. saml.idp in the application, the console’s Sign-in tab and ezgh sso applications idp show:

Service providers that import IdP metadata take the metadata URL. Others take the entity ID, the SSO URL and the certificate:

ezgh sso applications idp Grafana
ezgh sso applications idp-certificate Grafana > ezgh-sso.pem

In the console, select Download certificate on the Sign-in tab.

If you change your directory’s alias, these URLs change: update the service provider.

Settings

saml holds the service provider’s settings. On update, only the fields you send change; metadataUrl or metadataXml imports metadata again.

The answer also shows metadataUrl and metadataImportedAt (where and when metadata was last imported) and idp.

NameID formats

A request whose NameIDPolicy asks for a format other than the application’s (or unspecified) gets an InvalidNameIDPolicy error response.

Attributes

Each attribute is { "name", "nameFormat", "value" }. name is what the service provider expects, up to 256 characters, and each name appears once. nameFormat is unspecified (the default), uri or basic. value is a template of up to 1,024 characters:

Literal text and variables can be mixed, such as ${user.givenName} ${user.familyName}. An attribute whose value is a single variable the user has no value for is left out.

ezgh sso applications update Tool --attribute 'email=${user.email}' --attribute 'department=${user.department}' \
  --attribute 'groups=${user.groups}' --groups-filter all

Signing and encryption

Responses and assertions are signed with RSA-SHA256 and exclusive canonicalization. By default both the Response and the Assertion are signed, which most service providers accept; turn one off only if the service provider needs it.

With encryptAssertions, the assertion is signed, then encrypted to the service provider’s encryption certificate: the content with AES-128-GCM (default) or AES-256-CBC, the key with RSA-OAEP. Add the certificate to spCertificates with use: "encryption", or import it with the metadata.

ezgh sso applications update Slack --encrypt-assertions --encryption-certificate slack-encryption.pem

Certificates

Each directory has one SAML signing key: RSA-3072, with a self-signed certificate valid for three years. It’s made when you create the directory’s first SAML application, and every SAML application uses it.

Each certificate shows its fingerprintSha256, subject, notBefore, notAfter and warnAt, 60 days before it expires, from when the console warns you.

Rollover: service providers that read your IdP metadata URL pick up the next certificate on their own. For the others, give them the next certificate once it’s published and before the active one expires:

ezgh sso applications idp-certificate Slack --next > ezgh-sso-next.pem

You can’t roll the certificate early.

How sign-in works

Service provider-initiated: the service provider sends an AuthnRequest to the SSO URL, with the HTTP-Redirect or HTTP-POST binding. EZGH SSO checks that:

• its Issuer is the application’s entityId;
• its Destination, when sent, is the SSO URL, and it was issued within the last 90 seconds;
• the ACS it names, by URL or index, is one of acsUrls (without one, the default is used);
• its RelayState is at most 1,024 bytes, and the request is at most 64 KiB.

A request that fails these checks gets an error page; nothing is sent to an ACS URL. A valid request continues with the person’s portal session, or they sign in first. With ForceAuthn, they sign in again unless they signed in after the request was made. With IsPassive, someone who would have to sign in gets a NoPassive error response instead. A ProtocolBinding other than HTTP-POST gets UnsupportedBinding.

IdP-initiated: opening the SSO URL without a request (the portal tile does this) signs the person in to the default ACS URL, with defaultRelayState. It’s refused when idpInitiated is off. A RelayState in the URL is never used.

Portal tiles: assigned users see a tile for each SAML application that allows IdP-initiated sign-in. The tile can show the application’s own logo.

Either way, the person must be assigned, checked at every sign-in: someone who isn’t sees an error page (with IsPassive, a RequestDenied response), recorded in Trails as a failed AuthorizeApplication.

The assertion

Single logout

Single logout is best effort, for the browser the request comes from. A LogoutRequest to the SLO URL (HTTP-Redirect or HTTP-POST), checked like an AuthnRequest, ends that browser’s portal session when it names the session (SessionIndex) or the user. That also ends the session’s OIDC grants without offline_access, with their back-channel logout notices. The signed LogoutResponse goes to the application’s sloUrl, or the person sees the signed-out page without one.

Other service providers the person signed in to aren’t told, and EZGH SSO never sends a LogoutRequest itself.

Not supported

• Signed requests aren’t verified. Signatures on AuthnRequest and LogoutRequest messages are ignored, and spCertificates with use: "signing" are stored but not used. Nothing a request says is trusted beyond what you registered: responses go only to registered ACS URLs, and a forged logout request can at most sign out the browser it’s sent from.
• No single logout propagation to other service providers, and no IdP-initiated logout.
• The HTTP-Artifact binding, RequestedAuthnContext (it’s ignored), pairwise persistent NameIDs, and refreshing imported metadata.

The catalog

ListCatalogApplications (ezgh sso catalog list, needs sso.catalog.list) returns 16 common SaaS applications: Slack, Zoom, GitHub Enterprise Cloud (organization), Atlassian Cloud, Salesforce, Google Workspace, AWS IAM Identity Center, Dropbox, Notion, Figma, Zendesk, PagerDuty, Asana, Miro, Sentry and Tailscale. Each entry has:

• parameters: the values you fill in, such as slackDomain, each with a label, a description, an example and a pattern. They replace {{name}} in the entry’s URLs.
• saml: SAML settings in this API’s terms (all but Tailscale), with the vendor’s setup steps in notes.
• oidc: OIDC client settings, where the vendor documents a generic OIDC identity provider (Salesforce, Zendesk and Tailscale), for an OIDC application.
• scim: a SCIM base URL and attribute mappings for outbound provisioning, where the vendor supports it.
• sources: the vendor documentation each part was checked against.

ezgh sso catalog get slack

The console and the CLI create the application from an entry’s SAML settings; the API takes the filled-in settings in CreateApplication.

Delete a SAML application

DeleteApplication (ezgh sso applications delete) removes it with its assignments and provisioning. Its users can’t sign in to it through EZGH SSO any more, and its tile leaves the portal.