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. Controllers
      2. Globals
      3. HTTP
      4. Events
      5. Error handler
      6. Filters
      7. ID provider
      8. Tasks
      9. Templating
      10. Localization
      11. Websocket
      12. Mappings
      13. Components
      14. Processors
      15. Contributions
      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 Stable Iam System Idp

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:

The Super User

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 accounts users can be recognized from the small cog symbol above their avatar in the top right.

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:

List of service account keys
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.

Generate key

You may easily generate new keys by clicking add. Simply give your key a name, and click btn:generate.

Generate service account key
The public key will be saved, and the private key will automatically be downloaded to your device (in JSON format).

Upload key

You may also upload the public key portion of a user-managed key pair, and the use the private key for authenication later.

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

Try it out The following command generates a 2048-bit RSA key pair

openssl genpkey -algorithm RSA -out xp_private_key.pem -pkeyopt rsa_keygen_bits:2048 && \
openssl rsa -pubout -in xp_private_key.pem -out xp_public_key.pem

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

Upload public key
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 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.

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

JWT parts must be signed and encoded according to RFC-7519.

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

Contents

Contents