Document authentication

docs/authentication.md

@@ -0,0 +1,88 @@
+# Authentication on sources
+
+In order to authenticate on other sources there are possibilities based upon the way the source expects autentication parameters.
+These parameters can be set in the source configuration. For example, if the source expects an API key in the headers, we can set the parameter `headers.Authorization` with the API key as value.
+
+Usually, sources tend to use dynamic authorization parameters in order to prevent the same authentication parameter from being used by adversaries that catch a call and deduce the parameter.
+
+At the moment, OpenConnector supports two dynamic authentication methods, OAuth and JWT Bearers.
+
+## OAuth
+
+To use OAuth we put in our Authorization header the following value: 
+```twig 
+Bearer {{ oauthToken(source) }}
+```
+This will impose an OAuth 2.0 access token after `Bearer` if the field `authenticationConfig` contains correct values.
+OpenConnector supports the OAuth 2.0 protocol with client credentials and password credentials as grant_types.
+
+>[!NOTE]
+> TODO: How to add authenticationConfig parameters in frontend
+
+When using OAuth, OpenConnector supports the following parameters:
+
+### Standard parameters
+* `grant_type`: The type of grant we have to use at the source. Supported are `client_credentials` and `password`
+* `scope`: The scope(s) needed to perform the requests we want to do in the API.
+* `tokenUrl`: The URL used to fetch the actual access token. Usually this url can be recognised by its path ending on `/oauth/token`
+* `authentication`: Location of the credentials, either `body` for credentials included in the request body, or `basic_auth` when the credentials have to be sent as a basic_auth header. 
+  > Only used when `grant_type` is `client_credentials`
+* `client_id`: The client id of the OAuth client  
+  > Only used when `grant_type` is `client_credentials`
+* `client_secret`: The secret for the OAuth client 
+  > Only used when `grant_type` is `client_credentials`
+* `username`: The username for the OAuth client 
+  > Only used when `grant_type` is `password`
+* `password`: The password for the OAuth client
+  > Only used when `grant_type` is `password`
+
+This results in the following example:
+```json
+{
+	"grant_type": "client_credentials",
+	"scope": "api",
+	"authentication": "body",
+	"tokenUrl": "https://example.com/oauth/token",
+	"client_id": "test-client",
+	"client_secret": "some secret value"
+}
+```
+### Custom parameters
+
+> [!WARNING] 
+> Custom parameters are currently in beta, it is not recommended to use them in production environments.
+
+At the moment, OpenConnector is tested with the following custom parameters:
+
+* `client_assertion_type`, only meaningful at the moment when value is set to `urn:ietf:params:oauth:client-assertion-type:jwt-bearer`. When this is set (for Microsoft authentications) the following fields are needed to generate the `client-assertion`-field
+  - `private_key`: The base64 encoded private key of the certificate uploaded to Microsoft.
+  - `x5t`: The base64 encoded sha1 fingerprint of the uploaded certificate, generated by running the following command:
+
+  ```bash 
+  echo $(openssl x509 -in certificate.crt -fingerprint -noout) | sed 's/SHA1 Fingerprint=//g' | sed 's/://g' | xxd -r -ps | base64`)
+  ```
+
+  - `payload`: The payload of the JWT generated as `client_assertion`, this can contain Twig variables to render, for example to set timestamps in the JWT payload.
+
+## JWT Bearer
+
+A second supported way of using dynamic authentication is setting a JWT Bearer. This means setting a header or query parameter with a JWT token.
+
+This can for example be used by setting an Authorization header with the following value:
+```twig 
+Bearer {{ jwtToken(source) }}
+```
+
+This will impose a JWT token after the bearer. For this, the `authenticationConfig` field of the source needs to contain the following fields:
+* `algorithm`: The algorithm that should be used to generate the JWT. Supported are `HS256`, `HS384` and `HS512` for HMAC algorithms, `RS256`, `RS384`, `RS512` and `PS256` for RSA algorithms.
+* `secret`: The secret used for the JWT. This can either be a HMAC shared secret, or a RSA private key in base64 encoding.
+* `payload`: The payload of your JWT, json_encoded.
+
+This results in the following example for the `authenticationConfig` parameter in i.e. an OpenZaak source.
+```json
+{
+	"algorithm": "HS256",
+	"secret": "YOUR_256BIT_(32BYTE)_HMAC_SECRET",
+	"payload": "{\"iss\":\"my_zgw_client\",\"iat\":{{ 'now'|date('U') }},\"client_id\":\"my_zgw_client\",\"user_id\":\"my_zgw_client\",\"user_representation\":\"[email protected]\",\"aud\":\"my_zgw_client\"}"
+}
+```