Identity provider setup guides

Per-vendor walkthroughs for the SSO connection wizard described in SSO. Use these to configure your IdP application before clicking Done on the Configure your IdP panel in Praxis.

Every guide follows the same shape:

1. Create an application in the IdP.
2. Paste the service provider values (ACS URL, Audience / Entity ID, redirect URL) shown in Praxis after registration.
3. Configure user attributes — at minimum email; usually first name and last name as well.
4. Configure a group / role attribute so role mapping can resolve a Praxis role for each user.
5. Provide the IdP metadata URL (or pasted XML) — or for OIDC the discovery URL, client ID, and client secret — back to Praxis.

Email is required. If the IdP does not send an email attribute, sign-in fails. First name and last name are recommended but optional.

Common SAML attributes

The platform recognizes several common attribute name variants for each field — your IdP can use any of them.

Field	Recognized attribute names	Required
Email	email, http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress, urn:oid:0.9.2342.19200300.100.1.3	Yes
First name	firstName, givenName, http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname, urn:oid:2.5.4.42	No
Last name	lastName, surname, http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname, urn:oid:2.5.4.4	No
NameID	Built-in SAML field	Recommended (use email or persistent format)
Groups / roles	Custom — pick a name like groups, roles, or department and use the same string in Praxis role mapping	Required only if you use role mapping

The role-mapping attribute can carry a single string or an array; both formats are accepted.

Common OIDC claims

Field	Default OIDC claim	Notes
Email	email	Required. The boolean email_verified claim is also passed through if present.
First name	given_name	Optional.
Last name	family_name	Optional.
Display name	name	Optional fallback when given_name / family_name are absent.
Subject	sub	Built-in stable identifier — preferred over email for linking users to an IdP record.
Groups / roles	Custom — typically groups or roles; Auth0 requires a namespaced URI like https://praxis/roles	Required only if you use role mapping.

Praxis reads claim names exactly as configured under role mapping. Most IdPs use a plain name like groups; Auth0 needs a namespaced URI (see Auth0 OIDC).

Okta

1. Applications → Create App Integration → SAML 2.0.

2. General settings: name (for example Praxis), optional logo.

3. Configure SAML:

   • Single sign-on URL = ACS URL from Praxis.
   • Audience URI (SP Entity ID) = Audience value from Praxis.
   • Name ID format = EmailAddress. Application username = Email.

4. Attribute Statements:

   Name	Name format	Value
   email	Unspecified	user.email
   firstName	Unspecified	user.firstName
   lastName	Unspecified	user.lastName

5. Group Attribute Statements (for role mapping):

   Name	Name format	Filter	Value
   groups	Unspecified	Matches regex	.* (or scope to specific groups)

6. Sign On tab → View SAML setup instructions → Identity Provider metadata — copy the metadata URL.

7. In Praxis, finish the SSO wizard with that metadata URL and a role-mapping attribute of groups.

OIDC

1. Applications → Create App Integration → OIDC - OpenID Connect → Web Application.
2. General settings: name (for example Praxis), optional logo.
3. Grant type: keep Authorization Code (selected by default; required).
4. Sign-in redirect URIs = redirect URL from Praxis.
5. Sign-out redirect URIs (optional) = post-logout URL from Praxis if shown.
6. Assignments = restrict to a specific group/user set, or Allow everyone in your organization to access. Save.
7. From the General tab, copy Client ID and Client secret.
8. Add a groups claim so role mapping has something to match on:
   • Security → API → Authorization Servers → default → Claims tab → Add Claim.
   • Name = groups. Include in token type = ID Token, Always. Value type = Groups. Filter = Matches regex .* (or narrow to praxis-.*). Save.
9. Issuer URL = https://<your-domain>.okta.com/oauth2/default. The discovery URL Praxis needs is <issuer>/.well-known/openid-configuration.
10. In Praxis, finish the wizard with discovery URL + Client ID + Client secret. Set role-mapping attribute = groups.

Microsoft Entra ID (Azure AD)

1. Enterprise applications → New application → Create your own → Non-gallery.

2. Open the app, then Single sign-on → SAML.

3. Basic SAML Configuration:

   • Identifier (Entity ID) = Audience from Praxis.
   • Reply URL (ACS) = ACS URL from Praxis.

4. Attributes & Claims — keep the defaults for email/given/surname, or add unprefixed names if you prefer:

   Claim name	Source attribute
   http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress	user.mail
   http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname	user.givenname
   http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname	user.surname

5. Add a group claim:

   • Source = Security groups or Directory roles.
   • Customize the claim name to groups.
   • Source attribute: sAMAccountName, Cloud-only group display names, or Group ID — pick whichever string you will use in Praxis role mapping.

6. SAML Signing Certificate → App Federation Metadata Url — this is the metadata URL to paste into Praxis.

Group ID vs name: Entra ID often emits group object IDs (UUIDs) instead of display names. If you do, use those object IDs as the IdP value in each role-mapping row.

Overage claim: Users in roughly 200+ groups trigger Entra's overage behavior; the assertion contains a link instead of the group list and role mapping cannot resolve. Mitigate by mapping app roles instead, or by filtering the SAML group claim to a small set.

OIDC

1. Entra admin center → Entra ID → App registrations → New registration.
2. Name the app. Supported account types = Accounts in this organizational directory only (single tenant) for most cases.
3. Redirect URI = platform Web → paste the redirect URL from Praxis. Click Register.
4. From the Overview page, copy Application (client) ID and Directory (tenant) ID.
5. Certificates & secrets → Client secrets → New client secret → set expiry → copy the Value immediately (Entra only shows it once).
6. Token configuration → Add groups claim → choose Security groups (or Directory roles / All groups). For ID and Access token formats, Group ID is the safest choice (display names can change). Save.
7. Optional — app roles instead of groups:
   • App roles → Create app role with Value = the string Praxis should match (for example praxis-admin). Allowed member types = Users/Groups.
   • Assign users via Entra ID → Enterprise applications → your app → Users and groups → Add user/group.
   • App roles arrive in the roles claim instead of groups.
8. API permissions — the default User.Read (Microsoft Graph delegated) is enough for sign-in. Grant admin consent if required.
9. The OIDC discovery URL is https://login.microsoftonline.com/<tenant-id>/v2.0/.well-known/openid-configuration.
10. In Praxis, paste discovery URL + Client ID + Client secret. Set role-mapping attribute = groups (or roles if you used app roles). For groups by Group ID, the IdP value in each mapping row is the group's object ID (UUID).

Overage applies to OIDC too — the ~200-group limit triggers a _claim_names / _claim_sources pointer to Graph instead of the group list. Use app roles for users in many groups.

Google Workspace

Google Workspace does not send group memberships in SAML by default. You either map a custom user attribute into the assertion, or use Google Groups → SAML attribute (Enterprise/Education editions).

Custom-attribute approach (works on all editions)

1. Admin Console → Apps → Web and mobile apps → Add custom SAML app.

2. Google Identity Provider details: Download Metadata (you will give this XML to Praxis). Click Continue.

3. Service provider details:

   • ACS URL = ACS URL from Praxis.
   • Entity ID = Audience from Praxis.
   • Name ID format = EMAIL, Name ID = Basic Information → Primary email.

4. Directory → Users → More options → Manage custom attributes → Add Custom Attribute:

   Field	Value
   Category	Praxis
   Custom field name	Role
   Info type	Text
   Visibility	Visible to organization
   Number of values	Single (or Multi if a user may carry multiple roles)

5. Open each user that should sign in via SSO and set Praxis → Role (for example praxis-admin, praxis-member, praxis-viewer).

6. Back in the SAML app, SAML attribute mapping:

   Google attribute	App attribute
   Basic Information → Primary email	email
   Basic Information → First name	firstName
   Basic Information → Last name	lastName
   Praxis → Role	roles

7. User access → ON for everyone (or a specific OU/group). Allow a few minutes for propagation.

8. In Praxis, finish the wizard with the metadata XML and a role mapping attribute of roles.

Group-based approach (Workspace Enterprise/Education)

In the SAML app, open Group membership (optional), list the Google Groups you want to surface (for example [email protected]), and set App attribute = roles. Use the group email as the value in each role-mapping row.

Bulk role assignment: Use the Workspace Bulk update users CSV import to set the custom attribute (customSchemas.Praxis.Role) for many users at once.

OIDC variant

Google's OIDC implementation does not emit Google Group membership as a claim. Use OIDC only if all SSO users share the same role (set default_role in Praxis) or if you provision per-tenant roles inside Praxis after first login. For per-user roles driven by the IdP, stay on the SAML custom-attribute flow above.

1. Google Cloud Console → APIs & Services → Credentials → Create credentials → OAuth client ID.
   • First time only: configure the OAuth consent screen — set User type to Internal for Workspace-only access (no Google verification needed), or External with a verified domain.
2. Application type = Web application. Name it (for example Praxis).
3. Authorized redirect URIs = paste the redirect URL from Praxis. Click Create.
4. Copy the generated Client ID and Client secret (you can also download the JSON for safekeeping).
5. The OIDC discovery URL is https://accounts.google.com/.well-known/openid-configuration. Praxis requests the standard scopes openid email profile.
6. In Praxis, paste discovery URL + Client ID + Client secret. Leave role-mapping attribute empty so the connection's default_role applies to every user, or rely on Praxis-side per-tenant role assignment after first login.

Auth0

1. Applications → Create Application → Regular Web Application.

2. Addons tab → SAML2 Web App → enable. Set Application Callback URL = ACS URL from Praxis.

3. In the addon Settings JSON:

   {
     "mappings": {
       "email": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress",
       "given_name": "firstName",
       "family_name": "lastName"
     },
     "nameIdentifierProbes": [
       "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress"
     ]
   }

4. User Management → Roles — create the roles you want to map (for example praxis-admin, praxis-member, praxis-viewer). Assign users.

5. Inject roles into the SAML assertion via an Action on the Login flow:

   exports.onExecutePostLogin = async (event, api) => {
     const assignedRoles = event.authorization?.roles || [];
     if (event.transaction?.protocol === 'samlp') {
       api.samlResponse.setAttribute('roles', assignedRoles);
     }
   };

   (Auth0's legacy Rules also work; Actions are the recommended path.)

6. In the SAML2 addon, copy the Identity Provider Metadata URL (typically https://<your-tenant>.auth0.com/samlp/metadata/<client-id>) and paste it into Praxis.

7. In Praxis role mapping, use attribute = roles and add one row per Auth0 role.

OIDC variant

1. Applications → Create Application → Regular Web Application. Name it; the technology choice on the next screen does not affect the OIDC setup.

2. Settings tab → Application URIs → Allowed Callback URLs = redirect URL from Praxis. Save.

3. From the Settings tab copy Domain, Client ID, and Client Secret.

4. User Management → Roles — create the roles to map (for example praxis-admin, praxis-member, praxis-viewer) and assign users.

5. Auth0 does not include roles in tokens by default. Add an Action under Actions → Library → Build Custom, attach it to the Login flow, then deploy:

   exports.onExecutePostLogin = async (event, api) => {
     const roles = event.authorization?.roles || [];
     api.idToken.setCustomClaim('https://praxis/roles', roles);
     api.accessToken.setCustomClaim('https://praxis/roles', roles);
   };

   Custom claim names must be namespaced with a URI you control — Auth0 silently drops unnamespaced custom claims.

6. The OIDC discovery URL is https://<your-tenant>.auth0.com/.well-known/openid-configuration (or your custom domain).

7. In Praxis, paste discovery URL + Client ID + Client secret. Set role-mapping attribute = https://praxis/roles — the full namespaced URI, including the https:// prefix.

OneLogin

1. Applications → Add App → SAML Custom Connector (Advanced).

2. Configuration tab: Audience and ACS (Consumer) URL = the values from Praxis.

3. Parameters tab — Add the following with "Include in SAML assertion":

   Field name	Value
   email	Email
   firstName	First Name
   lastName	Last Name
   groups	User Roles or Groups

4. SSO tab → Issuer URL — that is your metadata URL. Paste it into Praxis.

5. In Praxis role mapping, use attribute = groups.

OIDC variant

1. Applications → Applications → Add App → search OpenID Connect (OIDC) → select it.
2. Display Name = for example Praxis. Save.
3. Configuration tab:
   • Login URL = your Praxis login URL (optional, surfaces the app in OneLogin's launcher).
   • Redirect URIs = redirect URL from Praxis (one per line if you have multiple environments).
4. SSO tab:
   • Copy Client ID.
   • Click Show client secret and copy Client Secret.
   • Application Type = Web.
   • Under Token Endpoint, set Authentication Method = POST (or Basic — match what your Praxis deployment expects; POST is the OneLogin default).
   • Right-click Well-known Configuration to copy the discovery URL — format: https://<subdomain>.onelogin.com/oidc/2/.well-known/openid-configuration.
5. Parameters tab → Add parameter:
   • Field name = groups.
   • In the parameter edit dialog, check Include in User Info and Include in ID Token.
   • Value = User Roles (or Groups if you organize users by OneLogin groups).
6. Access tab — assign the OneLogin Roles allowed to use this app.
7. In Praxis, paste discovery URL + Client ID + Client secret. Set role-mapping attribute = groups.

Generic SAML or OIDC

If your IdP is not in the presets, use SAML IdP or OIDC IdP in the connection wizard.

• SAML IdP — provide a metadata URL (preferred) or paste the metadata XML. Configure the IdP to send email, optionally firstName/lastName, and a custom group/role attribute (often groups or memberOf).
• OIDC IdP — provide the discovery URL (/.well-known/openid-configuration), the client ID, and the client secret. Make sure the IdP includes a groups (or similar) claim for role mapping; Praxis reads the claim name you configure under role mapping.

Role mapping — worked example

Suppose your IdP sends a groups attribute that lists Active Directory groups. In the SSO connection's role mapping panel:

{
  "attribute": "groups",
  "default_role": "viewer",
  "mappings": [
    { "value": "praxis-owners", "role": "owner" },
    { "value": "praxis-admins", "role": "admin" },
    { "value": "engineering",   "role": "member" }
  ]
}

Behaviour:

User's groups	Resolved Praxis role	Reason
["engineering"]	member	Single match
["engineering","praxis-admins"]	admin	Multiple matches; highest privilege wins
["praxis-owners","praxis-admins"]	owner	Highest privilege wins
["marketing"]	viewer	No match → default_role
(attribute missing)	viewer	No attribute → default_role

Matching is case-insensitive for both attribute values and role names. Order in mappings does not matter.

Pre-flight checklist

Before clicking Done in the Praxis SSO wizard:

• Email attribute is configured and reaches the assertion / token.
• First name / last name attributes are configured (recommended).
• NameID is email or a stable persistent ID.
• Group / role attribute is configured if you use role mapping.
• Each row in role mapping uses an exact IdP value (UUIDs for Entra group object IDs, group emails for Google Groups, etc.).
• ACS URL / Reply URL matches the value Praxis showed you.
• Audience / Entity ID matches the value Praxis showed you.
• You have provided the IdP metadata URL or XML (SAML), or discovery URL + client credentials (OIDC), to Praxis.
• You have assigned at least one test user to the IdP application.

If sign-in still fails, see Troubleshooting.

See also

• SSO — overview, scope (org-wide vs tenant), and Enforce SSO.
• Concepts and terminology — what role, scope, and tenant mean here.
• Troubleshooting — common SSO and role-mapping problems.