Skip to content
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.

Commit 1f8dab7

Browse files
committedNov 8, 2024·
Implemented client and updated README
1 parent efdd681 commit 1f8dab7

File tree

62 files changed

+259
-344
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

62 files changed

+259
-344
lines changed
 

‎.gitignore

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
/.env_oauth
1+
client/.env_oauth
22
/infra/terraform.tfvars
33
/.idea/.gitignore
44
/infra/.terraform.lock.hcl

‎README.md

Lines changed: 113 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -28,12 +28,60 @@ The file structure is as follows:
2828
![screenshot](images/terraform_tfvars.png)
2929

3030

31+
## Register server on Entra ID
32+
33+
Before deploying our server we need to create an app registration on Entra ID.
34+
35+
### Create a new app registration
36+
37+
Navigate to the **App registrations** blade and click on **New registration** button in the top left tab
38+
39+
![screenshot](images/azuread_app_registrations.png)
40+
41+
Choose a suitable name. Here I have chosen the name "Hvalfangst Server" as the registration will be utilized by an API we are to deploy to Azure Web Apps in the coming sections. The client which is to interact with our server resource will **NOT** be deployed. It will merely run locally. The fact that
42+
both the newly deployed server and the not-to-be-deployed local client are both Python APIs (using the FastAPI framework) may seem confusing, but this is just for demonstration purposes. We do not need to set up a redirect URI for our server as it merely validates token received in the authentication header of the client request
43+
and invoke services if the request has the necessary scopes. We will set the redirect URL for our client in later sections.
44+
45+
46+
![screenshot](images/azure_entra_id_register_hvalfangst_server_api.png)
47+
48+
Once the app registration has been created, store the application and tenant id for later use. We will make use of these when setting up the CI/CD pipeline - which deploys the server API to Azure Web Apps.
49+
50+
![screenshot](images/hvalfangst_server_api_app_registration.png)
51+
52+
53+
### Create Scope
54+
55+
We will now proceed to create scopes. Scopes are in essence fully customizable access right labels, meaning that you may are free to pick any name. It is, however common to conform to the following pattern: **{RESOURCE}.{ACCESS_LEVEL}**.
56+
Say that you have implemented a CRUD API in the domain of wines. Since the domain is wine, the prefix would naturally be **Wines**. Access levels **could** be **READ**, **WRITE** and **DELETE**.
57+
For instance, the scope **Wines.Read** grants you access to **read** wines - which in the API translates to the right to perform any **HTTP GET** requests, which commonly would be actions such as listing metadata of all wines or to get information about a specific wine.
58+
59+
Click on the **Add a scope** button under the **Expose an API** section, which is accessible from the **Expose an API** blade under **Manage**.
60+
61+
![screenshot](images/hvalfangst_server_api_expose_api.png)
62+
63+
Set the scope name to **Heroes.Read**. Clients with this scope may list and view heroes. As for consent, choose **Admins only**.
64+
For the remainder of fields you are free to choose whatever describes the scope.
65+
66+
![screenshot](images/hvalfangst_server_api_add_scope.png)
67+
68+
Repeat the above for scopes **Heroes.Write** and **Heroes.Delete**.
69+
70+
![screenshot](images/hvalfangst_server_api_all_scopes.png)
71+
72+
It goes without saying that the chosen scopes are just simple examples. Feel free to adapt as you see fit. It is important to mention that the newly created scopes
73+
are absolutely junk in and of itself. You **must** reference the scopes names exactly as defined in your [server code](server/security/auth.py) for it to have any effect.
74+
That is, you must implement logic in your endpoints which verifies the signature associated with the token derived from the auth header, ensure that the
75+
audience is the client id of the server app registration and that the scopes included in the decoded claims matches that of what is required for that specific endpoint.
76+
In order to [create heroes](server/services/hero_service.py) one must have the scope **Heroes.Create** as specified in the [router](server/routers/heroes.py).
77+
3178
## Set up CI/CD via Deployment Center
3279

33-
Now that we have our new Web App resource up and running on Azure, we may proceed to set up our means of deploying our code to the
34-
aforementioned Web App. We will do so by connecting our Web App to our GitHub repository. Azure Web Apps has the ability
80+
Now that we have provisioned necessary infrastructure and created an app registration for the server, we may proceed to create the pipeline used to deploy our code to Azure Web Apps.
81+
We will do so by integrating our Web App to our GitHub repository. Azure Web Apps has the ability
3582
to create a fully fledged CI/CD pipeline in the form of a GitHub Action Workflows script, which it commits on our behalf. As part of this pipeline a managed identify
36-
will be created in Azure in order to authenticate requests. Secrets will be automatically created and referenced in the CI/CD script by Azure.
83+
will be created in Azure in order to authenticate requests. Secrets will be automatically created and referenced in the CI/CD script by Azure. Once the
84+
pipeline script has been created, we must adapt it slightly for it to work. More on this later.
3785

3886
Click on the **Deployment Center** section under the **Deployment** blade. Choose GitHub as source and set the appropriate organization, repository and branch.
3987
For authentication keep it as is (user-assigned identity). Click on the **Save** button in the top left corner.
@@ -56,7 +104,17 @@ For the CI/CD workflow script to actually work, we have to make some adjustments
56104
which are located in their own directories. The autogenerated script assumes that the files are located in the root folder, which is not the case here.
57105
Thus, we need to change the script to reference files located under the server directory, as we are to deploy our server.
58106

59-
The final pipeline definition should look like [this](.github/workflows/main_hvalfangstlinuxwebapp.yml).
107+
We are storing configuration values for our API in a class named [AzureConfig](server/config/config.py). Notice how the values for fields **TENANT_ID**
108+
and **SERVER_CLIENT_ID** are retrieved from the runtime environment - which means that these environment variables must be set somehow. When running the
109+
API locally for sake of testing one should **NOT** hardcode the associated values due to the risk of accidentally committing to SCM. Instead, you should
110+
either set the environment values on your system or retrieve them from an .env file, which, naturally, **HAS** to be added your .gitignore.
111+
112+
Proceed to add two new GitHub Action secrets. These should be your tenant ID and the client ID associated with your newly created **Hvalfangst Server API** app registration.
113+
114+
![screenshot](images/github_actions_hvalfangst_secrets.png)
115+
116+
We now need to modify our GitHub Actions Workflow script to set the environment variables in our Azure Web App itself. We do so by the use of the az CLI
117+
command **az webapp config appsettings set** where the associated values are retrieved from our repository secrets we set above.
60118

61119
## Deploy API
62120

@@ -72,45 +130,83 @@ Navigate to the **Deployment Center** section of your Azure Web App. A new deplo
72130

73131
![screenshot](images/deployment_center_post_action.png)
74132

133+
Click on the **Environment variables** section of your Web App to ensure that the App setting environment variables **HVALFANGST_TENANT_ID** and **HVALFANGST_SERVER_CLIENT_ID**
134+
have been set. The environment variable **SCM_DO_BUILD_DURING_DEPLOYMENT** was set by our [Terraform script](infra/terraform.tf) when creating the Azure Web App. It instructs our container to
135+
build the virtual environment based on our [requirements](server/requirements.txt) file on deploy as opposed to utilizing some pre-built virtual environment that has been transmitted.
136+
137+
![screenshot](images/hvalfangstlinuxwebapp_environment_variables.png)
138+
75139
Now that we know that it deployed successfully it is finally time to access the API. Click on URI associated with **Default Domain**
76140

77141
![screenshot](images/overview_default_domain.png)
78142

79-
You will be prompted with the following default page, which indicates that the API is up and running.
143+
You will be prompted with the following index page, which indicates that the API is up and running.
80144

81145
![screenshot](images/firefox_api_home.png)
82146

147+
The index page is available for all users and as such is not protected by any token validation logic. What is protected by token validation logic is our [heroes route](server/routers/heroes.py).
148+
This route exposes 4 endpoints: "POST /heroes/", "GET /heroes/", "GET /heroes{hero_id}" and "DELETE /heroes/{hero_id}".
149+
Notice how one in each endpoint always start by awaiting a function called [authorize](server/security/auth.py), passing in a token and a scope.
150+
The scope names referenced in aforementioned function call are exactly what was defined earlier. Hence, my little
151+
rant about scopes in and of itself being useless unless there is logic in place to actually enforce
152+
required scopes. We will utilize our [local client](client/main.py) to make HTTP calls to the server we deployed in previous sections. But first we must register it on Entra ID
153+
and assign it the appropriate permissions so that the scopes contained in tokens received from the authorization server matches that of protected in the server code.
83154

84-
## Register API on Azure AD
85155

86-
Now that we have deployed our API to Azure Web Apps, we need to register it on Microsoft Entra ID.
156+
## Register client on Azure Entra ID
87157

88158
### Create a new app registration
89159

90-
Navigate to the **App registrations** blade and click on **New registration** button in the top left tab
160+
In order for our client to be abl
91161

92-
![screenshot](images/azuread_app_registrations.png)
162+
![screenshot](images/hvalfangst_api_client_app_reg.png)
93163

94-
![screenshot](images/azure_entra_id_register_hvalfangst_server_api.png)
164+
![screenshot](images/hvalfangst_client.png)
95165

96-
![screenshot](images/hvalfangst_server_api_app_registration.png)
166+
### Create Secret
97167

168+
![screenshot](images/hvalfangst_client_new_secret.png)
98169

99-
### Expose API
170+
![screenshot](images/hvalfangst_client_add_secret.png)
100171

172+
![screenshot](images/hvalfangst_client_secrets.png)
101173

102-
![screenshot](images/hvalfangst_server_api_expose_api.png)
174+
### Add Redirect URL
103175

176+
![screenshot](images/hvalfangst_client_authentication.png)
104177

105-
![screenshot](images/hvalfangst_server_api_add_scope.png)
178+
![screenshot](images/hvalfangst_client_api_configure_web.png)
106179

107-
![screenshot](images/hvalfangst_server_api_all_scopes.png)
180+
### Add API permissions
181+
182+
![screenshot](images/hvalfangst_client_api_permissions.png)
183+
184+
![screenshot](images/hvalfangst_client_request_permission_graph.png)
185+
186+
![screenshot](images/hvalfangst_client_api_permissions_graph_openid.png)
187+
188+
![screenshot](images/hvalfangst_client_api_permissions_hvalfangst_search.png)
189+
190+
191+
![screenshot](images/hvalfangst_client_api_permissions_hvalfangst_server_heroes_read.png)
192+
193+
![screenshot](images/hvalfangst_client_all_permissions_added.png)
194+
195+
![screenshot](images/hvalfangst_client_grant_admin_consent_prompt.png)
196+
197+
![screenshot](images/hvalfangst_client_permissions_granted_admin_consent_for.png)
108198

199+
### Create .env file
109200

201+
For the local client to work, one must create a file named ".env_oauth", which is to hold client and tenant id, secret and callback URI. This information
202+
may be retrieved from our Client App registration. If you forgot to copy the client secret to your clipboard you may create a new one and use that instead.
203+
The fields will be mapped to our [OAuthSettings](client/config/oauth.py) on startup and used when making calls to the authorization server in order to obtain tokens.
110204

205+
The final file should look as follows:
206+
![screenshot](images/env_oauth.png)
111207

112208

113-
## Running API
209+
## Running local Client API
114210
```bash
115-
python -m uvicorn app.main:app --reload
211+
sh client/run_client.sh
116212
```

0 commit comments

Comments
 (0)
Please sign in to comment.