nais · veiset · Mar 15, 2024 · Mar 16, 2024 · Mar 18, 2024 · Mar 20, 2024
diff --git a/.github/workflows/dependabot-auto-merge.yml b/.github/workflows/dependabot-auto-merge.yml
@@ -12,7 +12,7 @@ jobs:
     steps:
       - name: Dependabot metadata
         id: metadata
-        uses: dependabot/fetch-metadata@v1.6.0
+        uses: dependabot/fetch-metadata@v2.1.0
         with:
           github-token: "${{ secrets.GITHUB_TOKEN }}"
       - name: Enable auto-merge for Dependabot PRs

diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml
@@ -1,10 +1,5 @@
 name: Build and publish doc
-
-on:
-  push:
-    branches: 
-      - main
-
+on: push
 jobs:
   build:
     runs-on: ubuntu-latest
@@ -42,6 +37,7 @@ jobs:
           ./build.sh nav ssb ci-nais dev-nais tenant
 
   publish:
+    if: github.ref == 'refs/heads/main'
     needs: build
     runs-on: ubuntu-latest
     strategy:
@@ -65,7 +61,7 @@ jobs:
           key: ${{ github.sha }}
 
       - name: Sync documentation to bucket
-        uses: actions-hub/gcloud@466.0.0
+        uses: actions-hub/gcloud@474.0.0
         env:
           PROJECT_ID: not-used
           APPLICATION_CREDENTIALS: ${{ secrets.NAIS_DOC_SA }}
@@ -74,7 +70,7 @@ jobs:
           cli: gsutil
 
       - name: Invalidate cache
-        uses: actions-hub/gcloud@466.0.0
+        uses: actions-hub/gcloud@474.0.0
         env:
           PROJECT_ID: not-used
           APPLICATION_CREDENTIALS: ${{ secrets.NAIS_DOC_SA }}

diff --git a/build.sh b/build.sh
@@ -1,16 +1,17 @@
 #! /bin/bash
+set -e
 
 rm -rf ./out ./docs-base
 mkdir -p ./out ./docs-base
 
 # Copy documentation to base folder as we need to use docs as a staging folder
-cp -r ./docs/* ./docs-base
+cp -ra ./docs/. ./docs-base/
 
-for TENANT in $@; 
-  do 
+for TENANT in $@;
+  do
     rm -rf ./docs
-    cp -r ./docs-base ./docs
-    cp -rf ./tenants/$TENANT/* ./docs
-    TENANT=$TENANT poetry run mkdocs build --no-strict -d out/$TENANT
+    cp -ra ./docs-base/. ./docs/
+    cp -rf ./tenants/$TENANT/* ./docs || true
+    TENANT=$TENANT poetry run mkdocs build --strict -d out/$TENANT
   done
 
diff --git a/docs/.pages b/docs/.pages
@@ -0,0 +1,17 @@
+nav:
+- Home: README.md
+- explanations
+- tutorials
+- "": ""
+- workloads
+- build
+- auth
+- observability
+- persistence
+- security
+- Other services: services
+- "": ""
+- operate
+- "": ""
+- tags.md
+- ...
diff --git a/docs/README.md b/docs/README.md
@@ -1,58 +1,48 @@
 ---
+title: NAIS Developer Documentation
 hide:
   - feedback
   - footer
+  - toc
 ---
-
-<style> // hides the edit button on the start-page
-  .md-typeset h1,
+<!-- This hides the edit button on the start page -->
+<style>
   .md-content__button {
     display: none;
   }
 </style>
 
-# NAIS Documentation
+# :wave: **Welcome to the NAIS developer documentation!**
 
-<div class="grid cards" markdown>
--   :seedling: **Getting Started?**
+Here you'll find _explanations_[^1], _how-to guides_[^2], and _references_[^3] for all things NAIS.
 
-    ---
-    - Initially it's a good idea to learn about [what NAIS is](./explanation/nais.md) to get an idea of the fundamentals.
-    - Once you're familiar with the basic concepts, move on to the [Hello NAIS](./tutorial/hello-nais/hello-nais-1.md) tutorial to get your first app running.
+### :seedling: **New to NAIS?**
 
-</div>
+Start here to get an idea of the fundamentals.
 
 <div class="grid cards" markdown>
--   :rocket: **Tutorials**
-
-    ---
-
-    Learning-oriented lessons that take you through a series of steps to complete a project. Most useful when you want to get started with NAIS.
-
-    [:octicons-arrow-right-24: Tutorials](tutorial/README.md)
-
-- :dart: **How-to guides**
-
-    ---
 
-    Practical step-by-step guides to help you achieve a specific goal. Most useful when you're trying to get something done.
+- :ok_hand: [**What is NAIS?**](explanations/nais.md)
+- :student: [**Your first application; Hello NAIS**](tutorials/hello-nais.md)
 
-    [:octicons-arrow-right-24: How-to guides](how-to-guides/README.md)
-
-- :bulb: **Explanation**
-
-    ---
-
-    Big-picture explanations of higher-level concepts. Most useful when you want to understand how NAIS works.
-
-    [:octicons-arrow-right-24: Explanations](explanation/README.md)
+</div>
 
-- :computer: **Reference**
+### :technologist: **Already familiar with NAIS?**
 
-    ---
+What can we help you with today?
 
-    Reference documentation for the NAIS platform. Most useful when you need to look up details about a specific feature.
+<div class="grid cards" markdown>
 
-    [:octicons-arrow-right-24: Reference](reference/README.md)
+- :package: [**Run your code**](workloads/README.md)
+- :rocket: [**Build and deploy your code**](build/README.md)
+- :open_file_folder: [**Store your data**](persistence/README.md)
+- :closed_lock_with_key: [**Auth your users and workloads**](auth/README.md)
+- :telescope: [**Gain insight into your workloads**](observability/README.md)
+- :wrench: [**Manage your workloads and services**](operate/README.md)
+- :heavy_plus_sign: [**Explore the rest of NAIS**](services/README.md)
 
 </div>
+
+[^1]: :bulb: [_explanations_](tags.md#explanation) present higher-level concepts. Most useful when you want to understand how NAIS works.
+[^2]: :dart: [_how-to guides_](tags.md#how-to) help you achieve a specific goal. Most useful when you're trying to get something done.
+[^3]: :books: [_references_](tags.md#reference) contain technical descriptions and specifications. Most useful when you need to look up details about a specific feature.
diff --git a/docs/auth/.pages b/docs/auth/.pages
@@ -0,0 +1,5 @@
+nav:
+- README.md
+- 💡 Explanations: explanations
+- 📚 Reference: reference
+- ...
diff --git a/docs/auth/README.md b/docs/auth/README.md
@@ -0,0 +1,96 @@
+---
+tags: [auth, explanation]
+description: Services and addons to support authentication and authorization in your applications.
+---
+
+# Authentication and authorization
+
+NAIS helps your applications [log in users](#logging-in-users), [validate inbound requests](#validating-inbound-requests) and [make authenticated outbound requests](#making-outbound-requests) using the following identity providers:
+
+<div class="grid cards" markdown>
+
+- [**Azure AD**][Azure AD] (aka Entra ID)
+
+    For employees and internal services.
+
+- [**ID-porten**][ID-porten]
+
+    For Norwegian citizens.
+
+- [**TokenX**][TokenX]
+
+    For internal applications acting on-behalf-of ID-porten citizens.
+
+- [**Maskinporten**][Maskinporten]
+
+    For machine-to-machine communication between organizations or businesses.
+
+</div>
+
+Your application may have multiple use cases that can require a combination of services.
+
+See the different scenarios below to identify which service(s) you need for your application, and follow the links to the respective service for more details.
+
+## Logging in users
+
+Depending on who your users are, you can use the following services to log them in:
+
+:person_standing: Log in employees :octicons-arrow-right-24: [Azure AD](../security/auth/azure-ad/sidecar.md)
+
+:person_standing: Log in citizens :octicons-arrow-right-24: [ID-porten]
+
+## Validating inbound requests
+
+...from applications acting 
+
+```mermaid
+graph TD
+  B1[on-behalf-of]
+  B2[as themselves]
+
+  B1 --> |citizens| TokenX[<a href='../security/auth/tokenx'>TokenX</>]
+  B1 --> |employees| AAD_machine[<a href='../security/auth/azure-ad'>Azure AD</>]
+
+
+  B2 --> |internally| AAD_machine[<a href='../security/auth/azure-ad'>Azure AD</>]
+  B2 --> |externally| Maskinporten[<a href='../security/auth/maskinporten'>Maskinporten</a>]
+```
+
+The graph above can also be described as:
+
+:material-server::person_standing: Validate requests from application on behalf of employee :octicons-arrow-right-24: [Azure AD]
+
+:material-server::person_standing: Validate requests from application on behalf of citizen :octicons-arrow-right-24: [TokenX]
+
+:material-server: Validate requests from internal application :octicons-arrow-right-24: [Azure AD]
+
+:material-server: Validate requests from external application :octicons-arrow-right-24: [Maskinporten]
+
+## Making outbound requests
+
+```mermaid
+graph TD
+  B1[on-behalf-of]
+  B2[as application]
+
+  B1 --> |citizens| TokenX[<a href='../security/auth/tokenx'>TokenX</>]
+  B1 --> |employees| AAD_machine[<a href='../security/auth/azure-ad'>Azure AD</>]
+
+  B2 --> |internally| AAD_machine[<a href='../security/auth/azure-ad'>Azure AD</>]
+  B2 --> |externally| Maskinporten[<a href='../security/auth/maskinporten'>Maskinporten</a>]
+```
+
+The graph above can also be described as:
+
+:material-server::person_standing: Make requests on behalf of employee :octicons-arrow-right-24: [Azure AD]
+
+:material-server::person_standing: Make requests on behalf of citizen :octicons-arrow-right-24: [TokenX]
+
+:material-server: Make requests to internal API :octicons-arrow-right-24: [Azure AD]
+
+:material-server: Make requests to external API :octicons-arrow-right-24: [Maskinporten]
+
+[Azure AD]: ../security/auth/azure-ad/README.md
+[ID-porten]: idporten/README.md
+[TokenX]: tokenx/README.md
+[Maskinporten]: maskinporten/README.md
diff --git a/docs/security/auth/concepts.md → docs/auth/explanations/README.md b/docs/security/auth/concepts.md → docs/auth/explanations/README.md
@@ -1,4 +1,8 @@
-# Concepts
+---
+tags: [auth, explanation]
+---
+
+# Auth concepts
 
 This page describes basic concepts and glossary commonly referred to when working with authentication and authorization.
 
@@ -24,19 +28,19 @@ There are multiple ways of obtaining such a grant, depending on the use case:
 
 **Internal applications**
 
-- [Machine-to-machine with Azure AD](azure-ad/usage.md#oauth-20-client-credentials-grant)
+- [Machine-to-machine with Azure AD](../../security/auth/azure-ad/usage.md#oauth-20-client-credentials-grant)
 
 **Employee-facing applications**
 
-- [On-behalf-of an end-user with Azure AD](azure-ad/usage.md#oauth-20-on-behalf-of-grant)
+- [On-behalf-of an end-user with Azure AD](../../security/auth/azure-ad/usage.md#oauth-20-on-behalf-of-grant)
 
 **External applications**
 
-- [Machine-to-machine with Maskinporten](maskinporten/client.md)
+- [Machine-to-machine with Maskinporten](../maskinporten/README.md)
 
 **Citizen-facing applications**
 
-- [On-behalf-of an end-user with TokenX](tokenx.md)
+- [On-behalf-of an end-user with TokenX](../tokenx/README.md)
 
 ### OpenID Connect
 
@@ -45,8 +49,8 @@ It is used to authenticate end users.
 
 The platform provides opt-in sidecars that implement OpenID Connect:
 
-- [Sidecar for Azure AD](azure-ad/sidecar.md) (employee-facing applications)
-- [Sidecar for ID-porten](idporten.md) (citizen-facing applications)
+- [Sidecar for Azure AD](../../security/auth/azure-ad/sidecar.md) (employee-facing applications)
+- [Sidecar for ID-porten](../idporten/README.md) (citizen-facing applications)
 
 Due to the complexity involved in implementing and maintaining such clients, we recommend that your applications use
 these sidecars when possible.
@@ -68,10 +72,10 @@ Similar terms such as _authorization server_ (AS) or _OpenID provider_ (OP) are
 
 Providers that the platform supports provisioning for:
 
-- [Azure AD](azure-ad/README.md)
-- [ID-porten](idporten.md)
-- [Maskinporten](maskinporten/README.md)
-- [TokenX](tokenx.md)
+- [Azure AD](../../security/auth/azure-ad/README.md)
+- [ID-porten](../idporten/README.md)
+- [Maskinporten](../maskinporten/README.md)
+- [TokenX](../tokenx/README.md)
 
 #### Well-Known URL / Metadata Document
 
@@ -192,9 +196,9 @@ identifier is generally not considered to be confidential.
 The client ID for your client is injected at runtime as an environment variable.
 See the respective identity provider page for details:
 
-- [Azure AD](azure-ad/usage.md#runtime-variables-credentials)
-- [ID-porten](idporten.md#runtime-variables-credentials)
-- [TokenX](tokenx.md#runtime-variables-credentials)
+- [Azure AD](../../security/auth/azure-ad/usage.md#runtime-variables-credentials)
+- [ID-porten](../idporten/reference/README.md#runtime-variables-credentials)
+- [TokenX](../tokenx/README.md#runtime-variables-credentials)
 
 #### Client Authentication
 
@@ -424,7 +428,7 @@ Validation should always be performed before granting access to any [resource se
 Use well-known and widely used libraries and frameworks that take care of most
 of the heavy lifting for you.
 
-See [libraries and frameworks](development.md#libraries-and-frameworks) for a non-comprehensive list.
+See [libraries and frameworks](../reference/README.md#libraries-and-frameworks-for-validating-and-acquiring-tokens) for a non-comprehensive list.
 
 #### Signature Validation
 
@@ -465,10 +469,10 @@ Most libraries will have implementations to automatically validate these de fact
 
 See the individual identity provider pages for specific validation related to each provider:
 
-- [Azure AD](azure-ad/usage.md#token-validation)
-- [ID-porten](idporten.md#token-validation)
-- [Maskinporten](maskinporten/scopes.md#3-validate-tokens)
-- [TokenX](tokenx.md#token-validation)
+- [Azure AD](../../security/auth/azure-ad/usage.md#token-validation)
+- [ID-porten](../idporten/how-to/secure.md#validate-token-in-authorization-header)
+- [Maskinporten](../maskinporten/how-to/secure.md#validate-tokens)
+- [TokenX](../tokenx/README.md#token-validation)
 
 ---
 

diff --git a/docs/auth/idporten/.pages b/docs/auth/idporten/.pages
@@ -0,0 +1,6 @@
+title: ID-porten
+nav:
+- README.md
+- 🎯 How-To: how-to
+- 📚 Reference: reference
+- ...