auth: fix formatting and some typos

tronghn · tronghn · commit 0cc362d380c9 · 2024-05-31T09:17:33.000+02:00
diff --git a/docs/auth/entra-id/README.md b/docs/auth/entra-id/README.md
@@ -18,7 +18,7 @@ NAIS simplifies this by providing a [login proxy](../explanations/README.md#logi
 
 Your application is left with the responsibility to verify that inbound requests have valid [tokens](../explanations/README.md#tokens).
 
-:dart: Learn how to [log in employees with Entra ID](how-to/login.md).
+:dart: [**Learn how to log in employees**](how-to/login.md)
 
 ## Secure your API
 
@@ -27,7 +27,7 @@ Once configured, your consumers can acquire a token from Entra ID to [consume yo
 
 Your application code must verify inbound requests by validating the included tokens.
 
-:dart: Learn how to [secure your API with Entra ID](how-to/secure.md)
+:dart: [**Learn how to secure your API with Entra ID**](how-to/secure.md)
 
 ## Consume an API
 
@@ -50,7 +50,7 @@ graph LR
 
 The new token preserves the employee's identity context and is only valid for the specific API you want to access.
 
-:dart: Learn how to [consume an API on behalf of an employee](how-to/consume-obo.md)
+:dart: [**Learn how to consume an API on behalf of an employee**](how-to/consume-obo.md)
  
 ### Consume as application
 
@@ -65,4 +65,4 @@ graph LR
   Application --3. use token---> API["Other API"]
 ```
 
-:dart: Learn how to [consume an API as an application](how-to/consume-m2m.md)
+:dart: [**Learn how to consume an API as an application**](how-to/consume-m2m.md)
diff --git a/docs/auth/entra-id/how-to/consume-m2m.md b/docs/auth/entra-id/how-to/consume-m2m.md
@@ -2,7 +2,7 @@
 tags: [entra-id, azure-ad, how-to]
 ---
 
-# Consume internal API as an application using Entra ID
+# Consume internal API as an application
 
 This how-to guides you through the steps required to consume an API secured with [Entra ID](../README.md):
 
diff --git a/docs/auth/entra-id/how-to/consume-obo.md b/docs/auth/entra-id/how-to/consume-obo.md
@@ -2,7 +2,7 @@
 tags: [entra-id, azure-ad, how-to]
 ---
 
-# Consume internal API on behalf of an employee using Entra ID
+# Consume internal API on behalf of an employee
 
 This how-to guides you through the steps required to consume an API secured with [Entra ID](../README.md) on behalf of an employee:
 
diff --git a/docs/auth/entra-id/how-to/login.md b/docs/auth/entra-id/how-to/login.md
@@ -2,7 +2,7 @@
 tags: [entra-id, azure-ad, how-to]
 ---
 
-# Log in an employee with Entra ID
+# Log in an employee
 
 {%- if tenant() == "nav" %}
 !!! warning "Availability"
diff --git a/docs/auth/entra-id/how-to/secure.md b/docs/auth/entra-id/how-to/secure.md
@@ -22,29 +22,7 @@ Depending on who your consumers are, you must grant access to either application
 
 ### Applications
 
-By default, no applications have access to your API.
-You must explicitly grant access to consumer applications.
-
-```yaml title="app.yaml"
-spec:
-  accessPolicy:
-    inbound:
-      rules:
-        - application: app-a
-
-        - application: app-b
-          namespace: other-namespace
-
-        - application: app-c
-          namespace: other-namespace
-          cluster: other-cluster
-```
-
-The above configuration authorizes the following applications :
-
-* application `app-a` running in the same namespace and same cluster as your application
-* application `app-b` running in the namespace `other-namespace` in the same cluster
-* application `app-c` running in the namespace `other-namespace` in the cluster `other-cluster`
+{% include 'auth/entra-id/partials/app-access.md' %}
 
 ### Users
 
diff --git a/docs/auth/entra-id/partials/app-access.md b/docs/auth/entra-id/partials/app-access.md
@@ -0,0 +1,23 @@
+By default, no applications have access to your API.
+You must explicitly grant access to consumer applications.
+
+```yaml title="app.yaml" hl_lines="5-12"
+spec:
+  accessPolicy:
+    inbound:
+      rules:
+        - application: app-a
+
+        - application: app-b
+          namespace: other-namespace
+
+        - application: app-c
+          namespace: other-namespace
+          cluster: other-cluster
+```
+
+The above configuration authorizes the following applications:
+
+* application `app-a` running in the same namespace and same cluster as your application
+* application `app-b` running in the namespace `other-namespace` in the same cluster
+* application `app-c` running in the namespace `other-namespace` in the cluster `other-cluster`
diff --git a/docs/auth/entra-id/partials/user-access.md b/docs/auth/entra-id/partials/user-access.md
@@ -1,18 +1,6 @@
 By default, no users have access to your application.
 You must explicitly grant access to either [specific groups](#groups), [all users](#all-users), or both.
 
-#### All users
-
-The following configuration grants _all_ users access your application:
-
-```yaml hl_lines="5" title="app.yaml"
-spec:
-  azure:
-    application:
-      enabled: true
-      allowAllUsers: true
-```
-
 #### Groups
 
 The following configuration only grants users that are _direct_ members of the specified groups access to your application:
@@ -32,3 +20,15 @@ spec:
 
     Invalid [group identifiers](../explanations/README.md#group-identifier) are skipped and will not be granted access to your application.
     Ensure that they are correct and exist in Entra ID.
+
+#### All users
+
+The following configuration grants _all_ users access your application:
+
+```yaml hl_lines="5" title="app.yaml"
+spec:
+  azure:
+    application:
+      enabled: true
+      allowAllUsers: true
+```
diff --git a/docs/auth/entra-id/partials/validate.md b/docs/auth/entra-id/partials/validate.md
@@ -19,7 +19,7 @@ Validate that the `aud` claim is equal to the `AZURE_APP_CLIENT_ID` environment
 
 **Signature Validation**
 
-Validate that the token is signed with a ID-porten's public key published at the JWKS endpoint.
+Validate that the token is signed with a public key published at the JWKS endpoint.
 This endpoint URI can be found in one of two ways:
 
 1. the `AZURE_OPENID_CONFIG_JWKS_URI` environment variable, or
diff --git a/docs/auth/entra-id/reference/README.md b/docs/auth/entra-id/reference/README.md
@@ -6,6 +6,16 @@ tags: [entra-id, azure-ad, reference]
 
 ## Access policies
 
+### Applications
+
+{% include 'auth/entra-id/partials/app-access.md' %}
+
+### Users
+
+{% include 'auth/entra-id/partials/user-access.md' %}
+
+### Fine-grained permissions
+
 You may define custom permissions for your application in Entra ID and grant them to other consumer applications.
 Permissions will appear as _claims_ in the consumer's token.
 Your application can then use these claims to implement custom authorization logic.
@@ -21,7 +31,7 @@ Your application can then use these claims to implement custom authorization log
     2. The consumer has been granted a custom permission in your access policy definition.
     3. The target _audience_ is your application.
 
-### Custom scopes
+#### Custom scopes
 
 A _scope_ only applies to tokens acquired [on behalf of an employee][obo]
 (service-to-service calls on behalf of an end-user).
@@ -74,7 +84,7 @@ Scopes will appear as a _space separated string_ in the `scp` claim within the u
     }
     ```
 
-### Custom roles
+#### Custom roles
 
 A _role_ only applies to tokens acquired [as an application][m2m] (service-to-service calls).
 
@@ -128,28 +138,43 @@ Roles will appear in the `roles` claim as an _array of strings_ within the appli
 
 Notable claims in tokens from Entra ID:
 
-- `azp` (**authorized party**)
-    - The [client ID](../explanations/README.md#client-id) of the application that requested the token (this would be your consumer).
-- `azp_name` (**authorized party name**)
-    - The value of this claim is the (human-readable) [name](../explanations/README.md#client-name) of the consumer application that requested the token.
-- `groups` (**groups**)
-    - JSON array of [group identifiers](../explanations/README.md#group-identifier) that the user is a member of.
-    - Used to implement group-based authorization logic in your application.
-    - This claim only applies in flows where a user is involved i.e., either the [login] or [on-behalf-of][obo] flows.
-    - In order for a group to appear in the claim, all the following conditions must be true:
-        - The given user is a direct member of the group.
-        - The group has been [granted access to the application](../how-to/secure.md#users).
-- `idtyp` (**identity type**)
-    - This is a special claim used to determine whether a token is a [machine-to-machine][m2m] (app-only) token or a [on-behalf-of][obo] (user) token.
-    - The claim currently only appears in machine-to-machine tokens. The value is `app` when the token is a machine-to-machine token.
-    - In short: if the `idtyp` claim exists and it has the value `app`, then it is a machine-to-machine token. Otherwise, it is a user/on-behalf-of token.
+`azp` (**authorized party**)
+
+:   The [client ID](../explanations/README.md#client-id) of the application that requested the token (this would be your consumer).
+
+`azp_name` (**authorized party name**)
+
+:   The value of this claim is the (human-readable) [name](../explanations/README.md#client-name) of the consumer application that requested the token.
+
+`groups`
+
+:   JSON array of [group identifiers](../explanations/README.md#group-identifier) that the user is a member of.
+    Used to implement group-based authorization logic in your application.
+
+    This claim only applies in flows where a user is involved i.e., either the [login] or [on-behalf-of][obo] flows.
+    In order for a group to appear in the claim, all the following conditions must be true:
+
+    - The given user is a direct member of the group.
+    - The group has been [granted access to the application](../how-to/secure.md#users).
+
+`idtyp` (**identity type**)
+
+:   This is a special claim used to determine whether a token is a [machine-to-machine][m2m] (app-only) token or a [on-behalf-of][obo] (user) token.
+
+    Tokens are a machine-to-machine tokens only if this claim exists and has the value `app`.
+
 {%- if tenant() == "nav" %}
-- `NAVident` (**NAV ident**)
-    - The value of this claim maps to an internal identifier for the employees in NAV.
-    - This claim thus only applies in flows where a user is involved i.e., either the [login] or [on-behalf-of][obo] flows.
+
+`NAVident`
+
+:   The internal identifier for the employees in NAV.
+    Only applies in flows where a user is involved i.e., either the [login] or [on-behalf-of][obo] flows.
+
 {%- endif %}
-- `roles` (**roles**)
-    - The value of this claim is an _array of strings_ that lists the roles that the application has access to:
+
+`roles`
+
+:   The value of this claim is an _array of strings_ that lists the roles that the application has access to:
     ```json
     {
       "roles": [
@@ -159,19 +184,25 @@ Notable claims in tokens from Entra ID:
       ]
     }
     ```
-    - This claim **only** applies to [machine-to-machine][m2m] tokens.
-    - Consumers defined in the [access policy](../how-to/secure.md#applications) are always assigned the default role named `access_as_application`.
-    - You can optionally define and grant additional [custom roles](#custom-roles) to consumers.
-- `scp` (**scope**)
-    - The value of this claim is a _space-separated string_ that lists the scopes that the application has access to:
+
+    This claim **only** applies to [machine-to-machine][m2m] tokens.
+
+    Consumers defined in the [access policy](../how-to/secure.md#applications) are always assigned the default role named `access_as_application`.
+    You can optionally define and grant them [custom roles](#custom-roles).
+
+`scp` (**scope**)
+
+:   The value of this claim is a _space-separated string_ that lists the scopes that the application has access to:
     ```json
     {
        "scp": "defaultaccess scope1 scope2"
     }
     ```
-    - This claim **only** applies to user or [on-behalf-of][obo] tokens.
-    - Consumers defined in the [access policy](../how-to/secure.md#applications) are always assigned the default scope named `defaultaccess`.
-    - You can optionally define and grant additional [custom scopes](#custom-scopes) to consumers.
+
+    This claim **only** applies to user or [on-behalf-of][obo] tokens.
+
+    Consumers defined in the [access policy](../how-to/secure.md#applications) are always assigned the default scope named `defaultaccess`.
+    You can optionally define and grant them [custom scopes](#custom-scopes).
 
 For a complete list of claims, see the [Access Token Claims Reference in Entra ID](https://learn.microsoft.com/en-us/entra/identity-platform/access-token-claims-reference).
 We only use v2.0 tokens.
diff --git a/docs/auth/idporten/README.md b/docs/auth/idporten/README.md
@@ -17,4 +17,4 @@ NAIS simplifies this by providing a [login proxy](../explanations/README.md#logi
 
 Your application is left with the responsibility to verify that inbound requests have valid tokens.
 
-:dart: Learn how to [log in citizens with ID-porten](how-to/login.md).
+:dart: [**Learn how to log in citizens**](how-to/login.md)
diff --git a/docs/auth/idporten/how-to/login.md b/docs/auth/idporten/how-to/login.md
@@ -2,7 +2,7 @@
 tags: [idporten, how-to]
 ---
 
-# Log in a citizen with ID-porten
+# Log in a citizen
 
 This how-to guides you through the steps required to ensure that only citizens authenticated with [ID-porten](../README.md) can access your application. 
 
@@ -75,7 +75,7 @@ Validate that the `aud` claim is equal to the `IDPORTEN_AUDIENCE` environment va
 
 **Signature Validation**
 
-Validate that the token is signed with a ID-porten's public key published at the JWKS endpoint.
+Validate that the token is signed with a public key published at the JWKS endpoint.
 This endpoint URI can be found in one of two ways:
 
 1. the `IDPORTEN_JWKS_URI` environment variable, or
diff --git a/docs/auth/idporten/reference/README.md b/docs/auth/idporten/reference/README.md
@@ -8,10 +8,13 @@ tags: [idporten, reference]
 
 Notable claims in tokens from ID-porten:
 
-- `acr` (**Authentication Context Class Reference**)
-    - The [security level](#security-levels) used for authenticating the end-user.
-- `pid` (**personidentifikator**)
-    - The Norwegian national ID number (fødselsnummer/d-nummer) of the authenticated end user.
+`acr`
+
+:   The [security level](#security-levels) used when authenticating the end-user.
+
+`pid`
+
+:   "Personidentifikator". The Norwegian national ID number (fødselsnummer/d-nummer) of the authenticated end user.
 
 For a complete list of claims, see the [Access Token Reference in ID-porten](https://docs.digdir.no/docs/idporten/oidc/oidc_protocol_access_token#by-value--self-contained-access-token).
 
diff --git a/docs/auth/maskinporten/README.md b/docs/auth/maskinporten/README.md
@@ -22,7 +22,7 @@ graph LR
   Consumer --3. use token---> API["External API"]
 ```
 
-:dart: Learn how to [consume an external API using Maskinporten](how-to/consume.md)
+:dart: [**Learn how to consume an external API using Maskinporten**](how-to/consume.md)
 
 ## Secure your API
 
@@ -32,4 +32,4 @@ Once configured, your consumers can acquire a token from Maskinporten to [consum
 
 Your application code must verify inbound requests by validating the included tokens.
 
-:dart: Learn how to [secure your API with Maskinporten](how-to/secure.md)
+:dart: [**Learn how to secure your API with Maskinporten**](how-to/secure.md)
diff --git a/docs/auth/maskinporten/reference/README.md b/docs/auth/maskinporten/reference/README.md
diff --git a/docs/auth/tokenx/README.md b/docs/auth/tokenx/README.md
diff --git a/docs/auth/tokenx/how-to/consume.md b/docs/auth/tokenx/how-to/consume.md

Original file line number	Diff line number	Diff line change
`@@ -17,4 +17,4 @@ NAIS simplifies this by providing a [login proxy](../explanations/README.md#logi`
`17`	`17`
`18`	`18`	`Your application is left with the responsibility to verify that inbound requests have valid tokens.`
`19`	`19`
`20`		`-:dart: Learn how to [log in citizens with ID-porten](how-to/login.md).`
	`20`	`+:dart: [Learn how to log in citizens](how-to/login.md)`