Docs Developer Site
Enonic XP
arrow-down
    1. Widgets
    1. ID providers
    2. System ID provider
    3. Users and groups
    4. Roles
    1. Projects
    2. Layers
        1. AttachmentUploader
        2. Checkbox
        3. Combobox
        4. ContentSelector
        5. ContentTypeFilter
        6. CustomSelector
        7. Date
        8. DateTime
        9. Double
        10. GeoPoint
        11. HtmlArea
        12. ImageSelector
        13. Long
        14. MediaSelector
        15. Radiobutton
        16. Tag
        17. TextArea
        18. TextLine
        19. Time
      2. Field set
      3. Item set
      4. Option set
      5. Mixins
      6. Localization
    4. Content Types
    5. X-data
    6. Macros
    7. Custom styles
    8. Sites
      1. Regions
      2. Part component
      3. Layout component
      4. Text component
      5. Fragments
      6. Filtering
      7. Component indexing
      8. Visual editor
    10. Page templates
  4. Applications
    1. Sandboxes
    2. Code
    3. Building
    4. Configuration
    5. TypeScript
      1. Globals
      2. HTTP
      3. Controllers
      4. Filters
      5. Events
      6. Websocket
      7. Error handler
      8. ID provider
      9. Tasks
      10. Localization
      11. Mappings
      12. Components
      13. Processors
      14. Contributions
      15. Templating
      16. Main controller
      17. Java bridge
      1. Admin API
      2. Application API
      3. Auditlog API
      4. Authentication API
      5. Cluster API
      6. Common API
      7. Content API
      8. Context API
      9. Event API
      10. Export API
      11. Grid API
      12. I18N API
      13. IO API
      14. Mail API
      15. Node API
      16. Portal API
      17. Project API
      18. Repo API
      19. Scheduler API
      20. Schema API
      21. Tasks API
      22. Value API
      23. VHost API
      24. Websocket API
      1. Webapp Engine
        1. Image service
        2. Component service
      3. Admin Engine
      4. Asset service
      5. HTTP service
      6. IDprovider service
    2. Task engine
    3. Management Endpoint
    4. Statistics Endpoint
    1. Nodes and repos
    2. Properties
    3. Indexing
    4. Branches
    5. Queries (NoQL)
    6. Queries (DSL)
    7. Filters
    8. Aggregations
    9. Highlighting
    10. Editors
    1. Strategies
    2. Distributions
    3. Docker image
    4. Vhosts
    5. Configuration
    6. Backup & restore
    7. Systemd
    8. Clustering
  9. Audit Logs
    1. Upgrade Notes
    2. Upgrading Apps
Developer Docs Xp Next Iam Systemidp

System ID provider

Contents

Introduction

XP ships with a special ID provider that cannot be removed or renamed. It is called the System ID provider.

Built-in

When accessing the XP admin console for the first time in a fresh installation, you will see the login screen of System ID provider.

System ID provider login screen

System users

The System ID provider also contains some special users:

system:su The Super User exists in order to perform priveliged actions, and to allow you to start using XP before you have created any users. The Super User has the system.admin role, and thus unrestricted access.

system:anonymous - XP expects a user in every request. As such, the Anonymous user steps in to cover for users that have not authenticated.

Service Accounts

Unlike other ID providers, the users in the System IDP are referred to as service accounts.

Service accounts are designed for machine-to-machine authentication from remote clients to XP.

Avoid adding human users to the System ID provider, rather create a new ID provider for this purpose.

Since service accounts also are regular XP users, you may grant them roles and permissions as needed.

Service Account Key

A Service Account may be associated with one, or several Service Account keys. Using a Service Account Key is beneficial for security reasons:

  • It allows to authenticate without transferring the password over the network.

  • Support for multiple keys allow rotation of Public-Private key-pairs without service interruption.

  • Stored Public key is not a hash of a password, so it is not possible to reverse-engineer the password from the public key.

Once a key is created, it may be used to make an authorized call to:

Generate key

TODO: Screenshot

Upload key

You can upload the public key portion of a user-managed key pair to associate it with a service account, and the use the private key for authenication later.

The key you upload must be an RSA public key that is wrapped in an X.509 v3 certificate and encoded in base64. You can use tools such as OpenSSL to generate a key and certificate in this format.

Do not include private information in the X.509 certificate. Specifically, use a generic subject, and avoid optional attributes. Any private information in the certificate is visible to anyone who retrieves the certificate.

Try it out The following command generates a 2048-bit RSA key pair and wraps the public key in a self-signed certificate that is valid for 365 days:

openssl req -x509 -nodes -newkey rsa:2048 -days 365 \
    -keyout /path/to/private_key.pem \
    -out /path/to/public_key.pem \
    -subj "/CN=unused"

After generating the key, you may upload it the private_key.pem file to your service account.

JWT authentication

The System ID providers supports JWT (JSON Web Token) based authentication via the HTTP Authorization header.

Content of the header should look like the following:

Authorization: Bearer <mytoken>

A JWT token must be a valid RFC-7519 JWT token, following these requirements:

  • alg header parameter must be set to RS256.

  • kid header parameter must be set to ID of the public key that corresponds to the private key used to sign the token.

  • sub claim must be set to ID of the service account, for instance, user:system:myuser.

  • exp claim must be set to expiration time of the token. The token will be rejected if it is expired.

  • iat claim must be set to issue time of the token. The token will be rejected if it was issued in the future.

Your private key from the Public-Private key pair is stored only on the client side and must never be shared with the XP server.

The public key from Public-Private key pair is stored in XP, and is used to verify the signature of your token.

JWT header example 
{
  "kid": "51a29c2ab5ebf945f6a5ddac8935bf8b",
  "typ": "JWT",
  "alg": "RS256"
}
JWT payload example 
{
  "sub": "user:system:myuser",
  "exp": 1692787396,
  "iat": 1692787366
}

In general we recommend using libraries that match your platform to generate the token, as performing this manually can be cumbersome.

Service account keys are a security risk if not managed correctly. Make sure to rotate keys regularly and keep them safe. If you suspect that your keys have been compromised, you can revoke them in the Users app. Also consider using ID providers that support 3-leg authentication, such as the OIDC ID provider, if possible.

Contents

Contents