| Table of Contents |
|---|
This guide focuses on the OAuth2 authentication. It provides all information to configure an OAuth2 authentication for signer and for users. The first section focuses on the settings for the signer authentication and provides an overview of all configurations necessary to add a new provider. Please note that all information regarding the configuration of the provider for the signer authentication also apply for the user authentication.
...
| Code Block | ||||
|---|---|---|---|---|
| ||||
{
"SspFileIds": [
"##FileId##"
],
"SendEnvelopeDescription": {
"Name": "test",
"EmailSubject": "Please sign the enclosed envelope",
"EmailBody": "Dear #RecipientFirstName# #RecipientLastName#\n\n#PersonalMessage#\n\nPlease sign the envelope #EnvelopeName#\n\nEnvelope 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.
| 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".
}
} |
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