Sign-in and roles

Authentication

• Local auth works out of the box — use createsuperuser.
• LDAP/AD — Set LDAP_ENABLED=True and configure the LDAP_* variables.
• SSO (OIDC) — Set OIDC_ENABLED=True and configure OIDC_ISSUER, OIDC_CLIENT_ID, OIDC_CLIENT_SECRET. Works with Okta, Azure AD/Entra, Keycloak, Auth0, Google, or any standards-compliant provider — endpoint URLs are auto-discovered from the issuer, no per-endpoint config needed. Or set it live under Administration → Authentication → Single sign-on, which also shows the redirect URI to register with the provider (https://<host>/oidc/callback/). A first sign-in creates an account named after the person's email (their UPN when the directory holds no mail), with the Reader role, able to use PYXA at once; an existing account is matched by email. To take roles from the provider, name the claim (roles for Entra app roles, groups for group object ids) and the values that grant Administrator, Vulnerability manager and Analyst.
  • Entra ID: issuer https://login.microsoftonline.com/<tenant-id>/v2.0; client ID is the app's Application (client) ID; client secret is the secret's Value, not its Secret ID. Add the redirect URI under Authentication → Web, and to limit who may sign in, set Assignment required on the Enterprise application and assign users or groups. PYXA must reach login.microsoftonline.com and graph.microsoft.com.

Roles from your directory

PYXA has four roles: Administrator, Vulnerability Manager, Analyst and Reader. Reader is the default and never needs mapping, so three values are all you create — on either side.

Entra ID (SSO). No name is imposed: you choose the values and declare them under Administration → Authentication. Create three app roles on the app registration, then assign your security groups to them in the Enterprise application:

Set the claim to roles and paste the three values into their fields.

Prefer app roles over the groups claim. A cloud-only group arrives as an object id rather than a name, so you would be pasting GUIDs; and past roughly 200 groups Entra replaces the claim with a pointer PYXA cannot follow, which would silently drop everyone to Reader.

LDAP/AD. Enable it under Administration > Authentication. Once it runs, the sign-in page reads "Sign in with your directory account": people enter their directory user name (sAMAccountName) and password, with or without DOMAIN\, in any case; local administrator accounts sign in on the same form. If LDAP is enabled but could not start, the sign-in page says "Directory sign-in unavailable" and the Authentication page shows the cause. The image includes django-auth-ldap and python-ldap. Here the group names are fixed: PYXA mirrors your groups and matches their common name, case-insensitively.

Three further names are recognised and are usually not worth creating:

• Reader forces the Reader role at every sign-in, overwriting a role an administrator set by hand. A member of none of these groups keeps that role instead, so create Reader only to lock accounts read-only from the directory.
• Stakeholder also resolves to Reader, and additionally links the account to the Stakeholder record holding the same email address.
• Dashboard Viewer resolves to Reader and does nothing else.

Membership must be direct. Nested groups are not resolved, so someone in SOC-Team, which is itself a member of Analyst, is not an analyst.

In both cases: the highest matching role wins (Administrator, then Vulnerability Manager, then Analyst); an Administrator also becomes a Django superuser, which a later sign-in never revokes; and a person matching nothing keeps the role an administrator gave them rather than being reset.

Two limits worth stating: the LDAP_GROUP_* variables do not rename the three role groups above (they reach only Stakeholder and Dashboard Viewer), and the Stakeholder link has no OIDC equivalent, so accounts that sign in through Entra must be linked to their Stakeholder record by hand.

Generated from README.md in the PYXA repository.