Skip to main content
Sign in
Deutsch Español Français Italiano

Guide to Configuring SSO with a Generic Identity Provider (SAML 2.0)

1. Who this guide is for

The Cyber Guru platform integrates with any Identity Provider that supports SAML 2.0. There are dedicated guides with screenshots for Microsoft Entra ID and Google Workspace:

This guide is for all other cases: Okta, Microsoft ADFS, Shibboleth, Oracle, ForgeRock, IBM, AWS, WSO2, PingFederate, or a custom-built solution.

You won't find screenshots here: every console has its own interface, and menu items change from version to version. Instead, you'll find everything your Identity Provider needs to do and the exact values to exchange, so that whoever manages your system can configure it confidently.

💡 Your organization is responsible for configuring your Identity Provider, either with internal resources or with support from your identity platform provider. Cyber Guru configures its own side and provides all the necessary values.

2. How the integration works

Cyber Guru acts as the Service Provider (SP), and your system acts as the Identity Provider (IdP). For the protocol to work, both must have SAML 2.0 components and establish mutual trust (the so-called circle of trust) by exchanging metadata.

The expected flow is SP-initiated: the user starts from the platform's address, is redirected to your Identity Provider to authenticate, and returns to the platform with a SAML assertion. (Access started from the IdP portal — IdP-initiated — is possible but requires additional configuration: see Advanced SSO scenarios.)

3. Prerequisites and decisions to make before you start

Item Who provides it Notes
Identity Provider with SAML 2.0 support Customer Other protocols are not supported.
Admin privileges on the IdP Customer You need to be able to create a new application/relying party and define the released attributes.
Field to use as username Customer The most important decision in the configuration. It must be an immutable attribute: this is the key the platform uses to recognize the user and it cannot be changed after the project starts. In Active Directory, it's typically the ObjectGUID; in other systems, an equivalent identifier (such as an employee number). Avoid using email and UPN if they might change over time.
Required attributes set on profiles Customer There are four: username, email, firstName, lastName.
Organizations to send Customer + Cyber Guru Optional, in the format org_{ORG_NAME}. Needed if the company operates without preloading or if one of them should be used as a Team for statistics and gamification.
IdP metadata Customer Public URL accessible from the internet, or XML file.
Application access policy Customer Use a dedicated group: only users authorized for the application will be able to access.
User population method Customer + Cyber Guru With preloading (recommended) or without: see General SSO Procedure.
Test accounts Customer 2-3 accounts for testing, authorized for the application.
Platform subdomain and SP metadata Cyber Guru Provided after the exchange.

4. Step-by-step configuration

Step 1 — Create the SAML application on your Identity Provider

Create a new application (depending on the system, it may be called application, relying party trust, service provider, client) of type SAML 2.0. Do not use catalog templates for other products: you need a generic integration.

Step 2 — Send IdP metadata to Cyber Guru

Send Cyber Guru the public metadata URL of your Identity Provider (preferred) or the XML metadata file.

The metadata must include: the IdP's entityID, the Single Sign-On Service endpoint, and the public signing certificate.

⚠️ If your Identity Provider is only accessible from your internal network, the metadata must still be exposed at a public URL or sent as a file. An endpoint not reachable from the internet cannot be used for user authentication from outside.

Step 3 — Receive Cyber Guru SP metadata and configure the application

Cyber Guru completes the configuration on its side and sends you the SP metadata URL. If your system supports automatic metadata import, use it: it's the least error-prone method. Otherwise, open the URL in a browser and get the values from the XML file:

Value to configure Where to find it in the SP metadata XML file
Entity ID (audience / SP identifier) entityID attribute of the root <md:EntityDescriptor> element
ACS URL (Assertion Consumer Service, reply URL, destination) Location attribute of the <md:AssertionConsumerService> element with HTTP-POST binding
⚠️ Copy the values from your metadata file, character by character. Do not reconstruct them manually and do not copy them from other guides or from other organizations' configurations: the address depends on the environment where your company is hosted.

Step 4 — Assertion technical requirements

Parameter Required value
Protocol version SAML 2.0
Response binding HTTP-POST to the ACS URL
Signature The assertion (or the response) must be signed with the IdP's private key; the corresponding public certificate must be included in the provided metadata
Assertion encryption Not required. If your IdP requires it, let us know before configuration
Name ID format Set according to the instructions you receive from Cyber Guru along with the SP metadata
Single Logout Optional. If your IdP performs logout with HTTP-POST binding, let us know: this requires additional configuration on the Cyber Guru side

Step 5 — Configure released attributes

The assertion must contain four required attributes, with these exact names:

Attribute name Content
username The immutable identifier chosen in the prerequisites
email User's email address
firstName First name
lastName Last name

Optional: locale (two-letter lowercase ISO language code), country (two-letter uppercase ISO country code), and organizations in the format org_{ORG_NAME}.

🛑 Two rules that apply to any Identity Provider:
1. Attribute names are case-sensitive. firstName and lastName must be written exactly like this, in camelCase.
2. Names must not have namespace prefixes. Many Identity Providers — especially ADFS and Microsoft Entra ID — release attributes with a prefix like http://schemas.xmlsoap.org/ws/2005/05/identity/claims: that prefix must be removed, otherwise the attribute won't be recognized.

The complete reference for attributes — required, optional, organizations and Teams, update frequency — is in Identity Provider SSO Attributes. Any attributes not listed there must be agreed upon in advance with Cyber Guru.

Here's an example of how the attribute section of the assertion should look:

<saml2:AttributeStatement>
  <saml2:Attribute Name="username">
    <saml2:AttributeValue>a1b2c3d4-0000-1111-2222-33445566778</saml2:AttributeValue>
  </saml2:Attribute>
  <saml2:Attribute Name="email">
    <saml2:AttributeValue>mario.rossi@esempio.it</saml2:AttributeValue>
  </saml2:Attribute>
  <saml2:Attribute Name="firstName">
    <saml2:AttributeValue>Mario</saml2:AttributeValue>
  </saml2:Attribute>
  <saml2:Attribute Name="lastName">
    <saml2:AttributeValue>Rossi</saml2:AttributeValue>
  </saml2:Attribute>
</saml2:AttributeStatement>

Step 6 — Authorize users

Assign the group containing authorized users to the application. Anyone not authorized for the application will get an error when trying to log in, even if everything else is configured correctly. For testing, only authorize the test accounts.

Step 7 — Document the configuration

Keep a record of the values you entered (Entity ID, ACS URL, attribute names, authorized group) and the metadata file: you'll need them when renewing the certificate.

5. Testing and confirmation

  1. Make sure the test account is authorized for the application on the Identity Provider.
  2. If the company is configured with preloading, make sure the same account is already present on the platform with a username identical to the value sent in the username attribute. If it's not preloaded, access will be denied.
  3. Open a browser window in incognito mode.
  4. Go to https://<subdomain>.platform.cyberguru.eu and click the SSO login button.
  5. Authenticate on your Identity Provider: if everything works, you'll land on the Cyber Guru welcome page without entering any other credentials.
  6. Check on the platform that the first name, last name, and email are correct: if they're empty or incorrect, the issue is with the released attributes.

6. If something doesn't work

Your first tool is a SAML tracer in your browser: capture the SAML response and check the exact attribute names (including case), the absence of namespace prefixes, the username value, and the presence of all four required attributes.

Then check that the configured Entity ID and ACS URL match the SP metadata exactly, character by character, and that the user is authorized for the application.

The most common error messages, with causes and solutions, are collected in SSO Frequently Asked Questions (FAQ).

If the problem persists, contact Cyber Guru support and provide: the full error message, time of the attempt, username of the affected user, company subdomain, and if possible, the SamlRequest.xml and SamlResponse.xml files.

7. After go-live: maintenance

After configuration, the metadata should be considered fixed. If they change — signing certificate renewal, new endpoints, new application, replacement of the Identity Provider — do not modify them on your own: open a request with Cyber Guru support, who will coordinate the update on both sides. The same applies to changes in user email, UPN, or domain, which can break the association with platform accounts.

Procedures are in SSO Maintenance: certificate renewal and username/email changes.

8. Related articles

Related articles