...
On the first figure you can find the settings for the signer authentication. If you have configured and enabled the provider, you can then force the signer to authenticate before signing. For the signer authentication, we allow configuring 2 different options: an OAuth 2.0 Authorization Code flow (RFC 6749, Chapter 4.1) where one or several resource URIs are contacted to retrieve identification information, or the OpenID Connect (OIDC) compliant retrieval of a JWT token containing the identification data already. Choose the method offered by your identity provider.
| Figure | Desciption |
|---|---|
|
|
...
Beside using the resource URI to retrieve identification data, you could also use the resource URI to check (or document in the audit trail) e.g. product version information, in case such is provided. Below you find an example where a /license endpoint provides the product version information.
Data Mappings
For data retrieved from a resource uri, you can define data mappings. Data mappings allow the sender to define expected values, or when used for identification purpose to update recipient information with data provided by the OAuth 2.0 / OIDC identity provider. This can be e.g. in case of an eID provider a confirmed identity number.
...
You can set up custom data input fields for validation rules, which means the sender has to provide the expected value in a separate input field. Since eSAW 21.31 you can also use the predefined data fields to validate against (e.g. the recipient mail address, or certain disposable certificate holder information fields). For udpate-rules, of course only the update of predefined fields is available.
Please also see the following table which shows the correlation between the naming in the WebUI (recipient definition) and the OAuth 2.0 provider configuration:
...
OpenID Connect (OIDC) with JWT (JSON Web Token) 
| Info |
|---|
Please note the following: Some IDPs require the "openid" scope to provide necessary information. Therefore, please check the necessary scopes of your IDP if JWT validation is used. |
For more information about the JWT and OAuth please also see the following RFC:
...
Data mappings for data retrieved as claims of the JWT token work similar to the data mappings of the resource uri described above. Note that eSignAnyWhere up to (including) version 21.31 does NOT support addressing elements within complex data structures in the JWT.
Sending an Envelope with OAuth 2.0 / OIDC authentication
After the configuration you can add the authentication for the signer on the designer page. Please see the next figure:
Authenticating for a signer activity via OAuth 2.0 / OIDC
After enabling the authentication for the signer, the signer will see the following window appearing before signing:
Since eSignAnyWhere 21.40, the field value can reference to hierarchical data structures within the JWT. Therefore use the dot (.) separator to address different levels.
Example:
Assuming the JSON structure is:
| Code Block |
|---|
{
"person_data" : {
"given_name" : "John",
"family_name" : "Doe"
}
} |
Then, the given name can be accessed as
| Code Block |
|---|
person_data:given_name |
In case the JWT contains claims with a name that contains the dot (.) or colon (:), ensure to wrap the identifier within ['..']
Assuming the JSON structure is:
| Code Block |
|---|
{
"given_name" : "John",
"family_name" : "Doe",
"urn:pvpgvat:oidc.bpk" : "1234567+"
} |
Then, the bpk value can be accessed as
| Code Block |
|---|
['urn:pvpgvat:oidc.bpk'] |
Note that eSignAnyWhere up to (including) version 21.31 does NOT support addressing elements within complex data structures in the JWT. Therefore, in these releases you have to use the identifier of a flat structure, without ['..']
Sending an Envelope with OAuth 2.0 / OIDC authentication
After the configuration you can add the authentication for the signer on the designer page. Please see the next figure:
Authenticating for a signer activity via OAuth 2.0 / OIDC
After enabling the authentication for the signer, the signer will see the following window appearing before signing:
Instead of authenticating with eSAW, the different OAuth identification options Instead of authenticating with eSAW, the different OAuth identification options allowed for signer authentication will be presented to the signer. The signer can select the preferred one, and proceeds to the OAuth identity provider specific login page or signer identification procedure.
...
Because we added as a resource uri the license encpoint (https://demo.esignanywhere.net/api/v5/license), we can see all information about the license:
REST configuration
...
| Code Block | ||||
|---|---|---|---|---|
| ||||
{
"SspFileIds": [
"##FileId##"
],
"SendEnvelopeDescription": {
"Name": "test",
"EmailSubject": "Please sign the enclosed envelope",
"EmailBody": "Dear #RecipientFirstName# #RecipientLastName#\n\n#PersonalMessage#\n\nPlease
#PersonalMessage#
Please sign the envelope #EnvelopeName#\n\nEnvelope
Envelope will expire at #ExpirationDate#",
"DisplayedEmailSender": "",
"EnableReminders": true,
"FirstReminderDayAmount": 5,
"RecurrentReminderDayAmount": 3,
"BeforeExpirationDayAmount": 3,
"ExpirationInSecondsAfterSending": 2419200,
"CallbackUrl": "",
"StatusUpdateCallbackUrl": "",
"LockFormFieldsAtEnvelopeFinish": false,
"Steps": [
{
"OrderIndex": 1,
"Recipients": [
{
"Email": "##EMAIL##",
"FirstName": "##NAME##",
"LastName": "##NAME##",
"LanguageCode": "en",
"EmailBodyExtra": "",
"DisableEmail": false,
"AddAndroidAppLink": false,
"AddIosAppLink": false,
"AddWindowsAppLink": false,
"AllowDelegation": true,
"AllowAccessFinishedWorkstep": false,
"SkipExternalDataValidation": false,
"AuthenticationMethods": [
{
"Method": "CustomOAuthProvider",
"Parameter": "OAuthTest",
"Filters": [
{
"CompareOperation": "Equals",
"FilterId": "Email",
"FilterValue": "##EMAIL##"
}
]
}
],
"IdentificationMethods": []
}
],
"EmailBodyExtra": "",
"RecipientType": "Signer",
"WorkstepConfiguration": {
"WorkstepLabel": "test",
"SmallTextZoomFactorPercent": 100,
"FinishAction": {
"ServerActions": [],
"ClientActions": []
},
"ReceiverInformation": {
"UserInformation": {
"FirstName": "##NAME##",
"LastName": "##NAME##",
"EMail": "##EMAIL##"
},
"TransactionCodePushPluginData": []
},
"SenderInformation": {
"UserInformation": {
"FirstName": "##NAME##",
"LastName": "##NAME##",
"EMail": "##EMAIL##"
}
},
"TransactionCodeConfigurations": [],
"SignatureConfigurations": [],
"ViewerPreferences": {
"FinishWorkstepOnOpen": false,
"VisibleAreaOptions": {
"AllowedDomain": "",
"Enabled": false
}
},
"ResourceUris": {
"DelegationUri": "##DelegationUri##",
"SignatureImagesUri": "##SignatureImagesUri##"
},
"AuditingToolsConfiguration": {
"WriteAuditTrail": true
},
"Policy": {
"GeneralPolicies": {
"AllowSaveDocument": true,
"AllowSaveAuditTrail": true,
"AllowRotatingPages": false,
"AllowAppendFileToWorkstep": false,
"AllowAppendTaskToWorkstep": false,
"AllowEmailDocument": true,
"AllowPrintDocument": true,
"AllowFinishWorkstep": true,
"AllowRejectWorkstep": true,
"AllowRejectWorkstepDelegation": true,
"AllowUndoLastAction": true,
"AllowColorizePdfForms": false,
"AllowAdhocPdfAttachments": false,
"AllowAdhocSignatures": false,
"AllowAdhocStampings": false,
"AllowAdhocFreeHandAnnotations": false,
"AllowAdhocTypewriterAnnotations": false,
"AllowAdhocPictureAnnotations": false,
"AllowAdhocPdfPageAppending": false,
"AllowReloadOfFinishedWorkstep": true
},
"WorkstepTasks": {
"PictureAnnotationMinResolution": 0,
"PictureAnnotationMaxResolution": 0,
"PictureAnnotationColorDepth": "Color16M",
"SequenceMode": "NoSequenceEnforced",
"PositionUnits": "PdfUnits",
"ReferenceCorner": "Lower_Left",
"Tasks": [
{
"Texts": [
{
"Language": "en",
"Value": "Signature Disclosure Text"
},
{
"Language": "*",
"Value": "Signature Disclosure Text"
}
],
"Headings": [
{
"Language": "en",
"Value": "Signature Disclosure Subject"
},
{
"Language": "*",
"Value": "Signature Disclosure Subject"
}
],
"IsRequired": false,
"Id": "ra",
"DisplayName": "ra",
"DocRefNumber": 1,
"DiscriminatorType": "Agreements"
},
{
"PositionPage": 1,
"Position": {
"PositionX": 84.0,
"PositionY": 573.0
},
"Size": {
"Height": 80.0,
"Width": 190.0
},
"AdditionalParameters": [
{
"Key": "enabled",
"Value": "1"
},
{
"Key": "completed",
"Value": "0"
},
{
"Key": "req",
"Value": "1"
},
{
"Key": "fd",
"Value": ""
},
{
"Key": "fd_dateformat",
"Value": "dd-MM-yyyy HH:mm:ss"
},
{
"Key": "fd_timezone",
"Value": "datetimeutc"
}
],
"AllowedSignatureTypes": [
{
"AllowedCapturingMethod": "Click2Sign",
"Id": "98dd404c-1507-4162-b023-a23bb4ddec69",
"DiscriminatorType": "SigTypeClick2Sign",
"Preferred": false,
"StampImprintConfiguration": {
"DisplayExtraInformation": true,
"DisplayEmail": true,
"DisplayIp": true,
"DisplayName": true,
"DisplaySignatureDate": true,
"FontFamily": "Times New Roman",
"FontSize": 11.0,
"OverrideLegacyStampImprint": false,
"DisplayTransactionId": true,
"DisplayTransaktionToken": true,
"DisplayPhoneNumber": true
},
"SignaturePluginConfigurationId": "ltaLevelId"
}
],
"UseTimestamp": false,
"IsRequired": true,
"Id": "1#XyzmoDuplicateIdSeperator#Signature_f51586fa-e856-e06a-879d-0ffa11d9ee8c",
"DisplayName": "",
"DocRefNumber": 1,
"DiscriminatorType": "Signature"
}
]
},
"FinalizeActions": {
"FinalizeActionList": [
{
"DocRefNumbers": "*",
"SpcId": "ltaLevelId",
"DiscriminatorType": "Timestamp"
}
]
}
},
"Navigation": {
"HyperLinks": [],
"Links": [],
"LinkTargets": []
}
},
"DocumentOptions": [
{
"DocumentReference": "1",
"IsHidden": false
}
],
"UseDefaultAgreements": true
},
{
"OrderIndex": 2,
"Recipients": [
{
"Email": "##EMAIL##",
"FirstName": "##NAME##",
"LastName": "##NAME##",
"LanguageCode": "en",
"EmailBodyExtra": "",
"DisableEmail": false,
"AddAndroidAppLink": false,
"AddIosAppLink": false,
"AddWindowsAppLink": false,
"AllowDelegation": false,
"SkipExternalDataValidation": false,
"AuthenticationMethods": [],
"IdentificationMethods": []
}
],
"EmailBodyExtra": "",
"RecipientType": "Cc",
"DocumentOptions": [],
"UseDefaultAgreements": false
}
],
"AddFormFields": {
"Forms": {}
},
"OverrideFormFieldValues": {
"Forms": {}
},
"AttachSignedDocumentsToEnvelopeLog": false
}
} |
OAuth for user authentication
Before starting with the configuration please note that two new templates are available for OAuth2 authentication. You can find those templates in the section "Email Templates":
- OAuth user assignment invalidation information
- Initial OAuth verification request
For more information about the configuration please see the OAuth2 settings for signer authentication above. The settings for the user authentication are equal to settings of the signer authentication.
After configuration add the new provider to a user. You can either add the provider for users in the users setting or you can add the provider in the account setting. Please see the next two figures for more information:
When configuring a mapping, the user will get an email inviting him to bind his account to an OAuth identity provider. Once authenticated successfully, the user is linked to that identity. This step is required to avoid that someone with administrative permissions gets full control of another's account.
After setting up the OAuth2 binding, the user has to use the (readonly) Logon URL provided in the OAuth2 configuration.
If allowed in the instance configuration (_global.xml), the admin could even decide to add the OAuth login option on the main login page.
...
Note that the user, in case he has the permission "User can use a password to logon", could bypass the OAuth authentication. You can find this permission if you choose a user and click on the "Preview Permissions".
} |
OAuth for user authentication
Before starting with the configuration please note that two new templates are available for OAuth2 authentication. You can find those templates in the section "Email Templates":
- OAuth user assignment invalidation information
- Initial OAuth verification request
For more information about the configuration please see the OAuth2 settings for signer authentication above. The settings for the user authentication are equal to settings of the signer authentication.
After configuration add the new provider to a user. You can either add the provider for users in the users setting or you can add the provider in the account setting. Please see the next two figures for more information:
When configuring a mapping, the user will get an email inviting him to bind his account to an OAuth identity provider. Once authenticated successfully, the user is linked to that identity. This step is required to avoid that someone with administrative permissions gets full control of another's account.
After setting up the OAuth2 binding, the user has to use the (readonly) Logon URL provided in the OAuth2 configuration.
If allowed in the instance configuration (_global.xml), the admin could even decide to add the OAuth login option on the main login page.
| Info |
|---|
Note that the user, in case he has the permission "User can use a password to logon", could bypass the OAuth authentication. You can find this permission if you choose a user and click on the "Preview Permissions".
|
FAQ
After successful login in the external system, I am getting "The validation of the OAuth login could not be processed" with a OAuth User Authentication configuration. What am I doing wrong?
During login with an external OAuth Identity Provider, you are first redirected to the authorization (login) page of the external system which provides identification dataset via a resource endpoint, or which issues a JWT token with a signed response. The error shows that your configuration is not compatible with the external identity provider configuration. Therefore please verify your configuration and compare it against the manual of the OAuth Identity Provider. Please mind that also the error message in serverside application logs just indicates that "something in token retrieval was wrong", but will not be verbose about potential causes. The serverside log message "<TOKEN_FETCH_CALL_FAILED - Failed to fetch OAuth access token" could indicate reasons such as:
- Token URI is invalid
- JWKS URI is invalid and therefore a retrieved JWT cannot be verified
- Other verifications on JWT level, such as token validity, are not fulfilled
...