> ## Documentation Index > Fetch the complete documentation index at: https://thehyperstack.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Microsoft Entra ID > Connect Microsoft Entra ID (Azure AD) to Hyperstack with SAML or OIDC, so your team signs in with their Microsoft work account. This guide connects Microsoft Entra ID (formerly Azure Active Directory) to your Hyperstack organization. You need an administrator in Hyperstack and a person who can add enterprise applications in Entra, such as a Cloud Application Administrator. > [!NOTE] > > Single sign-on is on the Enterprise plan. Read the [overview](https://thehyperstack.com/docs/tutorials/single-sign-on.md) first to see who can sign in. ## SAML or OIDC? We recommend **SAML**. With SAML, the Microsoft My Apps tile opens Hyperstack, and a new Entra certificate reaches us by itself from the metadata URL. OIDC uses a client secret. Entra secrets end after a time you choose, and SSO sign-in stops when the secret ends. ## Start in Hyperstack Go to **Settings → Single sign-on** and click **Microsoft Entra**. Then choose **SAML (recommended)** or **OIDC**. ## SAML set-up **1. Create the app in Entra** In the Microsoft Entra admin center, open **Enterprise applications → New application → Create your own application**. Name it **Hyperstack**, pick **Integrate any other application you don't find in the gallery (Non-gallery)** and click **Create**. **2. Open the SAML settings** In the app, open **Single sign-on** and pick **SAML**. Then click **Edit** in **Basic SAML Configuration**. **3. Copy our values into Entra** Step 2 of the Hyperstack page, **Add Hyperstack to Microsoft Entra**, shows each value with a copy button and Entra's own field name: | Entra field | Value from Hyperstack | | - | - | | **Identifier (Entity ID)** | Copy **Identifier (Entity ID)**. Click **Add identifier** if the list is empty. | | **Reply URL (Assertion Consumer Service URL)** | Copy **Reply URL (Assertion Consumer Service URL)**. | | **Sign on URL (Optional)** | Copy **Sign on URL (Optional)**. | | **Relay State (Optional)** | Leave it empty. | | **Logout Url (Optional)** | Leave it empty. | Click **Save**. ![Step 2 in Hyperstack with the Identifier, Reply URL and Sign on URL for Entra](https://mintcdn.com/hyperstack/TA62Nx2wusH3dKmj/images/sso-entra-values.webp?fit=max\&auto=format\&n=TA62Nx2wusH3dKmj\&q=85\&s=011e74e589e22bff33c84fc664262361) > [!TIP] > > You can also click **Download our metadata (XML)** in Hyperstack, then **Upload metadata file** at the top of the Entra SAML page. Entra then fills these fields for you. **4. Leave the claims as they are** Entra already sends the email, given name and surname claims in **Attributes & Claims**. Leave them as they are. The **emailaddress** claim comes from the person's **Email** field in Entra (`user.mail`). If your people have no **Email** field, but their user principal name is their work email, change the **emailaddress** claim to `user.userprincipalname`. **5. Assign people to the app** Open **Users and groups** in the app and click **Add user/group**. Add yourself and your team, or a group of them. Assigned people still need to be on your Hyperstack team, or have an invitation. See [Who can sign in with SSO](https://thehyperstack.com/docs/tutorials/single-sign-on.md#who-can-sign-in-with-sso). **6. Copy the App Federation Metadata Url into Hyperstack** On the Entra **Single sign-on** page, find **SAML Certificates** and copy the **App Federation Metadata Url**. In Hyperstack, step 3 **Connect Microsoft Entra**, paste it in **Metadata URL** and click **Save connection**. You see **Connected to Microsoft Entra** with the issuer and the date the certificate ends. Can't use the metadata URL? Click **Enter the details by hand instead**. Fill in **Sign-in URL (IdP SSO URL)** with Entra's **Login URL**, **Issuer (IdP entity ID)** with Entra's **Microsoft Entra Identifier**, and upload the **Certificate (Base64)** file in **Signing certificate**. You must then paste each new certificate yourself. ### The Entra certificate An Entra SAML certificate lasts 3 years. Entra emails the address in **Notification Email** before it ends. Hyperstack also shows a notice on **Settings → Single sign-on** from 30 days before the end. To change the certificate, make a new one in Entra and make it **Active**. * With the metadata URL, Hyperstack reads it once a day and adds the new certificate next to the old one. A new certificate works within 24 hours after Entra publishes it. After Entra makes the new certificate **Active**, click **Refresh certificates** on **Settings → Single sign-on** to add it at once. SSO stays on. Hyperstack keeps up to 3 certificates, so old and new both work until the old one ends. * Without it, click **Update certificate** on the notice, or **Edit connection**, and add the new certificate. This turns SSO off until a new test passes. See [Change the connection](https://thehyperstack.com/docs/tutorials/single-sign-on/domains-and-enforcement.md#change-the-connection). Next: [verify your domain, test and turn on](#finish-in-hyperstack). ## OIDC set-up **1. Register the app in Entra** In the Microsoft Entra admin center, open **App registrations → New registration**. Name it **Hyperstack**. Under **Supported account types**, keep **Accounts in this organizational directory only**. Under **Redirect URI**, pick **Web** and paste the **Redirect URI (Web)** from step 2 in Hyperstack. Click **Register**. ![Step 2 in Hyperstack on the OIDC tab with the Redirect URI (Web)](https://mintcdn.com/hyperstack/TA62Nx2wusH3dKmj/images/sso-entra-oidc-values.webp?fit=max\&auto=format\&n=TA62Nx2wusH3dKmj\&q=85\&s=7eb2091083bc6a4d71488877c3928590) **2. Add a client secret** Open **Certificates & secrets → Client secrets → New client secret**. Enter a description, choose when it **Expires**, and click **Add**. Copy the **Value** column now, not the **Secret ID**. Entra shows the value only once. > [!WARNING] > > Note the date in **Expires**. SSO sign-in stops when the secret ends, and Hyperstack doesn't remind you of this date. Before it ends, add a new secret in Entra, then click **Edit connection** and **Replace secret** in Hyperstack. A new secret turns SSO off until a new test passes, so plan the change. See [Change the connection](https://thehyperstack.com/docs/tutorials/single-sign-on/domains-and-enforcement.md#change-the-connection). **3. Add the email claim** Open **Token configuration → Add optional claim**. Pick **ID**, tick **email** and click **Add**. If Entra asks, tick **Turn on the Microsoft Graph email permission**. **4. Copy the client values into Hyperstack** On the app's **Overview**, copy the **Application (client) ID** and the **Directory (tenant) ID**. In Hyperstack, step 3 **Connect Microsoft Entra**, fill in: * **Issuer URL**: `https://login.microsoftonline.com//v2.0`. Put your **Directory (tenant) ID** in place of ``. Hyperstack doesn't accept `common` or `organizations` here. * **Client ID**: the **Application (client) ID**. * **Client secret**: the **Value** you copied. Click **Save connection**. Hyperstack never shows the secret again. **5. Assign people to the app** Open **Enterprise applications** and find **Hyperstack**. In **Properties**, set **Assignment required?** to **Yes** and save. Then open **Users and groups** and add yourself and your team. ## Finish in Hyperstack **1. Verify your email domain** Add your domain, such as `acme.com`, and add the TXT record that Hyperstack shows to your DNS. See [Verify a domain](https://thehyperstack.com/docs/tutorials/single-sign-on/domains-and-enforcement.md#verify-a-domain). **2. Click Test sign-in** A new tab opens Microsoft's sign-in page. Sign in there. The test doesn't change your account or sign you in. When the test passes, you see **Test passed** with the email, the name and the Microsoft Entra ID that Entra sent. If it fails, the page says what to change. See [Test sign-in results](https://thehyperstack.com/docs/tutorials/single-sign-on/domains-and-enforcement.md#test-sign-in-results). **3. Click Turn on SSO** You see **SSO is on. Your team can sign in with Microsoft Entra.** Passwords keep working until you [enforce SSO](https://thehyperstack.com/docs/tutorials/single-sign-on/domains-and-enforcement.md#enforce-sso). ## Questions > [accordion] Can guests (Entra B2B users) sign in? > > Only when their email is on one of your verified domains. A guest with an email on another company's domain can't sign in with your SSO. > [accordion] The test says no email came back > > For SAML, check that the **emailaddress** claim is in **Attributes & Claims**, and that the person has an **Email** in Entra. For OIDC, add the optional claim **email** to the ID token. > [accordion] The test says Microsoft Entra didn't accept the client ID or secret > > Check that you copied the secret's **Value**, not its **Secret ID**, and that the secret hasn't expired. > [accordion] Why does Hyperstack check the email domain? > > Entra lets a tenant administrator type any email for a user. Hyperstack trusts an email only on a domain you have verified, so one tenant can never sign in as a person from another company. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.