Please note that the enhanced OAuth2 configuration which also allows a JWT configuration is available since:
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.
To configure the OAuth2 settings please open the "Identity Providers" section in the Settings.
OAuth settings for signer authentication
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.
Figure | Desciption |
---|---|
|
In this case we used the following Authorization Uri: https://demo.esignanywhere.net/Auth/Authorize and the following Token Uri: https://demo.esignanywhere.net/ApiToken/Retrieve.
The resource Uris are called for data, which will be stored in the audit trail. You can find more information about the audit trail in the section below.
JWT (JSON Web Token) configuration:
For more information about the JWT and OAuth please also see the following RFC:
- RFC 6749 (OAuth2 Autorization Framework)
- RFC 7519 (JWT)
- RFC 7515 (JWS)
- RFC 7517 (JWK)
You can either configure the JWT configuration or the Resource Uris.
For the JWT configuration you need the JWKS (JSON Web Key Set) Url the Issuer and you can define which dates should be validated. Per default all validations are disabled:
- Add 'nonce' parameter (to prevent replay attacks)
- Validate audience (the audience is the Client Id!)
- Validate issuer
- Validate lifetime
JWT sample:
The JWT specifies seven so called "claims" for example the "iss" for issuer, the "sub" for subject and more. Moreover the JWT typically consists of two parts, the type of the token (JWT) and the signing algorithmus.
For example:
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IlNpbW9uIFNlbGxlciIsImlzcyI6MTIzNDV9.##JWS-Signature##
The first two parts base64 decoded:
{"alg":"HS256","typ":"JWT"}.
{"sub":"1234567890","name":"Simon Seller","iss":12345}
Additionally you can add the Field property path. Afterwards, you can choose if you want to validate or update the data. Then you can choose the WorkstepData_Change (in this case the recipient email address was chosen). Please note that you can only validate, but not update the email address!
For the Resource Uris you just need the Resource Uri (in this case https://demo.esignanywhere.net/Api/v5.0/license)
Please note that all information about the license will then be shown in the audit trail. Find more information below.
After the configuration you can add the authentication for the signer on the designer page. Please see the next figure:
After enabling the authentication for the signer, the signer will see the following window appearing before signing:
After signing the envelope you can find all information regarding the authentication in the audit trail.
Because we used the following Uri: https://demo.esignanywhere.net/api/v5/license we can see all information about the license:
OAuth settings 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:
Note that the user must have the permission "User can use a password to logon". You can find this permission if you choose a user and click on the "Preview Permissions".
Please also see the following table which shows the correlation between UI and OAuth provider:
Web UI | OIDC JWT mapping configuration | Description |
---|---|---|
Recipient line: First Name | Recipient first name | To override the first name (given name). Will update the last name also for subsequent worksteps with same recipient mail address. |
Recipient line: Last Name | Recipient last name | To override the last name (family name). Will update the last name also for subsequent worksteps with same recipient mail address.
When provided via JWT, it is mapping to both “recipient last name” and “disposable certificate holder last name”. |
Recipient line: Email | Recipient email address |
|
Recipient line: Phone Nr | Recipient phonenumber | Phone number of the recipient. May be used to authenticate (also in subsequent worksteps), of for signature type “OtpSignature” if no other number is specified for OtpSignature in the recipient configuration. If no disposable certificate phone number is provided, the recipient phone number will also be used to access the disposable certificate. |
Disposable Certificate: Document Type | Current: Disposable Certificate document recognition type Note: Will be updated to Disposable Certificate document type |
|
Disposable Certificate: Document Number | Disposable Certificate document number | Alphanumeric; special characters allowed |
Disposable Certificate: Document Issued On | Disposable Certificate document issued on | The date when the document was issued. |
Disposable Certificate: Document Issued By | Disposable Certificate document issued by | The authority which issued the document, as it is written on the document. “Ministry of Immigration” |
Disposable Certificate: Document Expiry Date | Disposable Certificate document expiry date | The date when the document may expire – as printed on the document; if not printed on the document then as specified by law. |
Disposable Certificate: Identification Issuing Country | Disposable Certificate Identification Country |
|
Disposable Certificate: Identification Type | Disposable Certificate Identification Type |
|
Disposable Certificate: Identification Number | Disposable Certificate Identification Number | Alphanumeric; special characters allowed |
Disposable Certificate: Mobile Phone | Disposable Certificate Phonenumber | The phone number used for accessing the disposable certificate. An OTP will sent to the number via SMS. |
Disposable Certificate: Document Issuing Country | Will be available soon! | The document issuing country is requested when using “Lean Disposable Certificates” (which is recommended). |
Disposable Certificate: Country of Residence | Disposable Certificate Country of Residence | The country of residence is requested when NOT using “Lean Disposable Certificates” - DEPRECATED. |