Skip to content

sources.md

Latest commit

 

History

History
94 lines (72 loc) · 4.64 KB

sources.md

File metadata and controls

94 lines (72 loc) · 4.64 KB

Sources

Sources are the starting point of a connector. They contain the configuration for the source.

Sources can be of different types:

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:

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:

{
	"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:
    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:

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.

{
	"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\":\"me@company.com\",\"aud\":\"my_zgw_client\"}"
}