1.1 OAuth 2.0

The OAuth configuration describes the information needed for one or more APIs how to do the OAuth. When an API is described in this OAuth configuration, it can be accessed in any configuration by HTTP APIs to add the access token to the request.

The access and refresh tokens are stored with AES encryption in the database. This requires setting the DefaultEncryptionKey for the GCL of the WTS. See Setting up the WTS (Appsettings WTS) for more information.

Note that only one OAuth configuration is used, if several are present in Wiser then this may cause undesired behavior.

Note that if a local configuration is used that requires an OAuth configuration it must also be local.

For developers: the OAuth configuration is loaded into the OAuthConfigurationModel.

Properties of the OAuthConfiguration object

Property name	Mandatory	Default value	Explanation
ConnectionString	yes	Null	The connection string used to retrieve and store OAuth information in the database.
LogSettings	no	LogSettings of MainService	The settings to be used for logging. If not given, the MainService settings will be taken over. See Log settings for more information.
OAuths	yes	Null	A collection of OAuth information that can be used by HTTP APIs. See section "Fields OAuth" for more information.

Properties of the OAuth object

Property name	Mandatory	Default value	Explanation
ApiName	yes	Null	The name of the API to header to in an HTTP API.
GrandType	No	OAuthGrantType.NotSet	The type of grand type is being used
Endpoint	yes	Null	The full URL of the endpoint on which authentication is to take place.
Username	yes	Null	The username to log in with.
Password	yes	Null	The password to log in with.
ExpireTimeOffset	no	5 minutes	An offset this is subtracted from the expire time to prevent the token was still valid when requested but has expired when requested.
LogSettings	no	LogSettings of OAuthConfiguration	The settings to be used for logging. If not given, the OAuthConfiguration settings will be taken over. See Log settings for more information.
FormKeyValues	no	Null	A collection of keys and values to pass additional information to the OAuth call. See section "Properties of the FormKeyValue object" for more information.
Jwt	no	Null	The settings for creating a JWT token that will be added to the form data. See section "Properties of the Jwt object" for more information.

Properties of the FormKeyValue object

Property name	Mandatory	Default value	Explanation
Key	yes	Null	The value for the key in the formdata.
Value	yes	Null	The value for the value in the formdata. The special value [{jwt_token}] can be used to use the token that is generated if the <Jwt> element is present.

Properties of the Jwt object

Property name	Mandatory	Default value	Explanation
ExpirationTime	no	600	The seconds that the generated JWT token will be valid for.
Issuer	yes	Null	The value of the issuer claim.
Subject	yes	Null	The value of the subject claim.
Audience	yes	Null	The value of the audience claim.
CertificateLocation	yes	Null	The location where the PKCS12 (PFX) certificate is located.
CertificatePassword	yes	Null	The password of the certificate.
Claims	no	Empty array	A collection of additional claims to add to the payload. See section "Properties of the Claim object" for more information.

Properties of the Claim object

Property name	Mandatory	Default value	Explanation
Name	yes	Null	The name of the claim.
Value	yes	Null	The value of the claim.
DataType	no	Null	The data type the value should be converted to, e.g.: "System.Boolean". Note that the "System." part is not required.

Grand types

We currently support a few types of grand types: PasswordCredentials - which make use of username/password to connect ClientCredentials - which make use of clientId/secret to connect

Others will generate a NotImplementedException

for more details on grand types please check: https://oauth.net/2/grant-types/

Example

An example of an OAuth configuration within which the Wiser API has been added.

<OAuthConfiguration>
    <OAuths>
        <OAuth>
            <ApiName>Wiser</ApiName>
            <Endpoint>https://api.wiser3.nl/connect/token</Endpoint>
            <Username>TestUser</Username>
            <Password>TestPassword</Password>
            
            <FormKeyValues>
                <FormKeyValue>
                    <Key>subDomain</Key>
                    <Value>test</Value>
                </FormKeyValue>
                
                <FormKeyValue>
                    <Key>client_id</Key>
                    <Value>wiser</Value>
                </FormKeyValue>
                
                <FormKeyValue>
                    <Key>client_secret</Key>
                    <Value>bJgzX2ek7pLUPc9t</Value>
                </FormKeyValue>
                
                <FormKeyValue>
                    <Key>isTestEnvironment</Key>
                    <Value>false</Value>
                </FormKeyValue>
            </FormKeyValues>
            <!-- The <Jwt> node is completely optional. -->
            <Jwt>
                <ExpirationTime>600</ExpirationTime>
                <Issuer>MyIssuer</Issuer>
                <Subject>MySubject</Subject>
                <Audience>MyAudience</Audience>
                <CertificateLocation>C:\Certificates\Certificate.pfx</CertificateLocation>
                <CertificatePassword>password</CertificatePassword>
                <Claims>
                    <Claim>
                        <Name>AnAdditionalClaim</Name>
                        <Value>true</Value>
                        <DataType>boolean</DataType>
                    </Claim>
                </Claims>
            </Jwt>
        </OAuth>
    </OAuths>
</OAuthConfiguration>

Example of using the OAuth settings in an action

An HTTP API that uses the Wiser OAuth settings to send the access token with the request in the header.

<HttpApi>
    <TimeId>1</TimeId>
    <Order>1</Order>
    <Url><![CDATA[https://api.wiser3.nl/api/v3/entity-types?onlyEntityTypesWithDisplayName=true]]></Url>
    <Method>Get</Method>
    <OAuth>Wiser</OAuth>
</HttpApi>