Skip to main content

Initial Project & User Management

This document describes some of the more advanced setup you may need to do while configuring and deploying the ARGO Messaging Service.

A typical quick-start scenario

After a fresh install of the ARGO Messaging Service, the steps you need to follow are:

  • Configure service_token: to enable the service.
  • Create a service_admin user: to start managing the service.
  • Create a project: Project entities is used as a basis of organizing and isolating groups of users & resources
  • Create a project_admin user: Users that have the project_admin have, by default, all capabilities in their project. They can also manage resources such as topics and subscriptions (CRUD) and also manage ACLs (users) on those resources as well.
  • Create a topic: The main resource that is scoped in a project, and can hold messages.
  • Create a subscription: A subscription is the main resource from which users consume messages.
  • Create users for the new resources: Usually a project has publisher and consumer accounts for clients that either are authorized to publish or consume messages.

Configure service_token

ARGO Messaging Service configuration includes the service_token parameter. This service_token configuration parameter can be used to create the first service_admin user of the service

First a service token must be defined in the config.json as such:

{
"bind_ip":"",
"port":8080,
"zookeeper_hosts":["localhost"],
"kafka_znode":"",
"store_host":"localhost",
"store_db":"argo_msg",
"certificate":"/etc/pki/tls/certs/localhost.crt",
"certificate_key":"/etc/pki/tls/private/localhost.key",
"per_resource_auth":"true",
"service_token":"S3CR3T",
"push_enabled": false
}

The service token in this example has the value: S3CR3T This service_token is authorized for all available actions (projects,users,topics,subscriptions).

In order to enable the use of this service_token you must restart the service.

service argo-messaging restart

Create a service_admin user

The service_token is intended to be used for the first initialization of the API. The first thing the service needs is a user with all possible capabilities, which is a service_admin. Now even though no user has been initialized in the service, the administrator can use the ARGO Messaging API Call with service_token S3CR3T to create the user. The service_admin will be able to further define projects and other users.

Using the service_token an admin can create a new service_admin user with the username demo_service_admin by calling:

POST https://{URL}/v1/users/demo_service_admin

with the following POST BODY:

{
"email": "sadmin@mail.example.foo",
"service_roles": [
"service_admin"
]
}

It is important to mention that the user has the "service_admin" role defined in the service_roles list in order to be a service_admin.

The response:

{
"projects": [],
"name": "demo_service_admin",
"token": "904c56cc6e2b1955dbd98ace80a45be8238432fc",
"email": "sadmin@mail.example.foo",
"service_roles": [
"service_admin"
],
"created_on": "2016-10-13T11:19:07Z",
"modified_on": "2016-10-13T11:19:07Z"
}

The generated token 904c56cc6e2b1955dbd98ace80a45be8238432fc can be used to authenticate the new user. For more details visit the API Users to see all possible actions for users.

Create a project

Using the demo_service_admin account, the user can create the first project (ex named 'DEMO') by issuing:

POST https://{URL}/v1/projects/DEMO

with the following POST BODY:

{
"description": "my first demo project"
}

and the response:

{
"name": "DEMO",
"created_on": "2016-10-13T12:19:07Z",
"modified_on": "2016-10-13T12:19:07Z",
"created_by": "demo_service_admin",
"description": "my first demo project"
}

Response informs that the project has been indeed created_by the demo_service_admin user.

For more details visit the API Projects to see all possible actions for projects.

Create a project_admin

Service_admin users are not attached to specific projects. Instead each project should have a project_admin user that will manage topics, subscriptions and ACLs on those resources. To create a project_admin user in project DEMO, the user demo_service_admin will issue:

POST https://{URL}/v1/users/admin_DEMO

with the following POST BODY:

{
"email": "demoadmin@mail.example.foo",
"projects": [
{
"project": "DEMO",
"roles": [
"project_admin"
]
}
]
}

The user definition (in POST body) should have the field projects defined. The field accepts a list of tuple items ( project,roles) which describe each project that the user participates to and under which roles. A user can have multiple roles in a project and also participate in multiple projects as well. In this example, the user must participate in project DEMO and under the role of project_admin.

The response:

{
"projects": [
{
"project": "DEMO",
"roles": [
"project_admin"
]
}
],
"name": "admin_DEMO",
"token": "6311196665befcc1523b8e013979347b8780254c",
"email": "demoadmin@mail.example.foo",
"service_roles": [],
"created_on": "2016-10-13T12:29:07Z",
"modified_on": "2016-10-13T12:29:07Z",
"created_by": "demo_service_admin"
}

For more details visit the API Users to see all possible actions for users.

Create a topic

Service_admin users don't manage resources such as topics/subscriptions. Instead in each project the project_admin is eligible for creating (and managing) topics and subscriptions. To create a new topic (named topic101) as admin_DEMO user in project DEMO the user issues:

PUT https://{URL}/v1/projects/DEMO/topics/topic101

with response:

{
"name": "/projects/DEMO/topics/topic101"
}

Notice that the token used in api key changes to that of the admin_DEMO user

For more details visit the API Topics to see all possible actions for topics.

Create a subscription

To create a new subscription (named sub101) to topic topic101 of project DEMO the admin_DEMO user issues:

PUT https://{URL}/v1/projects/DEMO/subscriptions/subs101

with POST Body:

{
"topic": "projects/DEMO/topic/topic101"
}

and response:

{
"name": "/projects/DEMO/subscriptions/sub101",
"topic": "/projects/DEMO/topics/topic101",
"pushConfig": {
"pushEndpoint": "",
"retryPolicy": {}
},
"ackDeadlineSeconds": 10
}

For more details visit the API Subscriptions to see all possible actions for Subscriptions.

Create users for the new resources

Usually a project will have also publisher and consumer accounts for clients that either are authorized to publish or consume messages. The user demo_service_admin can create a publisher_DEMO and consumer_DEMO for project DEMO as such:

To create the publisher_DEMO user:

POST https://{URL}/v1/users/publisher_DEMO

with POST Body:

{
"email": "demopublisher@mail.example.foo",
"projects": [
{
"project": "DEMO",
"roles": [
"publisher"
]
}
]
}

resulting in response:

{
"projects": [
{
"project": "DEMO",
"roles": [
"publisher"
]
}
],
"name": "publisher_DEMO",
"token": "915dff62846dd1d790b4296c034c184fa3a859b6",
"email": "demopublisher@mail.example.foo",
"service_roles": [],
"created_on": "2016-10-13T12:39:07Z",
"modified_on": "2016-10-13T12:39:07Z",
"created_by": "demo_service_admin"
}

To create the consumer_DEMO user:

POST https://{URL}/v1/users/consumer_DEMO

with POST Body:

{
"email": "democonsumer@mail.example.foo",
"projects": [
{
"project": "DEMO",
"roles": [
"consumer"
]
}
]
}

resulting in response:

{
"projects": [
{
"project": "DEMO",
"roles": [
"consumer"
]
}
],
"name": "consumer_DEMO",
"token": "dba38fd1a45337a617a59e7278c756f23642e9e7",
"email": "democonsumer@mail.example.foo",
"service_roles": [],
"created_on": "2016-10-13T12:40:07Z",
"modified_on": "2016-10-13T12:40:07Z",
"created_by": "demo_service_admin"
}

For more details visit the API Users to see all possible actions for users.

Modify topic ACL to give access to publisher

In order to give access to user publisher_DEMO to topic topic101, the user admin_DEMO must modify the topic's ACL as such:

POST https://{URL}/v1/projects/DEMO/topics/topic101:modifyAcl

with POST body:

{
"authorized_users": [
"publisher_DEMO"
]
}

and empty response with 200 OK

Now the user publisher_DEMO will be authorized to call action topic:publish on topic101 and send messages

Modify subscription ACL to give access to consumer

In order to give access to user consumer_DEMO to subscription sub101, the user admin_DEMO must modify the subscription's ACL as such:

POST https://{URL}/v1/projects/DEMO/subscriptions/sub101:modifyAcl

with POST body:

{
"authorized_users": [
"consumer_DEMO"
]
}

and empty response with 200 OK

Now the user consumer_DEMO will be authorized to call action subscription:pull on sub101 and consume messages