Skip to main content

JumpCloud Integration

JumpCloud is a standard OIDC identity provider and SCIM 2.0 directory. AxonFlow uses it for per-user fleet identity: each developer authenticates with a JumpCloud-issued OIDC token, and their role is resolved from the SCIM-synced directory rather than from any claim inside the token.

This gives a fleet two things a single shared credential cannot:

  • Attribution — every governed action is tied to the individual developer's validated identity.
  • Authorization — the developer's role comes from the directory AxonFlow audits, so an IdP misconfiguration cannot mint an administrator.

JumpCloud is first-classed as an OIDC provider (provider: "jumpcloud"). It uses the same verifier inputs — issuer, audience, JWKS URI — as the generic oidc provider; selecting JumpCloud simply pre-fills its well-known endpoints.

How the Two Halves Fit Together​

ConcernSourceMechanism
Who the user is (identity)The JumpCloud OIDC tokenValidated against JumpCloud's JWKS (issuer, audience, expiry, RS256 signature)
What the user can do (role)The SCIM-synced directoryGroup-to-role mapping, never a token claim

Configure SCIM first so the directory is populated before any token resolves to more than least privilege.

Before You Configure JumpCloud​

Have these ready:

  • JumpCloud admin access
  • an AxonFlow SCIM token created from the customer portal
  • the real enterprise portal hostname for the tenant you are provisioning into
  • an operator with the sso:configure permission for the OIDC and role-mapping steps

Part 1 — SCIM Provisioning​

Step 1: Create the AxonFlow SCIM token​

In the customer portal, go to Settings → SCIM → Create Token and copy the token once. It is not shown again. Your SCIM base URL looks like this:

https://YOUR_PORTAL_OR_ENTERPRISE_DOMAIN/scim/v2

Step 2: Add JumpCloud SCIM/directory sync​

  1. In the JumpCloud Admin Console, open the application you use for AxonFlow (or create one) and enable Identity Management.

  2. Point the SCIM connector at https://YOUR_PORTAL_OR_ENTERPRISE_DOMAIN/scim/v2.

  3. For authentication, use a header with the full bearer-token format:

    Bearer scim_your_token_here

    That matches the SCIM middleware, which expects an Authorization header with the Bearer scheme.

Step 3: Assign a pilot group​

Do not begin with a company-wide assignment. Assign one pilot developer group so users and groups sync, then verify:

  • the users appear in the right tenant
  • the identity shape is correct
  • update and deactivation flows behave correctly

Step 4: Map JumpCloud groups to roles​

Roles come from the directory, never from the token. Map each synced JumpCloud group to an AxonFlow role using the group-to-role mapping endpoints (portal session, gated by sso:configure):

MethodEndpointPurpose
GET/api/v1/scim/rolesList assignable role IDs
GET/api/v1/scim/groups/role-mappingsList current group-to-role mappings
PUT/api/v1/scim/groups/{id}/role-mappingSet or clear a mapping for one synced group

The fleet resolver keys on the role name, so map groups to the seeded system roles (admin, owner, policy_admin, developer, member, viewer). Mapping a group to a differently-named custom role resolves to least privilege.

See Group to Role Mapping for rollout order and naming guidance.

Part 2 — OIDC SSO (Per-User Fleet Identity)​

Step 5: Create the OIDC application in JumpCloud​

  1. JumpCloud Admin Console → SSO Applications → Add New Application → Custom OIDC App.
  2. Grant type: Authorization Code (add Refresh Token as desired). Set the redirect URI to your token-delivery tooling (a device-flow or CLI helper).
  3. Note the values you will need in AxonFlow:
    • Issuer: https://oauth.id.jumpcloud.com/
    • JWKS URI: https://oauth.id.jumpcloud.com/.well-known/jwks.json
    • Audience: your app's client ID (or a custom audience you configure)
  4. Ensure the email claim is included by requesting the standard openid email scopes.
  5. Assign the app to the same developer group(s) you synced via SCIM.
Verify against your own tenant

Confirm the issuer, JWKS URI, and scopes against your tenant's discovery document at https://oauth.id.jumpcloud.com/.well-known/openid-configuration rather than copying them. A mismatched iss or aud is rejected, which looks identical to "tokens don't work".

Step 6: Configure the OIDC provider in AxonFlow​

Create the SSO configuration (portal session, gated by sso:configure):

curl -X POST "$PORTAL_URL/api/v1/sso/config" \
  -H "Cookie: <portal session>" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "jumpcloud",
    "enabled": true,
    "oidc_issuer": "https://oauth.id.jumpcloud.com/",
    "oidc_audience": "<your client id>",
    "oidc_jwks_uri": "https://oauth.id.jumpcloud.com/.well-known/jwks.json",
    "oidc_claim_mapping": {"email": "email"}
  }'
  • POST creates and returns 409 if a config already exists. To change an existing config, use PUT /api/v1/sso/config with the same body.
  • Issuer and JWKS URI must use HTTPS. URLs that resolve to private or cloud-metadata endpoints (169.254.169.254, RFC-1918 hosts, *.internal) are rejected, because AxonFlow fetches these server-side.
  • Use a per-tenant issuer or audience. The verifier trusts the identity in a token signed by the configured issuer and audience. If two tenants configure the same issuer and audience, a token minted for one is structurally valid for the other. Give each tenant a distinct OIDC app so a token cannot cross a tenant boundary.
  • oidc_claim_mapping.email names the claim carrying the developer identity (default email; some IdPs use preferred_username).

You can retrieve JumpCloud's pre-filled defaults from GET /api/v1/sso/providers/defaults?provider=jumpcloud.

  1. Configure SCIM and validate provisioning with a pilot group.
  2. Map the pilot group to a non-privileged role (for example developer).
  3. Create the JumpCloud OIDC app and configure the provider in AxonFlow.
  4. Validate one developer's end-to-end login: token validates, role resolves.
  5. Expand group assignment and role mapping gradually.

Common Issues​

Every token is rejected​

Check that the configured oidc_issuer and oidc_audience exactly match what JumpCloud emits (including any trailing slash on the issuer). Confirm the JWKS URI is reachable over HTTPS and the token is RS256-signed.

Login succeeds but the developer can read nothing​

The SCIM directory is not populated, or the developer's group is not mapped to a role. Provision the group first, then map it — an unmapped identity resolves to least privilege by design.

sso:configure denied​

The OIDC configuration and group-to-role mapping endpoints are privilege grants, so they require the sso:configure permission and are deliberately not reachable with a SCIM directory-sync token.

Last updated on