Configure JSON web token (JWT) API authentication

In this topic, you learn how to set up authentication via a JSON web token (JWT) and how to configure it in your Cockpit. You must perform multiple tasks to enable the connection.

Prerequisites

  • You have registered the Neptune DXP - Open Edition in the Microsoft Entra admin center. Find more information about how to register an app on Microsoft documentation.

  • You know the tenant ID from the Microsoft Entra admin center for your Neptune DXP - Open Edition.

Procedure

  1. In the Cockpit, go to Settings, and select System Settings.

  2. In the Authentication tab, select Edit.

  3. Select + Add and select JWT.

    Result: The Authentication window opens.

  4. Enter a Name for the authentication.

  5. Select Active to activate this authentication method.

  6. Enter a Description.

  7. Enter a Path to retrieve a Neptune DXP - Open Edition session, for example, /user/logon/jwt/(path). You can add any string as a path.

  8. You can add an Issuer validation.

  9. You can add an Audience validation.

  10. In Secret, add a secret key for the validation if no JSON web key set (JWKS) URL is provided.

    Jwks Url

    Add the URL that leads to the JWKS. For example:

    https://login.microsoftonline.com/<tenantid>/discovery/v2.0/keys

  11. In Proxy for JSON Web Key Sets URL, add a proxy for your JWKS URL. You can add any string.

  12. Set a token header field in Override Default Jwt Extraction Method - From Authorization Header as Bearer Token

  13. In Claims Assignment, you can map incoming identity-provider claims to user properties within the system. Each entry consists of three parts:

    • Claim: The name of the incoming claim or scope provided by the authentication authority.

    • Default: An optional fallback value used when the claim is missing or not supplied.

    • User Fields: A selectable internal user attribute (for example, Username, Email, Language, Name, Phone, Mobile) that the claim should populate.

      You can create multiple rows to define as many claim–to–property mappings as required. When a user signs in, the system evaluates the received token, applies the mappings, and populates or updates the corresponding user fields accordingly.

  14. If required, in Auto Assignment, assign roles and groups that you have defined in the Role and Security Group tools in the Cockpit.

  15. In Post Authentication Script, use Script to select a server script that should run after authentication. The script has access to the global variables profile, user, and updatedUser.

    If no server script is selected, you can enter custom logic in Function (profile, user, updatedUser, require, getEntityRepository, log). This allows you to run post-authentication code, such as logging details or modifying the variables, for example:

    log.info("XXuser",user);
log.info("XXprofile",profile);
log.info("Member of:"+ profile.memberof);
    Inline post-authentication scripts will be deprecated in a future patch. Plan to move any custom logic to a server script.

  16. Select OK to confirm.

    Result: The Authentication dialog closes.

  17. In System Settings, select Restart to activate JSON web token authentication.

Results

  • You have configured and activated a JWT authentication.

Related topics