Requires Powercode build 26.10.05 or later.
Single sign-on (SSO) lets your staff sign in to the admin portal with their Microsoft work account instead of a separate Powercode password. Powercode talks to Microsoft Entra ID (formerly Azure AD) using SAML: you create an enterprise application in Entra, copy a few values between the two, and a button for Microsoft appears on the Powercode sign-in page, under the usual username and password form.
Earlier builds could not complete sign-in with Entra, because Powercode always asked Microsoft to use one particular sign-in method, and Entra rejects that request. From 26.10.05 this is the Request Authn Context setting, and it is off by default.
Request Authn Context must be Disabled for Microsoft Entra ID. It is under Security Configuration on the provider card. If it is Enabled, Microsoft shows an error instead of sending your staff back to Powercode.
Third Party > SSO & SAML
| Permission | Why it is needed |
|---|---|
| SSO & SAML authentication (System → Third Party Integration) at Edit | To see the SSO & SAML menu link. |
You also need an Entra account that can create enterprise applications.
There is no Save button on this page. Each setting is saved as soon as you change it and move to the next field, and Powercode shows Configuration Saved.
https://yourdomain.com, and have staff sign in at that same address.Open Third Party > SSO & SAML. The Service Provider Details card at the top shows three read-only values, each with a copy button:
| Powercode field | Looks like | Where it goes in Entra |
|---|---|---|
| ACS URL | https://yourdomain.com/uapi/sp?acs |
Reply URL (Assertion Consumer Service URL) |
| Entity ID | https://yourdomain.com/uapi/sp?metadata |
Identifier (Entity ID) |
| SLS URL | https://yourdomain.com/uapi/sp?sls |
Not needed. See Limitations. |
In the Microsoft Entra admin center, go to Enterprise applications > New application > Create your own application.
Give it a name such as Powercode, choose the option to integrate an application you don't find in the gallery (Non-gallery), and create it.
In the new application, open Single sign-on and choose SAML.
In Basic SAML Configuration, click Edit and enter:
Save.
In Attributes & Claims, click Edit and use Add new claim to add the three claims below. Type each Name exactly as shown, in lowercase, and leave Namespace blank.
| Name | Source attribute |
|---|---|
email |
user.mail (or user.userprincipalname if your users' mail attribute is empty) |
firstname |
user.givenname |
lastname |
user.surname |
Still in Attributes & Claims, if you want Entra groups to decide Powercode permissions, use Add a group claim. Choose which groups to send, then under Advanced options tick Customize the name of the group claim and set the name to group, with no namespace. Entra sends each group's Object ID.
In SAML Certificates, download Certificate (Base64).
In the Set up section for your application, copy the Login URL and the Microsoft Entra Identifier.
In Users and groups, add the staff, or the groups, who should be able to sign in.
Anyone who can sign in to this Entra application gets a Powercode account. If Powercode has no user for them yet, it creates one at their first sign-in. Limit the application to the people who should have access, for example by setting Assignment required? to Yes in the application's Properties and assigning only staff.
Back on Third Party > SSO & SAML, fill in the provider card. If you need a second provider, click Add identity provider to add another card.
| Field | What to enter |
|---|---|
| Disabled / Enabled | Leave Disabled until everything else is filled in. Enabled shows the provider's button on the sign-in page. |
| Provider Name | The text on the sign-in button, for example Microsoft. |
| Provider Icon | Optional. An icon class to show on the button, for example fab fa-microsoft. |
| Field | What to enter |
|---|---|
| Entity ID | The Microsoft Entra Identifier from Step 2. It looks like https://sts.windows.net/<tenant-id>/. This is Entra's ID, not the Entity ID in Service Provider Details. |
| SSO URL | The Login URL from Step 2. It looks like https://login.microsoftonline.com/<tenant-id>/saml2. |
| SLO URL | Leave blank. |
| IdP Certificate | Open the Certificate (Base64) file in a text editor and paste its whole contents. |
| Field | What to enter |
|---|---|
| Default User Group | The Powercode permission group for users whose sign-in includes no group claim. Choose --- NA --- for none. |
| User Identifier (UID) | Leave as email. Powercode finds users by the claim named email. |
| Username: | email |
| First Name: | firstname |
| Last Name: | lastname |
| Group: | group |
Fill in all four mapping fields exactly as shown. Don't leave any blank, and don't use other claim names. Powercode uses these exact names when it updates a returning user.
The Group Mapping section lists every Powercode permission group. In Provider Group, next to each Powercode group you want to use, enter the Object ID of the matching Entra group. You can find it on the group's overview page in Entra. Leave the others blank.
Click Security Configuration to expand it. Leave everything at the defaults shown below unless you know you need a change. Above all, keep Request Authn Context set to Disabled.
| Setting | Default | What it does |
|---|---|---|
| NameID Format | Unspecified | The NameID format Powercode asks for. |
| Request Authn Context | Disabled | Asks the identity provider to use a specific sign-in method (Password Protected Transport). Must be Disabled for Entra. |
| SP Certificate / SP Private Key | Blank | Powercode's own certificate and key, used to sign requests. Only needed if you turn on a signing option. |
| Sign AuthN Requests | Disabled | Signs the sign-in request Powercode sends. |
| Encrypt NameID in Logout Requests | Disabled | Encrypts the NameID in logout requests. |
| Sign Logout Requests | Disabled | Signs logout requests. |
| Sign Logout Responses | Disabled | Signs logout responses. |
| Require Signed Messages | Disabled | Rejects responses that are not signed as a whole. |
| Require Signed Assertions | Disabled | Rejects responses whose assertion is not signed. |
| Require Encrypted Assertions | Disabled | Rejects assertions that are not encrypted. |
| Require NameID | Enabled | Rejects responses with no NameID. |
| Require Encrypted NameID | Disabled | Rejects a NameID that is not encrypted. |
| Signature Algorithm | RSA-SHA256 (recommended) | The algorithm Powercode signs with. |
| Digest Algorithm | SHA256 (recommended) | The digest algorithm Powercode signs with. |
Validate checks that the settings are complete and that Powercode can build its SAML metadata. It does not contact Microsoft, so it cannot tell you whether sign-in will work. Download Metadata XML downloads the same metadata as a file.
Keep your current session open in your normal window while you test, so you can fix settings if something is wrong.
email claim. To connect an existing Powercode user to SSO, their Username must be that email address. Otherwise Powercode creates a new user.firstname and lastname, and has no Powercode password or email address. They appear on Config > Users like any other user. See Users.firstname and lastname every time the user signs in with SSO.group claim, the user gets every Powercode group whose Provider Group matches one of the values. Values with no match are ignored. If nothing matches, the user ends up with no permission groups, and Default User Group is not used.group claim, the user gets the Default User Group, or no groups if that is --- NA ---.| Symptom | Likely cause |
|---|---|
| Microsoft shows an error instead of returning to Powercode | Request Authn Context is Enabled. Set it to Disabled. Also check that Identifier (Entity ID) and Reply URL in Entra exactly match Powercode's Entity ID and ACS URL, and that the user is assigned to the application. |
| After signing in at Microsoft, the user lands back on the Powercode sign-in page with no message | Powercode rejected the sign-in. Common causes: there is no claim named exactly email; IdP Certificate is wrong or out of date, for example after the certificate was renewed in Entra; Entity ID or SSO URL is wrong; or the user signed in at a different Powercode address. The server error log has the reason, for example SAML Auth failed or IDP parameter for the UID (email) not found. Possible parameters are: …. |
| Metadata is invalid under Validate | A required value is missing or invalid, such as Entity ID, SSO URL or IdP Certificate, or a signing option is on without an SP Certificate and SP Private Key. The reason is shown with the message. |
| Download Metadata XML gives an error | The provider's settings are incomplete. Click Validate to see why. |
| Save Failed when you change a field | That change was not saved. The reason is shown in the message. Try again. |
| The provider's button is not on the sign-in page | The provider is set to Disabled. |
| The button has no text | Provider Name is empty. |
| A user signs in but has no menus or permissions | Either their group claim matched no Provider Group, or they had no group claim and Default User Group is --- NA ---. Check the claim is named exactly group and that Provider Group holds the Entra groups' Object IDs. |
| Changes to an SSO user's permission groups keep reverting | Expected. Groups are set from Entra at every SSO sign-in. Change their groups in Entra or in Group Mapping instead. |
| A second Powercode account appeared for an existing user | The existing user's Username does not match the email Entra sends. Change their Username to that email address. |
| A user's name became blank | The firstname and lastname claims are missing or named differently. |
| A user you made inactive can still sign in | SSO does not check Status. Remove them from the application in Entra. |
| Opening Powercode from My Apps shows the Powercode sign-in page | Expected. Click the provider button. |