Skip to main content
Version: v44

Ephemeral Users with External JWT Authentication

Ephemeral user directories allow users to log in to PrivX with externally issued JSON Web Tokens (JWTs), without having to pre-create them in PrivX.

This setup is typically used for machine-to-machine (M2M) users and other non-human accounts whose identities are managed by an external issuer. PrivX validates the JWT with a configured external token provider, creates or updates the user in an ephemeral user directory, and assigns roles according to role rules.

For JWT authentication where users already exist in PrivX, see External JWT Authentication.

Prerequisites for Ephemeral JWT Users​

  • You have an external JWT identity provider that issues JWTs to users or workloads.

  • You have a JWT validation key, certificate, or x5u configuration for the external token provider.

  • JWTs from your identity provider include the iss and sub claims.

  • JWTs used for ephemeral users should include the exp claim. PrivX uses the JWT expiration time to determine how long mapped roles remain valid.

  • You have planned the role rules that will grant PrivX roles to ephemeral users. For more information about roles, see Granting User Permissions.

info

PrivX stores JWT claims for ephemeral users as user attributes. This allows role rules and attribute mapping to use custom JWT claims.

The examples in this procedure use a CI runner that authenticates to PrivX with a JWT issued by a trusted external identity provider. The signed JWT payload can use the following format:

{
    "iss": "https://idp.example.com",
    "sub": "ci-runner-123",
    "aud": "privx",
    "exp": 1893456000,
    "groups": ["deploy-prod", "database-maintenance"]
}

Create an Ephemeral User Directory​

To add an ephemeral user directory to PrivX:

  1. On Administration→Directories, click Add Directory.

  2. Set Type to Ephemeral Users.

  3. Provide a name for the directory.

  4. Under Ephemeral Users Settings, configure the allowed login methods and default role behavior.

    For this example, enable Allow Logging in as an API User. Enable Allow Logging in as a Regular User and Grant privx-user Role only if the ephemeral users also need access to the PrivX GUI.

  5. Set Attribute for Tags to the JWT claim that PrivX should map to user tags.

    For this example, set Attribute for Tags to groups. PrivX can then use values from the groups claim as user tags in role rules.

  6. Under User Lifecycle Policy, set User Purge Delay After Last Login (minutes) according to your user-retention requirements.

    After an ephemeral user's JWT-based validity has expired, PrivX housekeeping removes the user from the user cache and database after the configured delay.

  7. Configure any remaining directory settings according to your deployment requirements.

  8. Click Save to apply the directory settings.

Ephemeral user directories do not synchronize users from a remote source. Users are created or updated during successful JWT login.

Configure the External Token Provider​

To configure PrivX to trust JWTs for ephemeral users:

  1. On Administration→Deployment→External Token Authentication, click Add New Provider.

  2. In General settings, provide the provider name and select the ephemeral user directory as Users Directory.

  3. Set Subject type according to the format of the JWT's sub claim.

    If sub contains the user name directly, set Subject type to Plain.

    For the example token, set Subject type to Plain because sub contains ci-runner-123 directly.

    If sub is in DN format, set Subject type to DN and configure DN attribute.

  4. Configure Public key settings for validating JWT signatures.

    You may provide static public keys, fetch certificates from the JWT x5u header, or fetch public keys from the JWT x5u header. For more information about the available public-key methods, see External JWT Authentication.

  5. Set Issuer to match the JWT's iss claim.

    Optionally specify an audience value that must be present in the JWT's aud claim.

    For the example token, set Issuer to https://idp.example.com and Audience to privx.

  6. (Optional) Under Custom parameter validation, specify additional claims that must be satisfied before PrivX accepts the JWT.

  7. Click Save to apply the provider settings.

JWTs from this provider can now create or update users in the selected ephemeral user directory.

Map JWT Claims to Roles​

Ephemeral users receive roles through normal PrivX role rules.

With the example token in this procedure, set Attribute for Tags to groups and create role rules that match the deploy-prod or database-maintenance tags.

Mapped roles granted from JWT claims remain valid until the JWT expires. After the token expires, the user must log in again with a valid JWT to regain those mapped roles.

Explicitly granted roles are not removed when the JWT expires. Use explicit roles when an ephemeral user should retain specific access independently of the latest JWT login.

Log In with a JWT​

Ephemeral users log in by exchanging an external JWT for a PrivX access token:

POST /auth/api/v1/token/login

To test the login flow, first generate and sign a JWT with the issuer key trusted by the external token provider. Then send the compact JWT to the token-login endpoint. For example:

{
    "token": "<signed-jwt-token>",
    "client_id": "privx-external",
    "scope": "hosts-view"
}

In this example, <signed-jwt-token> is the encoded JWT whose payload contains the iss, sub, aud, exp, and groups claims shown earlier. The client_id identifies the PrivX OAuth client used for the exchange, and scope requests the access scope for the returned PrivX token.

On successful login, PrivX:

  • Validates the JWT signature and configured claims.

  • Creates the user in the ephemeral user directory if the user does not already exist. Created users are visible under Administration→Users.

  • Evaluates role rules and grants matching mapped roles.

  • Returns a PrivX bearer token that can be used for the requested API access.

Expiration and Housekeeping​

Ephemeral users are persisted to the PrivX database during login. This allows PrivX to show user information in logs, audit events, and administrative views.

When the JWT expires:

  • The user's mapped roles expire.

  • The user must log in with a valid JWT to regain mapped roles.

  • Explicitly granted roles remain available.

  • The user remains in the user cache and database until the User Purge Delay After Last Login (minutes) has passed and housekeeping removes the user.