You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
This repository was archived by the owner on Jun 10, 2025. It is now read-only.
Copy file name to clipboardExpand all lines: src/markdown-pages/docs/ecosystem/ecosystem-architecture.md
+11Lines changed: 11 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -67,3 +67,14 @@ The following diagram highlights some of the key components that make up the Gal
67
67
|**Kabana**| A dashboard for visualizing Elasticsearch metrics. Data can be explored through queries and drilldown. |
68
68
69
69
</details>
70
+
71
+
### Key concepts:
72
+
73
+
These concepts are relevant when running tests locally, or when submitting tests to a remote Galasa service:
74
+
- A **test case** - A piece of test logic which can be compiled or translated into something which is runnable by the Galasa framework. This may be a piece of Java code for example, or a Gherkin test feature.
75
+
- A **test run** - Also known as a 'run' - An execution of the testcase which was started at a certain point in time, executed logic steps, and is still running, or has finished with a test status and result. For example: Passed or Failed.
76
+
77
+
Some concepts are only relevant on a Galasa service:
78
+
- A **user** - The authorised person manipulating the Galasa system in some way.
79
+
-**Role based access control (RBAC)** - The mechanism where the Galasa service will allow some users to perform any available task, but limit what other users can do. This is to help isolate some system capabilities for safety or for security. Read more about the RBAC in the [role-based access](./ecosystem-role-based-access.md) section.
Before interacting with a Galasa Ecosystem using the Galasa command line tool (galasactl), you must be authenticated with it. Galasa uses personal access tokens to authenticate users who want to interact with a Galasa Ecosystem provided by the `GALASA_BOOTSTRAP` environment variable or through the `--bootstrap` flag.
6
+
Before interacting with a Galasa Ecosystem using the Galasa command line tool (`galasactl`), you must be authenticated with it. Any `galasactl` command which connects to a remote Galasa service needs to know the address of that service. A URL can be configured in the `GALASA_BOOTSTRAP` environment variable or it can be set on a per-command basis using the `--bootstrap` flag.
7
7
8
+
Once the `galasactl` tool knows which Galasa service to contact, it needs to be configured to be able to authenticate to that service.
9
+
To do that, the Galasa Web UI must be used to allocate a personal access token, which can be passed to the `galasactl` to be used.
8
10
9
-
Personal access tokens are stored in the `GALASA_TOKEN` property in the `galasactl.properties` file in your Galasa home folder. The `galasactl.properties` file is created when you run the `galasa local init` command. Setting the `GALASA_TOKEN` property in this file with a valid token value allows the galasactl tool to access and communicate with an Ecosystem on behalf of the user.
11
+
A personal access tokens is stored in the `GALASA_TOKEN` property in the `galasactl.properties` file in your Galasa home folder, or in the `GALASA_TOKEN` environment variable. The `galasactl.properties` file is created when you run the `galasa local init` command. Setting the `GALASA_TOKEN` property in this file with a valid token value allows the galasactl tool to access and communicate with an Ecosystem on behalf of the user.
10
12
11
-
12
-
If you have [installed your Galasa Ecosystem](../ecosystem/ecosystem-installing-k8s) by using the Galasa Ecosystem Helm chart that is provided with Galasa, you will have access to the Galasa Web UI. To get a value for the `GALASA_TOKEN` property, log into the Galasa Web UI and request a personal access token which can be copied into the `GALASA_TOKEN` property. The instructions on how to do this are displayed in a dialog box in the Galasa Web UI. You can choose to set the token as an environmental variable but the value would not persist across terminals, so is only valid for that session.
13
+
If you have [installed your Galasa Ecosystem](../ecosystem/ecosystem-installing-k8s) by using the Galasa Ecosystem Helm chart that is provided with Galasa, you will have access to the Galasa Web UI. To get a value for the `GALASA_TOKEN` property, log into the Galasa Web UI and request a personal access token (using the 'My Settings' page) which can be copied into the `GALASA_TOKEN` property. The instructions on how to do this are displayed in a dialog box in the Galasa Web UI. You can choose to set the token as an environmental variable but the value would not persist across terminals, so is only valid for that session.
13
14
14
15
## Authentication architecture
15
16
@@ -18,10 +19,13 @@ The following diagram shows the architecture for the authentication process:
When a user logs into the Galasa Web UI via their browser, the Web UI contacts the Galasa API server which in turn talks to a Dex server, providing it with the user ID. The Dex server talks to an identity provider, for example GitHub or LDAP, to authenticate that user. If the user is successfully authenticated, the provider returns an access token to the Dex server which sends that token to Galasa API server. The token is then sent to the Galasa Web UI where it is visible to the user. The user can then configure that token into the galasactl command line tool by updating the `GALASA_TOKEN` property in the `galasactl.properties` file. The user can then be authenticated each time the galasactl tool is used to log into a Galasa Ecosystem.
22
+
When a user logs into the Galasa Web UI via their browser, the Web UI contacts the Galasa API server which in turn talks to a Dex server, providing it with the user ID. The Dex server talks to an identity provider, for example GitHub or LDAP, to authenticate that user. If the user is successfully authenticated, Dex returns a bearer token to the Galasa API server, which in turn passes the token to the Galasa Web UI. The bearer token is then stored in a cookie by the web browser, to be used in further interactions with the Galasa Web UI until the user logs out of the web application, or the token expires.
23
+
24
+
Once logged-in to the Web UI, the user can then create a new access token token (using the 'My Settings' page). This provides a secret access token which must be copied from the Web UI panel and made available to the `galasactl` command line tool. The access token can be placed in the `GALASA_TOKEN` property in the `galasactl.properties` file, or the `GALASA_TOKEN` environment variable.
22
25
23
-
On a successful login, a `bearer-token.json` file is created in the Galasa home directory. This file contains a bearer token that galasactl uses to authenticate requests when communicating with a Galasa Ecosystem. If the bearer token expires, galasactl automatically attempts to re-authenticate with the Galasa Ecosystem using the properties in the `galasactl.properties` file within the Galasa home directory.
26
+
The `galasactl` tool will login implicitly when it needs to contact the remote Galasa service. Or the login state can be explicitly controlled using the `galasactl auth login` and `galasactl auth logout` commands.
24
27
28
+
On a successful login using the `galasactl` tool, the `GALASA_TOKEN` will be used to create a new temporary bearer token, which is stored in the `bearer-tokens` folder in the Galasa home directory. This file contains a bearer token that galasactl uses to authenticate requests when communicating with a Galasa Ecosystem. If the bearer token expires, galasactl automatically attempts to re-authenticate with the Galasa Ecosystem using the configured `GALASA_TOKEN`.
25
29
26
30
27
31
### Logging in to a Galasa Ecosystem using the auth login command
@@ -31,7 +35,7 @@ You can log in to a Galasa Ecosystem explicitly by using the `galasactl auth log
31
35
32
36
### Logging out of a Galasa Ecosystem using the auth logout command
33
37
34
-
To log out of a Galasa Ecosystem using galasactl, you can use the `galasactl auth logout` command. If you run a galasactl command that interacts with an Ecosystem while logged out, galasactl will attempt to automatically log in using the properties in your `galasactl.properties` file within your Galasa home directory.
38
+
To log out of a Galasa Ecosystem using galasactl, you can use the `galasactl auth logout` command. If you run a galasactl command that interacts with an Ecosystem while logged out, galasactl will attempt to automatically log again in using the configured `GALASA_TOKEN`.
35
39
36
40
37
41
### Listing personal access tokens
@@ -51,6 +55,21 @@ Total:2
51
55
52
56
The returned token list is sorted in creation date order, with the earliest creation date first. The description information matches the description that is provided by the user when creating a new access token from the Galasa Web UI.
53
57
58
+
You can also get tokens for a specific user
59
+
60
+
```
61
+
> galasactl auth tokens get --user m.smith@gmail.com
If you are unsure which user id you are currently using, you can find out with this command:
69
+
```
70
+
> galasactl users get --id me
71
+
id: m.smith@gmail.com
72
+
```
54
73
55
74
### Revoking personal access tokens
56
75
@@ -59,10 +78,20 @@ If a user moves to a new role, or loses a laptop with their personal access toke
59
78
You can retrieve a list of available personal access tokens that have been created, along with their token IDs, by running the `galasactl auth tokens get` command, as described in the previous section.
60
79
61
80
62
-
Run the following command to revoke a personal access token with the token ID `myId`:
81
+
Run the following command to revoke a personal access token with the token ID `myId` substituted for the numeric value visible from the `galasactl auth tokens get` command.
82
+
83
+
```
84
+
galasactl auth tokens delete --tokenid {myId}
85
+
```
63
86
87
+
For example:
64
88
```
65
-
galasactl auth tokens delete --tokenid myId
89
+
> galasactl auth tokens get --user m.smith@gmail.com
*Note:* The `galasactl auth tokens delete` command revokes personal access tokens that a user creates through the Galasa Web UI. When a user runs a CLI command that talks to the Ecosystem, the CLI uses the personal access token to get a JSON Web Token (JWT). A JWT is a separate, temporary token that identifies a user and is used in galasactl commands to talk to the API server. JWTs cannot be revoked, but they do expire, so a user can continue to run CLI commands after revoking their personal access token until their JWT expires. You can remove the JWT that is stored on a user's machine instead of having to wait for the JWT to expire, by running the `galasactl auth logout` command on that machine.
0 commit comments