Identity Provider: Single Sign-On (SSO)

Date posted: 12/8/2025

Last edited: Dec 8, 2025

Version requirement: Hyku >= v5.1.0

This documentation is intended for account administrators, hosting providers, and developers to enable single sign-on (SSO) in a Hyku application.

Overview

Single Sign-On (SSO) is an authentication process that allows a user to log in using credentials from an existing provider. SSO reduces the number of credentials a user must have to interact with multiple applications. This makes authentication faster and safer by reducing password fatigue that can cause bad security habits, allows for control of many application through a centralized access point, and can help with security audits and compliance requirements.

SSO is basically a handshake between the credential provider application and Hyku. Each credential provider application is slightly different and will require configurations based on how the information is provided and what information is available.

Hyku (>= v5.1.0) can be configured to support SSO. Hyku supports SAML, CAS, and Openid Connect protocols for SSO.

This documentation assumes a SAML protocol. SAML (Security Assertion Markup Language) is an open standard that allows credential provider applications to securely pass authentication and authorization data to Hyku.

Table of Contents

Resources

• Omniauth SAML

📚 SSO Terminology

• IdP - Identity Provider, owner of the user account (credential provider application, E.g. Okta, Azure AD, Google)

  • IdP Metadata URL, idp_metadata_url - URL for the XML of the IdP certificate

  • IdP Certificate, idp_cert - certificate that contains the secret key from the XML

    • This is ONLY needed if there if NOT an IdP Metadata URL

    • If the IdP Metadata URL is available, the IdP Certificate will be dynamically pulled from that URL

  • IdP SSO Service URL, idp_sso_service_url - URL to the IdP (the redirect from Hyku to the IdP log in page)

• SP - Service Provider, application allowing the SSO (Hyku)

  • SP Metadata URL(s) - URL to Hyku's XML, can be found in Hyku Dashboard > Settings > Identity Provider > click Metadata is available here and copy the URL

    • OR use the base URL of the application and append /users/auth/saml/1/metadata

  • ACS URL - Assertion Consumer Service URL, sometimes called Redirect URL or the Callback URL, where the IdP sends the authentication response (the redirect back to Hyku)

    • This is created dynamically by Hyku when setting up SSO; copy the value from the UI

    • Will follow the convention of base URL appended with /users/auth/saml/1/callback

  • SP Entity ID, sp_entity_id - entity ID, name of the Hyku application

    • Technically the value of the Entity ID is arbitrary as long as both the IdP and the SP have EXACTLY the same ID

    • By convention we have been using the Hyku URL appended with /users/auth/saml/sp

  • SP Certificate, certificate - public certificate used to verify SAML authentication requests sent to the IdP

    • This is generated by you if you are hosting an instance of Hyku

  • SP Private Key, private_key - secret key paired with the SP Certificate to verify requests

    • This should be kept confidential

    • Can be generated with the SP Certificate using OpenSSL or a similar tool

⚙️ Hyku Dashboard Configurations

1. Enable Identity Provider

   • Settings > Features > toggle Show identity provider in admin dashboard

   • This will add Identity Provider under Settings

2. Create a new Authentication Identity Provider

3. Name or Description can be the name of the institution or tenant

4. Provider - select SSO protocol from the dropdown

5. Save - this will generate the ACS URL just above the Metadata link

🌐 Getting the IdP Attributes

Setting up SSO requires exchanging configuration details between Hyku (the SP) and your IdP. Each IdP platform (Okta, Azure AD, Google, etc.) has a slightly different setup process, but the same core information is needed.

What you provide to your IdP administrator:

• SP Entity ID - by convention, your Hyku URL appended with /users/auth/saml/sp

• ACS URL - should be your Hyku URL appended with /users/auth/saml/callback

What you need from your IdP administrator:

• IdP Metadata URL - URL to the IdP's XML configuration (preferred)

  • If a metadata URL isn't available, request the raw XML file instead. You'll extract the IdP Certificate from it manually.

• IdP SSO Service URL - the login page URL where Hyku redirects users

🔐 SP Certificate and Private Key

Your hosting provider will have the SP Certificate and the SP Private Key. Likely these were generated using OpenSSL, or a similar cryptographic tool. Self-signed certificates work for SAML. You don't need to purchase one from a Certificate Authority.

Configure these in your Hyku environment according to your deployment method.

➡️ Request Attributes

Request Attributes are used to build the metadata file to inform the IdP to send certain attributes along with the SAML response messages. (Hey IdP, please send this info.)

OID Format

OID (Object Identifier) is a standard numeric code that uniquely identifies a data field. Typically we see the mail, givenName, and sn fields used in SAML IdPs. The name_format for these fields is generally urn:oasis:names:tc:SAML:2.0:attrname-format:uri.

OID JSON example

URI Format

It’s common with Microsoft-based IdPs (like Azure AD or ADFS) to use the claims-based URI rather than the OID for the request attributes.

URI JSON example

⬅️ Attribute Statements

Attribute Statements (sometimes called Assertion Attributes) are the counterpart to Request Attributes. Whatever information is included in the Request Attributes needs to have a place to map that info back into the hash. (Hey, IdP, put the info we requested right here.)

The keys in the Attribute Statements must match the keys in the Request Attributes. The values are an array with a string with the OID name attribute or the URI name_format attribute.

OID JSON example:

URI JSON example:

💻 Creating the JSON

Using the above information, you will need to configure the JSON that goes into the Options text field on the Authentication Identity Provider page of the Hyku Dashboard. If the JSON is configured correctly, clicking the Metadata is available here link on the Hyku Dashboard should show the Hyku SSO XML. If the link is unavailable, the XML can be found at base URL + /users/auth/saml/metadata.

SSO Client (IdP)

• idp_metadata_url - URL to the IdP XML, remove attribute if not provided and use idp_cert instead

  • idp_cert - IdP Certificate from XML, ONY use if there is no idp_metadata_url

• idp_sso_service_url - URL to the IdP, redirect from Hyku to log in page

Hyku Info (SP)

• certificate - our certificate that can be found in any Hyku application using SSO, use exactly as is (see troubleshooting section)

• private_key - our internal key that can be found in any Hyku application using SSO, use exactly as is

• sp_entity_id - Entity ID, by convention we have been using the Hyku URL appended with /users/auth/saml/sp

Possible Configs

• uid_attribute - change if this is present in their XML, if not leave as is

• info_fields - check client XML for configuration, this is not necessary in all SSO configurations

• request_attributes - may need to be configured if an error occurs: SAML response missing 'urn:oid:1.3.6.1.4.1.5923.1.1.1.6' attribute (see troubleshooting section)

• attribute_statements - may need to be configured if an error occurs: SAML response missing 'urn:oid:1.3.6.1.4.1.5923.1.1.1.6' attribute (see troubleshooting section)

JSON Template

It is easiest to copy the JSON into a text editor where it can be formatted. The following format uses the OID format for Request Attributes and Attribute Statements. Adjust accordingly.

🐛 Troubleshooting and Gotchas

• If the IdP Metadata URL is not available use the IdP Certificate directly from the XML. However, if any of the metadata changes, that certificate value will change and will need to be manually update in the JSON.

  • If there is no IdP Metadata URL available, remove that attribute from the JSON.

• The Entity ID must match EXACTLY. The ID is arbitrary, but by convention we have been using the Hyku application URL appended with /users/auth/saml/sp. Check for differences in the IdP and SP like uppercase vs lowercase letters, https vs http vs no prefix at all.

• It is helpful to have two different browsers (E.g. Firefox and Chrome) one with the Hyku dashboard and one doing the login action.

• The Firefox SAML Tracer or Chrome SML Tracer browser plug ins can help track the requests during SSO.

• SP Metadata URL may need to be added to CloudFlare: Security > Security rules > URI Path > Wildcard > /users/auth/saml/*/metadata