Server configuration (settings.config)
- Corentin Humbert
Since the Synchronize API is in version 2, it now relies entirely on authentication tokens to authorize clients. In this case, JSON Web Tokens are used since it is a popular and well-adopted standard.
Version 2 also comes with the possibility to use X509 certificates for authentication. But, regardless whether basic authentication or certificate-based authentication is used, the underlying security layer relies on JSON Web Tokens.
The server/synchronization API can be configured through editing the settings.config file found under App_Data on the server.
<OfflineSynchronizationSettings>
<!-- Configure how the server issues API tokens -->
<ApiTokenSettings />
<!-- Configure allowed methods of authentication -->
<BasicAuthSettings />
<CertificateAuthSettings />
<OAuth2Settings />
</OfflineSynchronizationSettings>API Token settings
On the server, the API Token settings need to be configured. This is achieved in the settings.config file, and the following snippet needs to be added:
<ApiTokenSettings>
<Issuer>SigAnySync</Issuer>
<Audience>SigAnyClient</Audience>
<DurationInMinutes>15</DurationInMinutes>
<Secret>YOUR_SECRET_HERE</Secret>
</ApiTokenSettings>There are four important settings in <ApiTokenSettings>:
Issuer: The name for the entity which is responsible for issuing and validating tokens (unique name, ex: hostname)
Audience: Name of the entity by which the token is intended to be used. (unique name, ex: hostname)
DurationInMinutes: How long a token is considered valid. After it has expired, the client will need to authenticate again. This is done seamlessly in the background and requires no user interaction.
Secret: A Base64 randomly generated string. A length of 128 bytes is recommended. Make sure this is kept secret!
Authentication methods
At least one of the following authentication methods should be enabled to allow clients to use the API. You can enable multiple at the same time (even all of them!).
Using basic username/password
Allow users to authenticate using their username/password (from AssertDB)
<BasicAuthSettings enabled="true" />Using X.509 certificates
In case certificate-based authentication is intended to be used on the synchronization server, you will have to set up the server so that it is able to validate user certificates.
To do so, the server must add the Root Certificate Authority responsible for issuing user certificates to its list of trusted authorities:
Download the certificate of the Root CA. Either check with your certificate provider or get the service URLs from the user certificate.
Install the Root CA on the server. You will likely be asked where to install the certificate, make sure to choose Local Machine and NOT Current User (Reason: IIS has its own current user and will not see the certificate if installed in the user store). For the location, pick “Trusted Root Certificate Authorities”.
Double check that you got the right certificate and that you installed it at the right location
Using an external OAuth2 provider
Right now, the OAuth2 module on the Synchronization API assumes that the OAuth2 tokens provided to it have been signed using the RS256 signing algorithm.
You can also use OAuth2 tokens issued by known Identity Providers to exchange them against an API token. To do so, it is important to configure the Issuer and Audience to make sure they match whatever is in the OAuth2 token.
Finally, the JsonWebKeySetEndpoint (also known as JWKS) is a public endpoint which should return the set of public signing keys that the Identity Provider used to sign the OAuth2 tokens.
The actual URL may vary depending on the provider used (Azure, Ping, Google, etc.). To obtain this URL, please refer to the instructions of the corresponding Identity Provider.