Single Sign-On

SAML 2.0 Integration

Federate your identity provider with Hygrade Business so employees sign in with the same credentials they use for the rest of your workplace — no additional passwords, no separate user directory to maintain.

Roles. Hygrade Business acts as the Service Provider (SP). Your organization’s IdP — Okta, Microsoft Entra ID, Ping, ADFS, Google Workspace, or any SAML 2.0-conformant IdP — is the authority for authentication.

Overview

Hygrade supports both SP-initiated and IdP-initiated sign-in. In the SP-initiated flow, users land on the Hygrade portal and are redirected to your IdP to authenticate, then bounced back with a signed assertion. In the IdP-initiated flow, users launch Hygrade from a tile in your corporate app launcher.

Protocol: SAML 2.0
Assertion binding (IdP → SP): HTTP-POST
Request binding (SP → IdP): HTTP-Redirect
Signed assertions: required
Encrypted assertions: supported, not required
Single Logout (SLO): supported (HTTP-Redirect)
NameID format: emailAddress

Hygrade service provider metadata

Provide these values to your identity team, or import our metadata XML directly — most IdPs accept a metadata URL and will configure themselves automatically.

Entity ID (Audience)

PRODhttps://order.hygradebusiness.com/saml/metadata

TESThttps://test.hygradebusiness.com/saml/metadata

Assertion Consumer Service

PRODhttps://order.hygradebusiness.com/saml/acs

TESThttps://test.hygradebusiness.com/saml/acs

Single Logout Service

PRODhttps://order.hygradebusiness.com/saml/sls

TESThttps://test.hygradebusiness.com/saml/sls

SP metadata XML

PRODhttps://order.hygradebusiness.com/saml/metadata

TESThttps://test.hygradebusiness.com/saml/metadata

NameID format

urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress

ACS binding

urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST

RelayState (optional)

Deep-link path, e.g. /tab/forms/catalog/1234

Example SP metadata

The live metadata document is served at the URL above. A representative excerpt:

sp-metadata.xml

<EntityDescriptor xmlns="urn:oasis:names:tc:SAML:2.0:metadata"
    entityID="https://order.hygradebusiness.com/saml/metadata">
  <SPSSODescriptor AuthnRequestsSigned="true"
      WantAssertionsSigned="true"
      protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
    <KeyDescriptor use="signing">
      <KeyInfo xmlns="http://www.w3.org/2000/09/xmldsig#">
        <X509Data><X509Certificate>MIIDazCCAlOgAwIBAgIUZ...</X509Certificate></X509Data>
      </KeyInfo>
    </KeyDescriptor>
    <SingleLogoutService
        Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect"
        Location="https://order.hygradebusiness.com/saml/sls"/>
    <NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress</NameIDFormat>
    <AssertionConsumerService index="0" isDefault="true"
        Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"
        Location="https://order.hygradebusiness.com/saml/acs"/>
  </SPSSODescriptor>
</EntityDescriptor>

Required SAML attributes

The SAML <AttributeStatement> returned by your IdP must include the attributes below. Hygrade uses these to create or update the shopper record on each sign-in ("just-in-time provisioning"), unless SCIM is enabled.

Attribute	Type	Required	Description
`NameID`	string	Yes	Email address, sent as the SAML Subject’s `NameID`. Used as the stable user identifier.
`email`	string	Yes	Same value as NameID. Included as an attribute for IdPs that don’t surface the subject separately.
`firstName`	string	Yes	Given name. Displayed in the portal header and on order confirmations.
`lastName`	string	Yes	Family name.
`custId`	string	Optional	The Hygrade customer account identifier assigned to your organization. Not required — Hygrade will infer the customer account from the IdP’s entity ID when this attribute is omitted. Provide only when your IdP federates multiple Hygrade customer accounts.
`groups`	string (multi-valued)	Recommended	Role membership. Any of `buyer`, `approver`, `chief_approver`, `customer_admin`. Controls approval routing and catalog access.
`costCenter`	string	Optional	Default cost center code applied to orders placed by this user.
`department`	string	Optional	Free-text department label; surfaced on reports and exports.
`employeeId`	string	Optional	Your internal employee identifier. Written through to order records.

Example assertion

assertion-excerpt.xml

<saml:AttributeStatement>
  <saml:Attribute Name="email">
    <saml:AttributeValue>jane.doe@acmecorp.com</saml:AttributeValue>
  </saml:Attribute>
  <saml:Attribute Name="firstName">
    <saml:AttributeValue>Jane</saml:AttributeValue>
  </saml:Attribute>
  <saml:Attribute Name="lastName">
    <saml:AttributeValue>Doe</saml:AttributeValue>
  </saml:Attribute>
  <saml:Attribute Name="custId">
    <saml:AttributeValue>ACME001</saml:AttributeValue>
  </saml:Attribute>
  <saml:Attribute Name="groups">
    <saml:AttributeValue>buyer</saml:AttributeValue>
    <saml:AttributeValue>approver</saml:AttributeValue>
  </saml:Attribute>
  <saml:Attribute Name="costCenter">
    <saml:AttributeValue>CC-4420</saml:AttributeValue>
  </saml:Attribute>
</saml:AttributeStatement>

What Hygrade needs from your IdP

Share the following with your implementation engineer. A metadata URL is strongly preferred — it future-proofs certificate rotations on your side.

IdP Entity IDstringrequired

The unique issuer identifier your IdP sends in the SAML <Issuer> element.

SSO URLURLrequired

The HTTP-Redirect endpoint Hygrade will send AuthnRequest messages to.

X.509 signing certificatePEMrequired

The public certificate Hygrade will use to verify assertion signatures.

IdP metadata URL or XML fileURL / file

Strongly preferred. Hygrade refreshes from this URL periodically so that your next signing cert rotation is automatic.

Single Logout URLURL

Optional. If provided, signing out of Hygrade will also terminate the IdP session.

Identity provider setup

Step-by-step walkthroughs for the most common IdPs. The underlying SAML requirements are identical — only the admin UI differs.

Okta

In the Okta Admin Console, open Applications → Applications and click Create App Integration. Select SAML 2.0.
Give the app the name Hygrade Business and upload the Hygrade logo (available on request).
Under SAML Settings:
- Single sign-on URL: https://order.hygradebusiness.com/saml/acs
- Audience URI (SP Entity ID): https://order.hygradebusiness.com/saml/metadata
- Name ID format: EmailAddress
- Application username: Email
Add the attribute statements in the table below (map to your Okta profile attributes).
After saving, open the Sign On tab and copy the Metadata URL. Send it to integrations@hygradebusiness.com.
Assign the app to the appropriate Okta groups.

Name	Name format	Value
`email`	Basic	`user.email`
`firstName`	Basic	`user.firstName`
`lastName`	Basic	`user.lastName`
`custId`	Basic	optional constant, e.g. `"ACME001"` — only if federating multiple Hygrade accounts
`groups`	Basic	`Matches regex` · `^hygrade-.*`

Microsoft Entra ID (formerly Azure AD)

In the Entra admin center, open Enterprise applications → New application → Create your own application. Name it Hygrade Business and choose Integrate any other application you don’t find in the gallery.
Open Single sign-on and select SAML.
Edit Basic SAML Configuration:
- Identifier (Entity ID): https://order.hygradebusiness.com/saml/metadata
- Reply URL (ACS): https://order.hygradebusiness.com/saml/acs
- Sign on URL: https://order.hygradebusiness.com/saml/login
- Logout URL: https://order.hygradebusiness.com/saml/sls
Edit Attributes & Claims and add claims matching the attribute table above, pointed at the corresponding user. fields (for example user.givenname, user.surname, user.mail).
Under SAML Signing Certificate, download Federation Metadata XML and send it to integrations@hygradebusiness.com.
Assign the relevant users or groups under Users and groups.

Ping Identity (PingOne / PingFederate)

In PingOne, open Applications → Add Application → Advanced Configuration → SAML.
Provide the following under Configure SAML Connection:
- ACS URL: https://order.hygradebusiness.com/saml/acs
- Entity ID: https://order.hygradebusiness.com/saml/metadata
- SLO Endpoint: https://order.hygradebusiness.com/saml/sls
- Subject NameID Format: urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress
Under Attribute Mapping, map each Hygrade attribute name to the corresponding PingOne directory attribute. custId is optional — set it to a literal constant only if a single IdP federates multiple Hygrade customer accounts.
Enable Sign Assertion. Encryption is optional.
From the app’s Configuration tab, download the SAML Metadata and forward it to Hygrade.

Active Directory Federation Services (ADFS)

Open AD FS Management → Relying Party Trusts → Add Relying Party Trust.
Choose Claims aware, then Import data about the relying party published online and enter: https://order.hygradebusiness.com/saml/metadata.
Accept the default access control policy (or scope it to your SSO AD group).
After creation, open Edit Claim Issuance Policy and add the following rules:
- Send LDAP Attributes as Claims — map E-Mail-Addresses → email, Given-Name → firstName, Surname → lastName.
- Transform an Incoming Claim — transform email → Name ID with format Email.
- Send Claims Using a Custom Rule — (optional) issue custId as a literal string if your ADFS federates multiple Hygrade customer accounts.
Export the ADFS federation metadata from https://adfs.your-domain.com/FederationMetadata/2007-06/FederationMetadata.xml and send the URL to Hygrade.

Sign-in flow

The SP-initiated flow is the default. A user landing on order.hygradebusiness.com who is not yet authenticated is redirected to your IdP, authenticates, and is returned with a signed assertion.

SP-initiated SSO

  Browser                    Hygrade (SP)                    Your IdP
     │                             │                              │
     │  GET /portal ────────────── │                              │
     │  <302 to IdP SSO URL> ←──── │                              │
     │                             │                              │
     │  GET ?SAMLRequest=...  ─────────────────────────────────→  │
     │                             │                              │
     │                             │        (authenticate)        │
     │                             │                              │
     │  POST /saml/acs  ←──────────────────────────────────────── │
     │  SAMLResponse=<signed assertion>                           │
     │                             │                              │
     │                             │ verify signature, extract    │
     │                             │ attributes, start session    │
     │                             │                              │
     │  <302 to RelayState> ←───── │                              │

Testing your integration

Install SAML-tracer (Firefox / Chrome) to inspect requests and responses in the browser.
Navigate to https://order.hygradebusiness.com/saml/login and authenticate.
Confirm that the SAMLResponse contains all required attributes and is signed by your IdP’s current certificate.
On your first successful round-trip, Hygrade will show a test mode banner; your implementation engineer will flip the tenant to production once you confirm the mapping is correct.

✓

Testing endpoint. Use https://order.hygradebusiness.com/saml/debug during integration. It decodes the assertion and displays all received attributes without starting a portal session. The endpoint is automatically disabled once your tenant is placed in production.

Troubleshooting

Invalid signature / signature verification failed

Your IdP is signing assertions with a certificate Hygrade doesn’t have on file, or the certificate has been rotated. Resend your current metadata XML or signing certificate. If you provided a metadata URL, confirm it is reachable from the public internet.

Missing required attribute

The assertion reached Hygrade but is missing a required attribute. Review the attribute table and confirm each is emitted by your IdP. Attributes marked Optional can be left out; the required ones (email, firstName, lastName) must be present on every assertion.

NameID policy mismatch / `urn:oasis:names:tc:SAML:2.0:status:InvalidNameIDPolicy`

The IdP is returning a NameID format other than emailAddress. Reconfigure the application’s NameID settings; Hygrade will not accept transient or persistent NameIDs.

Clock skew / `NotBefore` condition failed

Hygrade allows 180 seconds of clock skew on SAML timestamps. If you see this error, verify both your IdP and the requesting device have accurate time (NTP-synchronized).

User authenticates but cannot access any catalog

The user was provisioned successfully but no groups were sent, so no role was granted. Either include a groups attribute in the assertion or ask your Hygrade admin to assign a default role to the user in the portal.

Security & certificate rotation

Hygrade’s SAML signing certificate is rotated every 24 months. Subscribers to a metadata URL receive the new certificate automatically.
60 days before rotation, a notice is sent to the integration and security contacts on file, and the next cert is published in the metadata document with a future validFrom date.
You may rotate your IdP signing certificate at any time by replacing the cert in your federation metadata. No action is required on our side if you provided a metadata URL.
All SAML endpoints enforce TLS 1.2 or higher.
Report suspected security issues to security@hygradebusiness.com.

→

Next: once SAML is live, many customers enable SCIM provisioning so that hires and departures sync automatically, rather than relying on just-in-time user creation.

SAML 2.0 Integration

Overview

Hygrade service provider metadata

Example SP metadata

Required SAML attributes

Example assertion

What Hygrade needs from your IdP

Identity provider setup

Okta

Microsoft Entra ID (formerly Azure AD)

Ping Identity (PingOne / PingFederate)

Active Directory Federation Services (ADFS)

Sign-in flow

Testing your integration

Troubleshooting

Invalid signature / signature verification failed

Missing required attribute

NameID policy mismatch / urn:oasis:names:tc:SAML:2.0:status:InvalidNameIDPolicy

Clock skew / NotBefore condition failed

User authenticates but cannot access any catalog

Security & certificate rotation

NameID policy mismatch / `urn:oasis:names:tc:SAML:2.0:status:InvalidNameIDPolicy`

Clock skew / `NotBefore` condition failed