Security for Axon Framework Client Applications

Applications need to provide a valid token before they can perform all operations. The access token can be setup in the client using the property axon.axonserver.token=<token>. The Axon Server connector will use this to authenticate the client to the server.

Using the CLI to register client apps (Axon Server EE only)

In Axon Server EE, instead of setting a single token in axonserver.properties, you must register applications with specific roles. Please do note that you’ll need either a user with ADMIN level access to do this in the UI, or access to the system token for use with the CLI.

To register an application and get an access token use the “register-application” command. This command will return the token to use, which can be specified on the commandline, or generated by Axon Server. Note that this token is only generated once; if you lose it you must delete the application and register it again to get a new token. The command register-application has several options:

$ java -jar axonserver-cli.jar register-application
usage: register-application
 -a,--application <arg>    Name of the application
 -d,--description <arg>    [Optional] Description of the application
 -i,--insecure-ssl         Do not check the certificate when connecting
                           using HTTPS.
 -o,--output <arg>         Output format (txt,json)
 -prop,--property <arg>    [Optional] properties for a context/application
                           (specify as name=value)
 -r,--roles <arg>          Roles for the application, use role@context
 -S,--server <arg>         Server to send command to (default
                           http://localhost:8024)
 -s,--https                Use HTTPS to connect to the server, rather than
                           HTTP.
 -t,--access-token <arg>   [Optional] Access token to authenticate at
                           server
 -T,--token <arg>          use this token for the app
Error processing command 'register-application': Invalid command

Mandatory parameters

  • -a or --application specifies the name of the application.

  • -r or --roles specifies the roles of the application. Specify multiple roles by giving a comma separated list, for example “READ,ADMIN”.

Optional parameters

  • -d or --description specifies a description of the application, which will be shown in overviews.

  • -T or --token can be used to specify the token you want to use for a newly registered application.

  • -prop or --property adds an application specific property. These properties will be provided to any plugin processing messages from/for that application.

  • -t or --access-token specifies the access token to authenticate at the server to which the command is sent to. For SE this should be the same as the (admin) token set in the properties. For EE this should be the security token discussed above.

  • -S or --server can be used to specify the URL to the server that the command needs to be sent to. If this is not supplied it connects to “http://localhost:8024”; by default.

  • -s or --https will cause the CLI to use TLS, in effect changing the URL to “https://localhost:8024”;. Note that if you also want to change the port, you’ll have to use “-S”, in which case you can leave out “-s”.

  • -i or --insecure-ssl will tell the CLI that Axon Server is using a certificate which is not signed by a known CA, for example when using self-signed certificates.

The ADMIN role is only valid for the admin context, the other roles are specific to another context. In addition to the role name you can also supply the context to which this role applies, for example _{role_name}@{context_name}. Also if no context is mentioned in Axon Server EE, the role is granted to the application for all registered contexts, including contexts that are created after the role has been granted.

The token that you set here must be used by all Axon Framework Applications connecting to Axon Server. The access token can be setup in the client using the property axon.axonserver.token=[Token]

If you are using the REST APIs, you can specify the token in the HTTP requests via the following header:

AxonIQ-Access-Token: my-token-value-here