Integrate with Microsoft Entra ID

This guide connects an AISIX Cloud organization to Microsoft Entra ID through SAML single sign-on (SSO). When you finish, the people you assign to an Entra ID enterprise application sign in to the AISIX Cloud dashboard with their Entra ID account, and the Entra ID app role you give them sets their role in the organization.

The steps follow the order an administrator works in, switching between the Microsoft Entra admin center and the AISIX Cloud dashboard. How SSO behaves once it is configured, including membership, role mapping, enforcement, and sessions, is described in Single Sign-On (SAML).

Prerequisites

Before you start, make sure you have:

• The owner role in the AISIX Cloud organization. Only owners can change the SSO connection.
• A Microsoft Entra ID role that can create and configure enterprise applications, such as Cloud Application Administrator or Application Administrator.
• An AISIX Cloud control plane that browsers reach over HTTPS at its public base URL. On an On-Premises control plane, this is AISIX_CLOUD_PUBLIC_BASE_URL, or api.publicBaseURL in the Helm chart. See Runtime URLs.

Entra ID accepts an http:// reply URL only for localhost, and the My Apps tile does not open an http:// sign-on URL at all, so a plain HTTP control plane is suitable only for local testing.

Create the Enterprise Application

Create a non-gallery enterprise application for AISIX Cloud:

1. Sign in to the Microsoft Entra admin center and browse to Entra ID > Enterprise apps > All applications.
2. Select New application, then Create your own application.
3. Enter a name, such as AISIX, select the option to integrate an application that is not in the gallery (Non-gallery), and select Create.
4. In the new application, under Manage, select Single sign-on, then SAML.

The Set up Single Sign-On with SAML page opens. Keep it open for the next steps.

Copy the Service Provider Values

In the AISIX Cloud dashboard, open Settings and find the Single sign-on (SAML) card. Its Service provider section shows three values, each with a Copy button:

• Entity ID (Identifier): <public-base-url>/api/auth/sso/saml/<org-id>/metadata
• Assertion Consumer Service URL (Reply URL): <public-base-url>/api/auth/sso/saml/<org-id>/acs
• Sign-on URL: <public-base-url>/login?sso=<org-slug>

The card shows these values before any connection is saved, so you can register the application in Entra ID first. For how the values are built, see Service Provider Values.

Enter the Basic SAML Configuration

On the Set up Single Sign-On with SAML page in Entra ID, select Edit in the Basic SAML Configuration section and enter the values from the SSO card:

Entra ID field	Value from the SSO card
Identifier (Entity ID)	Entity ID (Identifier)
Reply URL (Assertion Consumer Service URL)	Assertion Consumer Service URL (Reply URL)
Sign on URL	Sign-on URL

Leave the relay state and the logout URL empty, and select Save.

Do not skip the Sign on URL. AISIX Cloud accepts only sign-ins that it started itself. With the sign-on URL set, the application's tile in My Apps opens the AISIX Cloud sign-in page, which starts the sign-in. Without it, the tile makes Entra ID send a response that AISIX Cloud did not ask for, and AISIX Cloud refuses it with SSO_UNSOLICITED_RESPONSE.

Check the Attributes and Claims

AISIX Cloud reads three values from the SAML assertion:

• Name identifier (NameID), which identifies the person. After the first sign-in, AISIX Cloud recognizes the person by it alone, so it must not change when the person's email address or user name does. See Identity Links.
• Email address, from the http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress claim. When that claim is absent, AISIX Cloud uses the NameID instead if it has the form of an email address. The address is what a first sign-in is matched by, where AISIX Cloud trusts the IdP for it. See First Sign-In.
• Display name, from the http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name claim, or the givenname and surname claims joined when it is absent. AISIX Cloud sets the account's name from the display name when it creates the account, and on the SaaS service when the sign-in takes over an account that was registered for the address but never verified. An account that already verified its address keeps its name, and later sign-ins do not change it.

In the Attributes & Claims section, check that the application has the default claims:

Claim	Source attribute
Unique User Identifier (Name ID)	user.userprincipalname
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress	user.mail
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name	user.userprincipalname
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname	user.givenname
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname	user.surname

If the list of claims is empty, add these claims before you continue. An application that was created with Microsoft Graph, PowerShell, or an infrastructure-as-code tool, rather than in the admin center, often has no claims configuration. Entra ID then sends an opaque pairwise identifier as the NameID and no emailaddress claim, so AISIX Cloud receives no email address.

Then change the NameID to the user's object ID, which never changes:

1. Select the Unique User Identifier (Name ID) claim.
2. Set Name identifier format to Persistent, and Source attribute to user.objectid.
3. Select Save.

The default NameID, the user principal name (UPN), also works, but it changes when a user is renamed. A renamed user is then refused with SSO_ACCOUNT_ALREADY_LINKED until they are removed from the organization and added back. Make this change before people start signing in: changing the NameID later has the same effect on everyone who has already signed in. See Changing the NameID Later.

With the object ID as the NameID, the email address comes only from the emailaddress claim, user.mail, which Entra ID omits for a user who has no mail value. Such a user can still sign in, but AISIX Cloud gets no email address for them, so their first sign-in always goes to the Connect page, where only an existing account can be connected. To use the UPN as the address instead, set Email attribute on the SSO card to http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name, which carries the UPN.

To show people's names in AISIX Cloud instead of their UPN, change the source attribute of the name claim to user.displayname.

Do not turn on token encryption for the application. AISIX Cloud does not accept encrypted assertions. Entra ID signs the assertion with RSA-SHA256 and leaves the response unsigned, which AISIX Cloud accepts.

If you also provision users from Entra ID through SCIM, a user it provisions at an address outside the organization's verified domains joins when they connect SSO with a NameID equal to the externalId that SCIM sent. Map the same Entra ID attribute to both, such as objectId to externalId in the provisioning attribute mappings when the NameID is user.objectid. See Members Waiting to Join.

Define App Roles

App roles let Entra ID tell AISIX Cloud which role each person should have. Define one app role for each AISIX Cloud role that differs from the connection's default role. For example, an app role for admins:

1. In the Microsoft Entra admin center, browse to Entra ID > App registrations, select All applications, and select the application you created. It has the same name as the enterprise application.
2. Under Manage, select App roles, then Create app role.
3. Enter a Display name, such as AISIX Admin, set Allowed member types to Users/Groups, enter a Value, such as AISIX.Admin, and enter a Description.
4. Keep Do you want to enable this app role? selected, and select Apply.

The Value is what Entra ID sends in the http://schemas.microsoft.com/ws/2008/06/identity/claims/role claim, and what the AISIX Cloud role mapping rule compares, including case.

People who have no app role, or an app role that no rule matches, get the connection's default role. You do not need an app role for them.

Use Groups Instead of App Roles

App roles are the recommended choice, but rules can also read Entra ID groups. Under Attributes & Claims, select Add a group claim. Entra ID then sends the http://schemas.microsoft.com/ws/2008/06/identity/claims/groups claim, whose values are group object IDs by default, so a rule's value is the object ID of the group, not its name.

Entra ID sends at most 150 groups in a SAML assertion and omits the claim entirely for a user in more groups. Choose Groups assigned to the application to send only the groups assigned to the application, which keeps the claim small.

Assign Users and Groups

Entra ID signs in only the users assigned to the application when its Assignment required? property is Yes, which you can check under Manage > Properties. To assign people:

1. In the enterprise application, under Manage, select Users and groups, then Add user/group.
2. Under Users and groups, select the users or groups who should be able to sign in, and choose Select.
3. Under Select a role, choose the app role for them, such as AISIX Admin, and choose Select. Skip this step for people who should get the default role.
4. Select Assign.

Assigning a group requires Microsoft Entra ID P1 or P2, and the assignment covers only the group's direct members.

A change of app role takes effect at the person's next sign-in to AISIX Cloud.

Download the Federation Metadata

In the SAML Certificates section of the Set up Single Sign-On with SAML page, select Download next to Federation Metadata XML.

The file describes Entra ID as the identity provider: its entity ID, its sign-in URL, and its signing certificate.

Configure the Connection in AISIX Cloud

In the AISIX Cloud dashboard, open Settings > Single sign-on (SAML) and complete the connection:

1. Paste the metadata into Identity provider metadata XML and select Read metadata, or select Upload metadata file and choose the downloaded file.

2. Check the fields that the metadata filled in:

   • Identity provider entity ID: https://sts.windows.net/<tenant-id>/
   • Single sign-on URL: https://login.microsoftonline.com/<tenant-id>/saml2
   • Signing certificates: one certificate. The metadata repeats the certificate in several places, and AISIX Cloud keeps one copy.

3. Turn on Enable single sign-on.

4. Turn on Add new members on sign-in (just-in-time) if people who are not members yet should join on their first sign-in. Otherwise, invite them first, or provision them through SCIM.

5. Keep Default role at Member, or choose the role that people without a matching app role should get.

6. Under Role mapping, select Add rule and enter the rule for the admin app role:

   Attribute	Operator	Value	Role
   http://schemas.microsoft.com/ws/2008/06/identity/claims/role	any value equals	AISIX.Admin	Admin

7. Leave Email attribute and Display name attribute empty to use the defaults.

8. Select Save.

With a role mapping rule in place, AISIX Cloud sets the member's role at every sign-in, so a role changed by hand in the dashboard is replaced at the member's next sign-in. Owners are never changed. See Map IdP Attributes to Roles.

You can also skip the metadata and enter the three fields by hand. On the Set up Single Sign-On with SAML page in Entra ID, they are Microsoft Entra Identifier and Login URL in the section that sets up the application, and the Certificate (Base64) download in SAML Certificates.

Test the Sign-In

Test with a user who is assigned to the application, in a private browser window:

1. Open the sign-on URL, <public-base-url>/login?sso=<org-slug>.
2. Select Sign in with SSO.
3. Sign in to Microsoft with the user's account.

The browser returns to AISIX Cloud. On an On-Premises control plane, or on the SaaS service when the user's email address is on one of the organization's verified domains, it opens the organization. Otherwise, on the SaaS service, the first sign-in opens the Connect page, where the user connects an account and confirms. Later sign-ins open the organization directly. On the Members page, check that the member has the role their app role maps to.

Members can also start from the regular sign-in page, <public-base-url>/login. On an On-Premises control plane, it shows a Continue with <organization> SSO button that goes straight to Entra ID. On the SaaS service, the member selects Continue with SSO and enters the organization's identifier, the <org-slug> in the sign-on URL. See SSO Sign-In.

Multi-factor authentication, including Microsoft security defaults and Conditional Access, happens in Entra ID before AISIX Cloud receives the response. There is nothing to configure for it in AISIX Cloud. A test user without a registered authentication method may first be asked by Microsoft to register one.

Sign In from My Apps

Assigned users also see the application as a tile in My Apps. Selecting the tile opens the AISIX Cloud sign-on URL, where the user selects Sign in with SSO once more. Entra ID already has the user's session, so the sign-in then completes without another prompt.

The tile works only with an HTTPS Sign on URL. With an http:// sign-on URL, even on localhost, My Apps reports App launch failed. With no sign-on URL, AISIX Cloud refuses the sign-in with SSO_UNSOLICITED_RESPONSE.

Require Single Sign-On

After a test sign-in succeeds, you can make SSO the only way for members other than owners to reach the organization. On the SSO card, turn on Require single sign-on and select Save. Owners can still sign in with their password, which keeps a way in if Entra ID is unavailable or misconfigured. See Require Single Sign-On.

Rotate the Signing Certificate

Entra ID creates the application's signing certificate with a validity of three years and emails the notification addresses on the SAML Signing Certificate page before it expires. An SSO connection holds up to 10 certificates and accepts a response signed by any of them, so you can rotate without an outage:

1. In Entra ID, in the SAML Certificates section, select Edit. On the SAML Signing Certificate page, select New Certificate, then Save. The new certificate is Inactive.
2. Select the ellipsis (...) next to the new certificate and download it in Base64 format.
3. On the AISIX Cloud SSO card, select Add certificate, paste the certificate, and select Save. Alternatively, download the Federation Metadata XML again, which now lists both certificates, and read it with Read metadata.
4. In Entra ID, select the ellipsis (...) next to the new certificate and select Make certificate active.
5. Sign in through SSO to confirm that sign-in works with the new certificate.
6. Remove the old certificate from the SSO card and select Save.
7. Turn Require single sign-on back on and select Save.

Any change to the certificates on the SSO card, adding or removing, turns Require single sign-on off, because the new settings have not been proven by a sign-in yet. That is why it is turned back on last.

If Entra ID signs with a certificate that the SSO card does not hold, for example because the new certificate was made active before it was added to AISIX Cloud, every sign-in fails with SSO_RESPONSE_INVALID.

Troubleshooting

Errors from Entra ID appear on a Microsoft page, after the user has entered their credentials. Errors from AISIX Cloud send the browser back to the AISIX Cloud sign-in page with an explanation. The full list of AISIX Cloud error codes is in Troubleshooting.

Symptom	Cause	Fix
AADSTS50011: The reply URL ... does not match the reply URLs configured for the application	The Reply URL in Entra ID differs from the SSO card's reply URL, often because the control plane's public base URL changed after the application was registered.	Copy Assertion Consumer Service URL (Reply URL) from the SSO card into the Basic SAML Configuration again.
AADSTS50105: Your administrator has configured the application ... to block users unless they are specifically granted ('assigned') access to the application	The user is not assigned to the application, directly or through a group.	Assign the user or one of their groups under Users and groups.
App launch failed in My Apps	The Sign on URL is an http:// URL.	Use the HTTPS sign-on URL of the control plane.
Every first sign-in opens the Connect page without an email address	The application has no claims configuration, so Entra ID sends a pairwise NameID and no emailaddress claim. Or the user has no mail value.	Add the default claims in Attributes & Claims, as in Check the Attributes and Claims. Alternatively, set Email attribute on the SSO card to http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name, which Entra ID fills with the UPN.
SSO_ACCOUNT_ALREADY_LINKED	The user's NameID changed since their first sign-in: the user was renamed while the NameID is the UPN, or the Unique User Identifier (Name ID) claim was changed.	Remove the user from the AISIX Cloud organization and add them back. To avoid it, use user.objectid as the NameID.
SSO_UNSOLICITED_RESPONSE	The sign-in started in Entra ID, for example from My Apps without a Sign on URL.	Set the Sign on URL in the Basic SAML Configuration, and start sign-ins from AISIX Cloud.
SSO_RESPONSE_INVALID	Entra ID signed the response with a certificate that the SSO card does not hold.	Add the active certificate to the SSO card, or read the current federation metadata again.
SSO_ENCRYPTED_ASSERTION_UNSUPPORTED	Token encryption is on for the application.	Turn off token encryption in Entra ID.
SSO_NOT_A_MEMBER	The person is assigned in Entra ID but is not a member of the AISIX Cloud organization, and just-in-time provisioning is off.	Invite the person, provision them through SCIM, or turn on Add new members on sign-in (just-in-time).

Next Steps

Use SCIM Directory Sync to provision and deprovision members from Entra ID ahead of their first sign-in, and Roles and Custom Roles to define roles beyond member and admin that the role mapping rules can assign.