Documentation on how to get started technically (#351)

* Added first revision of Get Started guide

* Integrated Get Started guide in README.md

* Removed dead code

* Removed another reference to scope not in use

* Removed another reference to scope not in use

* Added links to get rid of TODO's

* Fixed typo

* Simplified

* Removed unsubstantiated claim

* Current revision/hope

* Landed on 'Contact Us'

* Fixed channel name

README.md

@@ -1,10 +1,17 @@
-# altinn-broker (work-in-progress)
-Formidlingstjenesten
+# Altinn Broker ("Formidlingstjenesten")
+
+Altinn Broker is a Managed File Transfer (MFT) service for secure file transfer between organizations in Norway. 
 
 [![Build and push](https://github.com/Altinn/altinn-broker/actions/workflows/build-and-push.yml/badge.svg)](https://github.com/Altinn/altinn-broker/actions/workflows/build-and-push.yml)
 
+## Getting started
+
+Altinn Broker is currently available in Altinn's staging environment at https://platform.tt02.altinn.no. In order to get started integrating to the API, follow our [guide on getting started](./docs/get-started.md).
+
 ## Postman
 
+<a id="postman"></a>
+
 Example requests using postman can be found in [altinn3-broker-postman-collection.json](/altinn3-broker-postman-collection.json). In order to use it, you need to [register a Maskinporten integration](https://sjolvbetjening.test.samarbeid.digdir.no/auth/login) with the scope "altinn:testtools/tokengenerator/enterprise" and use it to fill out the Postman variables "client_id", "client_kid" and "client_jwk". Also set the variable "serviceowner_orgnumber". After that, run all the requests in the folder Authenticator in order. This will authenticate you to to run all the other requests in the collection.
 
 The first time you start testing in an environment, you need to register a service owner in Broker so that we can provision the necessary storage resources for you. Use the "Register Service Owner" request in the Postman collection to do this. Make sure you have run the Authenticator/"Authenticate as service owner (tjeneste-eier)" request first. 
@@ -21,6 +28,8 @@ The services required to support local development are run using docker compose:
 To support features like hot reload etc, the app itself is run directly. Either in IDE like Visual Studio or by running:
 ```dotnet watch --project ./src/Altinn.Broker.API/Altinn.Broker.API.csproj```
 
+Installing Dotnet 8.0 is a pre-requisite.
+
 ### Azurite
 
 When running tests or when running locally, we use the Azurite storage emulator to emulate an Azure Storage account locally. You can use Azure Storage Explorer to inspect the blob contents.
@@ -30,14 +39,6 @@ When running tests or when running locally, we use the Azurite storage emulator
 The solution uses Flyway to run migrations. The migration scripts can be found in /src/Altinn.Broker.Persistence/Migrations. Script naming must follow the convention "V${four-digit-version-number}__${name}".
 If you need to re-initialize the database during local development, you can delete the database container and re-run docker compose.
 
-### Authorization
-
-To get access to the Broker API in staging/production, a consumer needs to use a Maskinporten integration. Recipients should use the scope altinn:broker.read and senders should use the scope altinn:broker.write. Tokens with both scopes also work. You can create a Maskinporten integration here:
-https://selvbetjening-samarbeid-ver2.difi.no/integrations
-
-For more on Maskinporten tokens see:
-https://docs.digdir.no/docs/Maskinporten/maskinporten_guide_apikonsument
-
 When running locally for development, you can use any Maskinporten token. It is not validated.
 
 ### Formatting

altinn3-broker-postman-collection.json

@@ -1328,7 +1328,7 @@
 						"method": "GET",
 						"header": [],
 						"url": {
-							"raw": "https://altinn-testtools-token-generator.azurewebsites.net/api/GetEnterpriseToken?env=tt02&scopes=altinn:broker.admin altinn:resourceregistry/resource.write altinn:authorization:pdp&org=ttd&orgNo={{serviceowner_orgnumber}}",
+							"raw": "https://altinn-testtools-token-generator.azurewebsites.net/api/GetEnterpriseToken?env=tt02&scopes=altinn:resourceregistry/resource.write altinn:authorization:pdp&org=ttd&orgNo={{serviceowner_orgnumber}}",
 							"protocol": "https",
 							"host": [
 								"altinn-testtools-token-generator",
@@ -1346,7 +1346,7 @@
 								},
 								{
 									"key": "scopes",
-									"value": "altinn:broker.admin altinn:resourceregistry/resource.write altinn:authorization:pdp"
+									"value": "altinn:resourceregistry/resource.write altinn:authorization:pdp"
 								},
 								{
 									"key": "org",

docs/get-started.md

@@ -0,0 +1,58 @@
+## Getting Started
+
+To understand how the Broker API operates, including its dependencies and configuration steps, refer to the information below:
+
+```mermaid
+sequenceDiagram
+    participant TE as TE/You
+    participant Maskinporten as Maskinporten
+    participant ResourceRegistry as Resource Registry
+    participant Events as Events
+    participant SBS as SBS/client
+    participant Broker as Broker
+    participant Authorization as Authorization
+
+    TE->>+Maskinporten: 1. Register clients
+    TE->>+ResourceRegistry: 2. Register resource with auth policy
+    TE->>+Events: 3. Set up event subscription
+    TE->>+SBS: Configure SBS/client
+    loop Each Broker request
+        SBS->>+Authorization: Get token (note: usually cached)
+        SBS->>+Broker: Initialize FileTransfer etc.
+        Broker->>+Authorization: Authorize request
+        Authorization->>+ResourceRegistry: Retrieve policy
+        Broker->>+Events: Publish event
+        Events->>-SBS: Push event/webhook
+    end
+```
+
+### 0. Get an API key
+
+In order to use Altinn API's, you need a subscription key for the API's. This is passed as the header "Ocp-Apim-Subscription-Key" in every request.
+You can get it by contacting us at [Altinn@Slack#produkt-formidling](https://join.slack.com/t/altinn/shared_invite/zt-7c77c9si-ZnMFwGNtab1aFdC6H_vwog).
+
+### 1. Register Maskinporten Clients
+Register Maskinporten clients to authenticate with the Broker API, assigning them relevant scopes:
+- `altinn:authorization:pdp` - Required for all broker API clients for authorization access.
+- `altinn:broker.sender` - For clients sending files.
+- `altinn:broker.reader` - For clients receiving files.
+
+Use [Samarbeidsportalen self-service](https://sjolvbetjening.test.samarbeid.digdir.no/) for registration. [Here's a detailed guide](https://docs.digdir.no/docs/Maskinporten/maskinporten_sjolvbetjening_web#selvbetjening-som-api-konsument).
+
+### 2. Register a Resource
+All files sent using Broker is associated with a resource/service/"tjenesteressurs". These are registered in Altinn Studio, and are used for access rules and access lists.
+Your access rules must be configured in such a way that that they permit the actions "publish" (for all), "read" (for recipients) and "write" (for senders). 
+
+To setup a resource that works quickly, you can use our Postman collection and run the requests "Create resource" and "Create resource policy". See an example policy in .xml format in Test/Altinn.Broker.Tests/Data/BasePolicy.xml. Note that this policy will authorize neither on access lists nor on system user, and is essentially open for use by anyone with access to the Broker API in general.
+
+Alternatively, you can use the GUI in Altinn Studio. 
+
+**TIP**: Verify your configurations from steps 1 and 2 using the [Postman collection](../README.md#postman), substituting the test tokens with your own Altinn tokens (See "Login to Maskinporten (Initialize)" request in Authenticator folder).
+
+### 3. Set Up Event Subscriptions
+In order to use events/webhooks for a broker resource, you need to setup a subscription for the given resource. This subscription is used to configure the endpoint where the events published by broker end up. [You can read more about how to setup an Events subscription in Altinn Events here](https://docs.altinn.studio/events/subscribe-to-events/developer-guides/setup-subscription/).
+
+### 4. Integrate with the Broker API
+Authenticate using the Maskinporten integration from step 1 to [obtain a Maskinporten token](https://docs.digdir.no/docs/Maskinporten/maskinporten_protocol_token), then acquire an Altinn Token from [Altinn Authentication](https://docs.altinn.studio/authentication/architecture/accesstoken/). Use the Altinn Token as a Bearer token for all Broker API requests along with the APIM subscription key as a header with the key "Ocp-Apim-Subscription-Key".
+
+First-time service owners who want to use Broker need to provision their Altinn Broker-managed cloud infrastructure via POST on /serviceowner with an Altinn Token (see [Postman collection](../altinn-broker-v1.json)). The infrastructure should be operational within a couple of minutes.

src/Altinn.Broker.API/Helpers/MaskinportenHelper.cs

@@ -44,5 +44,4 @@ public static class MaskinportenHelper
 
     public const string WriteScope = "altinn:broker.write";
     public const string ReadScope = "altinn:broker.read";
-    public const string AdminScope = "altinn:broker.admin";
 }

src/Altinn.Broker.Persistence/Repositories/FileTransferRepository.cs

@@ -186,7 +186,6 @@ public async Task<Guid> AddFileTransfer(ServiceOwnerEntity serviceOwner, Resourc
         command.Parameters.AddWithValue("@fileTransferSize", fileTransferSize is null ? DBNull.Value : fileTransferSize);
         command.Parameters.AddWithValue("@senderActorId", actorId);
         command.Parameters.AddWithValue("@externalFileTransferReference", sendersFileTransferReference);
-        command.Parameters.AddWithValue("@fileTransferStatusId", (int)FileTransferStatus.Initialized); // TODO, remove?
         command.Parameters.AddWithValue("@created", DateTime.UtcNow);
         command.Parameters.AddWithValue("@storageProviderId", serviceOwner.StorageProvider.Id);
         command.Parameters.AddWithValue("@hangfireJobId", hangfireJobId is null ? DBNull.Value : hangfireJobId);