README.md 9.24 KB
Newer Older
Rostislav Vatolin [SLB]'s avatar
Rostislav Vatolin [SLB] committed
1
2
# entitlements-v2-azure

Rostislav Vatolin [SLB]'s avatar
Rostislav Vatolin [SLB] committed
3
4
entitlements-v2-azure is a [Spring Boot](https://spring.io/projects/spring-boot) service which hosts CRUD APIs that enable management of user entitlements.
Data kept in Azure cosmos graph database.
Rostislav Vatolin [SLB]'s avatar
Rostislav Vatolin [SLB] committed
5

6

Rostislav Vatolin [SLB]'s avatar
Rostislav Vatolin [SLB] committed
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
### Graph structure

`id` - auto-generated property <br/>
`appId` - a multi value property <br/>
`dataPartitionId` - a cosmos db partition key. It is a required property in all vertices in a graph.

Group vertex:

    {
        "id": "***"
        "nodeId": "users@opendes.domain.com",
        "name": "users",
        "description": "",
        "dataPartitionId": "opendes",
        "appId": "",
        "label": "GROUP"
    }

User vertex:

    {
        "id": "***",
        "nodeId": "user@test.com",
        "dataPartitionId": "test",
        "label": "USER"
    }
33
34
Parent edges point from group to group (in case a group is a member of another group)
or from a user to group (in case a user is a member of a group). <br/>
Rostislav Vatolin [SLB]'s avatar
Rostislav Vatolin [SLB] committed
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
Child edges point from group to group (in case a group is a member of another group)
or from a group to user (in case a user is a member of a group). <br/>
`role` - an edge property. Can be "OWNER" or "MEMBER". User can be "OWNER" or "MEMBER" of another group.
Group can be only a "MEMBER" of another group.

Child edge:

    {
        "id": "***",
        "label": "child",
        "type": "edge",
        "inVLabel": "USER",
        "outVLabel": "GROUP",
        "inV": "***",
        "outV": "***",
        "properties": {
            "role": "OWNER"
        }
    }
Rostislav Vatolin [SLB]'s avatar
Rostislav Vatolin [SLB] committed
54

55
56
57
58
59
60
61
62
63
64
65
66
Parent edge:

    {
        "id": "***",
        "label": "parent",
        "type": "edge",
        "inVLabel": "GROUP",
        "outVLabel": "USER",
        "inV": "***",
        "outV": "***"
    }

67

Rostislav Vatolin [SLB]'s avatar
Rostislav Vatolin [SLB] committed
68
69
70
71
72
73
74
75
76
### Requirements

In order to run this service locally, you will need the following:

- [Maven 3.6.0+](https://maven.apache.org/download.cgi)
- [AdoptOpenJDK8](https://adoptopenjdk.net/)
- Infrastructure dependencies, deployable through the relevant [infrastructure template](https://dev.azure.com/slb-des-ext-collaboration/open-data-ecosystem/_git/infrastructure-templates?path=%2Finfra&version=GBmaster&_a=contents)
- While not a strict dependency, example commands in this document use [bash](https://www.gnu.org/software/bash/)

77

Rostislav Vatolin [SLB]'s avatar
Rostislav Vatolin [SLB] committed
78
79
80
81
82
83
84
85
86
87
88
89
### General Tips

**Environment Variable Management**
The following tools make environment variable configuration simpler
 - [direnv](https://direnv.net/) - for a shell/terminal environment
 - [EnvFile](https://plugins.jetbrains.com/plugin/7861-envfile) - for [Intellij IDEA](https://www.jetbrains.com/idea/)

**Lombok**
This project uses [Lombok](https://projectlombok.org/) for code generation. You may need to configure your IDE to take advantage of this tool.
 - [Intellij configuration](https://projectlombok.org/setup/intellij)
 - [VSCode configuration](https://projectlombok.org/setup/vscode)

90

Rostislav Vatolin [SLB]'s avatar
Rostislav Vatolin [SLB] committed
91
92
### Environment Variables

93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
| name | value | description | sensitive? | source |
| ---  | ---   | ---         | ---        | ---    |
| `LOG_PREFIX` | `entitlements` | Logging prefix | no | - |
| `LOGGING_LEVEL` | `INFO` | Logging level | no | - |
| `partition_service_endpoint` |  ex `https://foo-partition.azurewebsites.net` | Partition Service API endpoint | no | output of infrastructure deployment |
| `aad_client_id` | `********` | AAD client application ID | yes | output of infrastructure deployment |
| `KEYVAULT_URI` | ex `https://foo-keyvault.vault.azure.net/` | URI of KeyVault that holds application secrets | no | output of infrastructure deployment |
| `appinsights_key` | `********` | API Key for App Insights | yes | output of infrastructure deployment |
| `AZURE_TENANT_ID` | `********` | AD tenant to authenticate users from | yes | keyvault secret: `$KEYVAULT_URI/secrets/app-dev-sp-tenant-id` |
| `AZURE_CLIENT_ID` | `********` | Identity to run the service locally. This enables access to Azure resources. You only need this if running locally | yes | keyvault secret: `$KEYVAULT_URI/secrets/app-dev-sp-username` |
| `AZURE_CLIENT_SECRET` | `********` | Secret for `$AZURE_CLIENT_ID` | yes | keyvault secret: `$KEYVAULT_URI/secrets/app-dev-sp-password` |
| `azure_istioauth_enabled` | `true` | Flag to Disable AAD auth | no | -- |
| `server_port` | ex `8080` | Port of the server | no | -- |
| `service_domain_name` | ex `contoso.com` | domain name of the service | yes | -- |
| `root_data_group_quota` | ex `5000` | Maximum number of parents a group users.data.root can have | no | -- |
108
| `redis_ttl_seconds` | ex `1` | The time to live in seconds for entitlements redis cache | no | -- |
109

110
In order to run the service locally, you will need to have defined environment variables that you can find [here](https://community.opengroup.org/osdu/platform/deployment-and-operations/infra-azure-provisioning/-/blob/master/tools/variables/entitlements.sh#L150).
Rostislav Vatolin [SLB]'s avatar
Rostislav Vatolin [SLB] committed
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134

**Note** The following command can be useful to pull secrets from keyvault:
```bash
az keyvault secret show --vault-name $KEY_VAULT_NAME --name $KEY_VAULT_SECRET_NAME --query value -otsv
```

### Build and run the application

After configuring your environment as specified above, you can follow these steps to build and run the application. These steps should be invoked from the *repository root.*

```bash
# build + test + install core service code
$ ./mvnw clean install

# run service
#
# Note: this assumes that the environment variables for running the service as outlined
#       above are already exported in your environment.
$ java -jar $(find provider/entitlements-v2-azure/target/ -name '*-spring-boot.jar')

# Alternately you can run using the Maven Task
$ ./mvnw spring-boot:run -pl provider/entitlements-v2-azure
```

135

Rostislav Vatolin [SLB]'s avatar
Rostislav Vatolin [SLB] committed
136
137
### Test the application

138
139
#### Using Cloud Infrastructure

140
1. Run Entitlements V2 service from Azure provider (assumed that all the required environment variables specified for using Cloud Infrastructure).
141
142

2. Define environment variables for integration tests (e.g. maven options):
143
[See this link](https://community.opengroup.org/osdu/platform/deployment-and-operations/infra-azure-provisioning/-/blob/master/tools/variables/entitlements.sh#L176)
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177

3. Run integration tests:

```bash
# build + install integration test core
$ ./mvnw compile -f testing/entitlements-v2-test-core

# build + run Azure integration tests.
$ ./mvnw test -f testing/entitlements-v2-test-azure
```

#### Using CosmosDB Emulator

1. Set up CosmosDB Emulator
    - Download [Azure Cosmos emulator](https://docs.microsoft.com/en-us/azure/cosmos-db/local-emulator?tabs=cli%2Cssl-netstd21#download-the-emulator) and save the program to your desktop
    - Navigate to the directory and start the emulator from command prompt. This should pop up the Emulator in localhost:8081
       ```
       Microsoft.Azure.Cosmos.Emulator.exe /EnableGremlinEndpoint
       ```
    - Go to Explorer tab and create a database `osdu-graph` and a collection `Entitlements`. For the partition key, use `/dataPartitionId`

2. Using this tool [Entitlements data uploader](https://community.opengroup.org/osdu/platform/deployment-and-operations/infra-azure-provisioning/-/tree/master/tools/test_data/entitlements_data_uploader), populate CosmosDB Emulator by required data for integration tests.

3. Temporarily hardcode in `provider/entitlements-v2-azure/src/main/resources/application.properties` the following properties:
    - `app.gremlin.port`=`8901`
    - `app.gremlin.sslEnabled`=`false`

4. Temporarily hardcode in `provider/entitlements-v2-azure/src/main/java/org/opengroup/osdu/entitlements/v2/azure/AzureAppProperties.java` the following methods so that they start returning such values:
    - `getGraphDbEndpoint()`=`localhost`
    - `getGraphDbPassword()`=`C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw==`

5. Run Entitlements V2 service from Azure provider.

6. Define environment variables for integration tests (e.g. maven options):
178
[See this link](https://community.opengroup.org/osdu/platform/deployment-and-operations/infra-azure-provisioning/-/blob/master/tools/variables/entitlements.sh#L176)
179
180

7. Run integration tests:
Rostislav Vatolin [SLB]'s avatar
Rostislav Vatolin [SLB] committed
181
182
183
184
185
186
187
188
189

```bash
# build + install integration test core
$ ./mvnw compile -f testing/entitlements-v2-test-core

# build + run Azure integration tests.
$ ./mvnw test -f testing/entitlements-v2-test-azure
```

190

Rostislav Vatolin [SLB]'s avatar
Rostislav Vatolin [SLB] committed
191
192
193
194
## Debugging

Jet Brains - the authors of Intellij IDEA, have written an [excellent guide](https://www.jetbrains.com/help/idea/debugging-your-first-java-application.html) on how to debug java programs.

195

Rostislav Vatolin [SLB]'s avatar
Rostislav Vatolin [SLB] committed
196
197
## Deploying the Service

198
Service deployments into Azure standardized to make the process the same for all services if using ADO and are
Rostislav Vatolin [SLB]'s avatar
Rostislav Vatolin [SLB] committed
199
200
201
202
closely related to the infrastructure deployed. The steps to deploy into Azure can be [found here](https://github.com/azure/osdu-infrastructure)

The default ADO pipeline is /devops/pipeline.yml

203

Rostislav Vatolin [SLB]'s avatar
Rostislav Vatolin [SLB] committed
204
205
206
207
208
209
210
211
212
213
214
215
216
217
## License
Copyright © Microsoft Corporation

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

[http://www.apache.org/licenses/LICENSE-2.0](http://www.apache.org/licenses/LICENSE-2.0)

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
218