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

Guide to Configuring SSO with Microsoft Entra ID

1. Who this guide is for

This guide walks you through setting up Single Sign-On (SSO) between Microsoft Entra ID (formerly Azure Active Directory) and the Cyber Guru platform, using the SAML 2.0 protocol.

To complete this process, you’ll need a role with administrative privileges in Microsoft Entra ID (typically Cloud Application Administrator or Application Administrator). If you’re not sure you have these permissions, check with your organization’s IT team before starting.

In this guide, “CyberGuru” refers to CyberGuru or the partner managing your platform.

This guide also covers SSO authentication via SAML 2.0 using the SP-Initiated mechanism (i.e., starting from the URL). If you need to set up SSO access via application (IDP-Initiated), please contact support.

💡 The screenshots in this guide show the Microsoft console in English. If your console is in Italian, you’ll find the corresponding labels in parentheses in the text. Microsoft interface labels change frequently: if you don’t see an exact match, use the portal’s search bar.

2. Table of Contents

  • Key terms
  • Prerequisites and decisions to make before you start
  • Step-by-step configuration (steps 1-8)
  • Testing and confirmation
  • If something doesn’t work
  • After go-live: maintenance
  • Additional resources

3. Key terms

  • IdP (Identity Provider): the system that authenticates users. In this scenario, it’s Microsoft Entra ID.
  • SP (Service Provider): the service the user is accessing, i.e., the Cyber Guru platform.
  • Metadata: XML files (or URLs) that IdP and SP use to exchange endpoints and certificates to establish mutual trust (circle of trust).
  • Claim: information about the user that the IdP includes in the SAML response—such as first name, last name, or email.
  • Enterprise Application: the object in Entra ID that represents the application to be integrated.

4. Prerequisites and decisions to make before you start

These points should be clarified before opening the console: most configuration issues stem from making the wrong choice here.

Item Who provides it Notes
Administrative access to Microsoft Entra ID Customer Application Administrator role or higher.
Protocol — SAML 2.0. Other protocols are not supported.
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 identify the user and cannot be changed after the project starts. In Entra ID, the recommended choice is Object ID (user.objectid). Alternatives (e.g., employee number) are allowed as long as they are immutable. Avoid email and UPN if they can change: see §8.
Required attributes populated on the user profile Customer There are four: username, email, firstName, lastName. Make sure first name, last name, and email are actually filled in on Entra profiles.
Organizations to send Customer + Cyber Guru Optional, in the form org_{ORG_NAME} (location, department, organizational unit, etc.). Needed if your company operates without preloading or if one of them should be used as a Team for statistics and gamification. Details in Identity Provider SSO Attributes.
Application access policy Customer Use a dedicated group instead of assigning individual users: this is the easiest way to manage access over time. Only users assigned to the app will be able to log in.
User population method Customer + Cyber Guru With preloading (recommended) or without. The two methods have different impacts on licenses and attributes: read General SSO Procedure before choosing.
Test user Customer Provide a test account in Entra ID, useful for checks during the testing phase.
Platform subdomain Cyber Guru In the form https://<subdomain>.platform.cyberguru.eu.

5. Step-by-step configuration

Step 1 — Log in to Microsoft Entra ID

Go to https://entra.microsoft.com with an account that has the administrative privileges listed in the prerequisites.

Step 2 — Open "Enterprise applications"

In the left navigation panel, select Enterprise applications (Applicazioni aziendali).

Navigation menu with Enterprise applications selected

Step 3 — Create a new non-gallery application

At the top of the page, click New application (Nuova applicazione).

New application button

Then click Create your own application (Crea la tua applicazione).

Create your own application button

In the panel that opens: enter a name for the application (e.g., Cyber Guru), make sure the option "Integrate any other application you don't find in the gallery (Non-gallery)" is selected, and click Create.

Non-gallery application creation panel

Step 4 — Start SAML configuration

From the overview page of the newly created application, open Single sign-on in the left menu (or the Set up single sign on tile).

Application overview page

From the available methods, select SAML.

Selecting the SAML SSO method

Step 5 — Send IdP metadata to Cyber Guru

In the 3 — SAML Certificates section, you’ll find the App Federation Metadata Url field.

SAML Certificates section with App Federation Metadata Url

Copy that URL and send it to Cyber Guru. It looks like this:

https://login.microsoftonline.com/<tenant-id>/federationmetadata/2007-06/federationmetadata.xml?appid=<app-id>

⚠️ Send the URL, not the downloaded certificate or XML file.
After configuration, the metadata must remain unchanged. If they change in the future—a new certificate, new application, different endpoints—do not modify or recreate them on your own: open a request with CyberGuru support, who will coordinate the update. See §8.

Step 6 — Receive and upload Cyber Guru SP metadata

Cyber Guru will complete the configuration on their side and send you the SP metadata URL, in this format:

https://<host-login-cyberguru>/realms/<subdomain>/broker/saml/endpoint/descriptor

⚠️ Use exactly the URL you receive from Cyber Guru: do not try to build it yourself or copy it from other guides or other organizations’ configurations. The address depends on the environment where your company is hosted.

Open the URL in a browser and save the page as an XML file. Then, on the application’s SAML page, click Upload metadata file (Aggiorna file metadati) at the top and upload the saved file.

Upload metadata file button

Entra ID will automatically fill in Identifier (Entity ID) and Reply URL (ACS URL). Check the values on the review page and click Save.

Review page for imported metadata

Step 7 — Configure claims (Attributes & Claims)

Open the 2 — Attributes & Claims section and click Edit. When you create the app, you’ll see a set of default claims:

Default application claims

You can edit the existing additional claims or remove them all and create new ones. Cyber Guru requires exactly these four claims:

Claim name (Name) Namespace Recommended source attribute
username (empty) user.objectid or user.userprincipalname
email (empty) user.mail
firstName (empty) user.givenname
lastName (empty) user.surname
Unique User Identifier aligned with username

For each claim, in Manage claim set Source = Attribute and choose the Source attribute:

Manage claim panel with Source attribute

🛑 The two most common mistakes, both in this step:
1. The Namespace field must remain empty. Entra ID auto-fills it with something like http://schemas.xmlsoap.org/ws/2005/05/identity/claims: if you leave it, the claim will be sent to Cyber Guru with the prefix and won’t be recognized. Delete it for all four claims.
2. Claim names are case-sensitive. firstName and lastName must be written exactly like this (camelCase).

If you also need to send organizations (org_{ORG_NAME}) or the optional attributes locale and country, if the user account is created at login via SSO, add them using the same rules. The complete rules for attributes—required, optional, organizations and Teams, update frequency—are in Identity Provider SSO Attributes, which is the reference to follow.

When you’re done, you should see something like this. Double-check the mapping line by line:

Final claim mapping

Step 8 — Authorize users and document the configuration

Go to Users and groups (Utenti e gruppi) and assign the group containing authorized users to the application. Anyone not assigned to the app will get a 403 error when trying to log in or an unauthorized error from their IDP, even if everything else is set up correctly.

For testing, assign only 2-3 test users; you’ll add the full group at go-live.

Keep a digital copy of the configuration (metadata URLs, claim names, assigned group): you’ll need it when renewing the certificate.

6. Testing and confirmation

  1. Make sure the test user is assigned to the application in Entra ID.
  2. If the company is set up with preloading, check that the same user is already present on the platform and that their username on the platform matches exactly the value sent in the username claim. If the user is not preloaded, access will be denied.
  3. Open a browser window in incognito mode (to avoid reusing active Microsoft sessions).
  4. Go to https://<subdomain>.platform.cyberguru.eu
  5. Click the SSO login button.
  6. Sign in with Microsoft. If everything works, you'll go straight to the Cyber Guru welcome page without entering any other credentials.
  7. Check on the platform that the user's first name, last name, and email are correct: if they're empty or incorrect, the issue is with the claim mapping.

7. If something doesn't work

Try these three checks, which solve most cases:

  1. Capture the SAML response with a SAML tracer (browser extension) and check the exact names of the claims received: are the capitalizations correct? Is the namespace missing? Is the username value the same as on the platform?
  2. Check the user's assignment to the application in Entra ID.
  3. Read the error message: it's almost always diagnostic.

The most common error messages, along with their 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, the time of the attempt, the username of the user involved, and if possible, the SamlRequest.xml and SamlResponse.xml files captured by the tracer.

8. After go-live: maintenance

Three events require coordinated action with Cyber Guru. Plan them in advance:

  • SAML signing certificate expiration on the Entra application (Microsoft sends a notification before expiration).
  • Any changes to the application's metadata: these must remain unchanged, and any modification must be handled by support.
  • Changes to users' email, UPN, or domain: these can break the link between the Entra identity and the platform account, resulting in access being blocked.

The procedures are described in SSO Maintenance: certificate renewal and username/email changes. Notify Cyber Guru in advance of domain migrations or mass UPN changes.

9. Additional resources

Related articles