/
OAuth2 Authentication Samples

OAuth2 Authentication Samples

11 Dec 2024

OAuth2 enables you to configure an external authentication method, such as LinkedIn or Facebook. In this section you find how to configure them.

The signer will see an additional external authentication option. A pop-up appears, where the signer has to enter his credentials to authenticate. eSignAnyWhere will receive a temporary token to receive some authentication information, which will be stored in the audit log of the envelope. You can integrate any external OAuth 2.0 service. For example the open source project OAuthServer (https://oauthserver.codeplex.com/) would enable you to connect your AD/LDAP via OAuth 2.0 and eSignAnyWhere, or you can implement your own OAuth 2.0 service.

The following chapters show, based on examples, how to configure OAuth2 authentication. Because some of these examples are based on external services, the procedure may change by time. They should show you the basic concept tow to configure OAuth2. Note: To force a specific user and configure validation rules, the OAuth2 provider must return a JWT token or offer a resource uri that provides user data in JSON format (e.g. an OIDC /userinfo endpoint)!



Samples of OAuth 2.0 Signer Authentication

Authenticate with LinkedIn

Step 1: Create a new LinkedIn App

Go to https://developer.linkedin.com/ and create a new LinkedIn App. You have to enter a name (e.g. “my-eSAW-Authenticator”, a description, URL and some additional information). Once you have created your LinkedIn App you have to finish the configuration.

Step 2: Configure LinkedIn App

In your LinkedIn App you will find your (secret) client-id and client-secret, and the available scopes (e.g. r_basicprofile r_emailaddress). It is important to separate the scopes with space ” “.

You have to add a OAuth 2.0 forwarding URL. The URL for eSignAnyWhere is https://www.significant.com/esawviewer/HttpHandlers/AuthHandler.ashx.

Step 3: Configure eSignAnyWhere

Open the Settings > Organization page and add a new OAuth 2.0 provider. Enter the LinkedIn credentials as below (see LinkedIn documentation for current configuration!). The Identifier is your unique identifier for using with API. The ressources URIs are called for data, which will be stored in the audit-log.

Client ID:

your Linked Client ID

Client Secret:

your LinkedIn Client Secret

Scope:

r_basicprofile r_emailaddress

Authorization URI:

https://www.linkedin.com/oauth/v2/authorization

Token URI:

https://www.linkedin.com/oauth/v2/accessToken

Logout URI:

https://www.linkedin.com

Ressource Parameter:

oauth2_access_token

Ressource URI:

https://api.linkedin.com/v1/people/~:(id,firstName,lastName,headline,email-address)?format=json

OAuth LinkedIn

Authenticate with Facebook

Step 1: Create a new Facebook App

Go to Facebook Developer, login and create a new Facebook App. You have to enter your App Name (e.g. “my-eSAW-Authenticator”), a contact email-address and a category.

Step 2: Configure your Facebook App

In your Facebook App dashboard and subpages you will find the API ID (similar to Client Token) and the App Secret (similar to Client Secret). You have to add a Facebook Login product to your app (OAuth2). In the settings page of your Facebook Login you can configure the OAuth Redirect URI (https://www.significant.com/esawviewer/HttpHandlers/AuthHandler.ashx).

For the scope you will need to add permissions, which can be found here. For this example we are using the following permissions: public_profile email user_about_me. It is important to separate the scopes with space ” “.

Step 3: Configure eSignAnyWhere

Open the Settings > Organization page and add a new OAuth 2.0 provider. Enter the Facebook credentials as below (see Facebook documentation for current configuration!). The Identifier is your unique identifier for using with API. The ressources URIs are called for data, which will be stored in the audit-log (see Facebook documentation).

Client ID:

your Facebook App ID

Client Secret:

your Facebook App Secret

Scope:

public_profile email user_about_me

Authorization URI:

https://www.facebook.com/v2.8/dialog/oauth

Token URI:

https://graph.facebook.com/v2.8/oauth/access_token

Logout URI:

http://facebook.com

Ressource Parameter:

oauth_token

Ressource URI:

https://graph.facebook.com/v2.5/me?fields=id,name,first_name,middle_name,last_name,email,birthday

The configured Ressource URI returns a JSON object with the specified parameter. These parameters can be defined in the fields to force a specific LinkedIn user to authenticate (e.g. email address). HINT: to see what data is returned in the Ressource URI send yourself an envelope and have a look in the audit trail. It contains the returned object with its parameter. Note: Parameter in Ressource URI of LinkedIn is not the same in the result (email vs. emailAddress).



OAuth Facebook



The Ressource URI will return data of the profile. With the “Graph API Explorer” you can build and test your own profile requests. With the optional configuration of “Fields” you can define fields, which are checked for authentication. So you can force a specific user (e.g. identified via email, id or birthdate) to authenticate. Other users are not accepted.

{ "id": "5761459xxxxxx", "name": "Firstname Lastname", "first_name": "Firstname", "last_name": "Lastname", "email": "some@email.com", "birthday": "01/01/2000" }
Ressources

Facebook Developer: https://developers.facebook.com
Permissions: https://developers.facebook.com/docs/facebook-login/permissions/
Facebook API: https://developers.facebook.com/docs/graph-api/using-graph-api/

Authenticate with eSignAnyWhere

This configuration allows to authenticate with an eSignAnyWhere account. The authentication information will be added to the Audit Trail, as evidence that the signer was the intended one. Recommended for use cases where internal signers are invited to sign, and signature methods such as ClickToSign should be used.

Step 1: Create a new OAuth App in eSAW AdminWeb 

Only customers running their own On-Premise instance configure the OAuth Application (i.e. the authentication method on the identity provider side) themselves. On Private-SaaS and Shared-SaaS instances, ask Namirial staff to create this app on the OAuth identity provider side for your instance.

Contact us

Create a new app in eSAW. You can find the OAuth settings in the section OAUTH APPS. You can configure the app with the following settings:

  • Logo (optional)

  • Name

  • Description

  • Redirect Urls

    • The allow-list of redirect URIs depends on which external environments want to authenticate using eSignAnyWhere Login as authentication method.

    • When configuring Signer Authentication for eSignAnyWhere using the eSignAnyWhere OAuth Identity Provider, the URI is shown in the WebUI where you are configuring the authentication method (see Step 2, value "Redirect Url").
      When configuring WebUI User Authentication for eSignAnyWhere using the eSignAnyWhere OAuth Identity Provider (e.g. to log in using eSAW credentials from another instance), the URI is shown in the WebUI where you are configuring the authentication method (similar to step2, but in the section "User Authentication").

  • In the settings you can also find the Client id and the Client Secret which are both necessary in the next steps.

Step 2: Configure Signer Authentication using eSignAnyWhere

This configuration allows the sender of an envelope to define that the signer has to authenticate with an eSAW WebUI login before getting access to the document.

Open the Settings > Identity Providers page and add a new OAuth 2.0 provider. Enter the eSAW app credentials as below.

Client ID:

your linked Client ID

Client Secret:

your linked Client Secret

Scope:



Authorization URI:

https://<your-instance-url>/Auth/Authorize

Token URI:

https://<your-instance-url>/ApiToken/Retrieve

Logout URI:



Ressource Parameter:

oauth_token

Ressource URI:

https://<your-instance-url>/api/v5/user/me?fields=Email



The Ressource URI allows to define a validation rule, to ensure that the recipient himself performs the login (and not just any  account on that instance).
Therefore, configure a validation rule of the value "Email" (returned from the resource uri) against the recipient's email address. The resource Uri returns a JSON object with the specified parameter. These parameters can be defined in the fields to force a specific eSAW user to authenticate (e.g. email address).

Example response of the user/me endpoint, containing the data which can be used for data validation rules:

{ "Id": "39cbe455xxxxxx", "Email": "j.doe@example.com", "FirstName": "John", "LastName": "Doe", }



Please see the following figure for more information about the configuration in eSAW:

OAuth ESignAnyWhere

(Hint: in some older product versions, this settings had been located in Settings-Organization, section "OAuth Settings").



HINT: to see what data is returned in the Resource URI send yourself an envelope and have a look in the audit trail. It contains the returned object with its parameter.



The response of the resource URI will also be logged in the audit trail (which might be important in scenarios where you just enforce that someone performs the login, in case you do not validate for a specific user email).

If the user is not allowed to authenticate an error will appear.


If authentication was successful, the signer will be logged in and SAW Viewer will grant access to the document.
After a successful login, the granted access for the OAuth Application is shown in Settings->Api Tokens and Apps in the section Apps and Connectors:

 

For more information about the signing process in eSAW please also see the next video:

Force a specific user to authentication via API

You can force a specific user to authentication via checks in the authenticator (based e.g. on userid or email). Via API you configure the authentication with a “check”.

<authentications> <authentication> <!-- CustomAuthenticationProvider will be mapped to GenericOAuthProvider --> <method>CustomAuthenticationProvider</method> <parameter>nameofprovider</parameter> <checks> <check compareOperation="equals" fieldId="userprofile" value="a232656-6656-5665"></check> </checks> </authentication> <authentication> <method>CustomOAuthProvider</method> <parameter>nameofprovider</parameter> <checks> <check compareOperation="equals" fieldId="useremail" value="jordan@xyzmo.com"></check> <check compareOperation="equals" fieldId="userprofile" value="a232336-6656-5665"></check> </checks> </authentication> </authentications>

Samples of OAuth 2.0 Signer Identification

In this section, we are describing OAuth 2.0 based solutions for strong identification of signers, with technical possibilities to retrieve data (e.g. for issuance of a QEC). Please note that legal aspects and the allowance of its use in specific scenarios need to be checked in the Trust Service Provider's Operative Manual or contractual agreements.

Video Identification - Namirial LiveID+

The Namirial LiveID+ video identification can be inserted into identification processes using an OAuth 2.0 Authentication / Identification configuration. As LiveID+ is not offering an OAuth 2.0 endpoint itself, this is implemented in "LIP OAuth Wrapper". 

Step 1: Request to create an organization in LiveID+ configuration, and configure the required identification process

The underlying LiveID+ configuration needs to be done by Namirial staff.
As a result, you will get

  • an organization identifier in LiveId+

  • a process identifier

Step 2: Request registration of a new Application in LIP OAuth Wrapper

This needs to be done by Namirial staff. Please provide following information:

  • Request to create an OAuth application for the LIP OAuth Wrapper for a code grant flow with eSignAnyWhere. You need to receive, as result of the request, a client_id and client_secret.
    Note that the LIP OAuth Wrapper is an optional add-on to eSignAnyWhere and must therefore be installed on the eSAW instance as a precondition.

  • eSignAnyWhere redirect URI which needs to be whitelisted in the MyNamirial configuration

  • Provide your eSignAnyWhere organization's customization ID, and which LiveID+ organization and LiveID+ process should be linked with it

Step 3: Configure eSignAnyWhere

  1. Login to eSignAnyWhere with a user that has administrative permissions on your Organization.

  2. Open the Settings > Identity Providers page and add new OAuth Settings for Signer Authentication.

Provider Name

This name will be displayed in the Authentication dialog in SignAnyWhere Viewer, so make sure it identifies your organization.
e.g.: Video Ident with LiveId+

Redirect Url

This is already set and has to be white listed on LIP OAuthWrapper. We already provided this URL in the request in Step 2.

Client Id

your "Application (client) ID" from Step 2

Client Secret:

your secret's value from Step 2

Scope:



Authorization URI:

https://<your-esaw-instance>/OAuthWrapperLiveIdPlus/api/authorize

Token URI:

https://<your-esaw-instance>/OAuthWrapperLiveIdPlus/api/getToken

Logout URI:

can be blank

JWKS URI:

https://<your-esaw-instance>/OAuthWrapperLiveIdPlus/Jwk/getJwks

Issuer:

https://<your-esaw-instance>/OAuthWrapperLiveIdPlus

On-Off Sliders:

LiveId Validation



And then configure the following field mappings:

Field property path

Validate/Update

Data Field

Field property path

Validate/Update

Data Field

firstname

Update

Recipient First Name

lastname

Update

Recipient Last Name

identificationType

Update

Disposable Certificate identification type

recognitionType

Update

Disposable Certificate document type

identificationNumber

Update

Disposable Certificate identification number

phone

Update

Disposable Certificate phone number

eMail

Validate

Recipient Email

documentIssuingCountry

Update

Disposable Certificate document issuing country

documentIssuingOrganisation

Update

Disposable Certificate document issued by

documentNumber

Update

Disposable Certificate document number

documentIdentificationCountry

Update

Disposable Certificate identification country

documentIssueDate

Update

Disposable Certificate document issued on

documentExpiryDate

Update

Disposable Certificate document expiry date

(if you want to disallow proceeding with data corrected by the video identification agent, change additional mappings from "Update" to "Validate". But note that e.g. small deviations in the name might then disallow to proceed)


and then,

  1. Click on Update to save the configuration

  2. Click on the slider to enable the OAuth provider

Step 4: Send envelopes using the LiveID+ identification

When sending an envelope using eSignAnyWhere Web UI, select the identification provider in the Envelope Create wizard's Recipients Page. The identification provider is listed in the expandable area of the recipient's activity, accessible through the "lock" symbol (Identification methods are listed in a separate section directly below the Authentication methods)



Identify using SignD SmartIdent 

An alternative is to perform identification using the SmartIdent solution offered by SignD. It can be inserted into identification processes using an OAuth 2.0 Authentication / Identification configuration. 

Step 1: Obtain SmartIdent credentials

It will therefore necessary to mention the "OAuth Redirect URI" to SignD, to perform the necessary whitelisting. The URI can be seen in your eSAW Instance, Settings - Identity Providers, when creating a new Signer Authentication.
As a result, you will receive client_id and client_secret.

Step 2: Configure eSignAnyWhere

  1. Login to eSignAnyWhere with a user that has administrative permissions on your Organization.

  2. Open the Settings > Identity Providers page and add new OAuth Settings for Signer Authentication.

Provider Name

This name will be displayed in the Authentication dialog in SignAnyWhere Viewer, so make sure it identifies your organization.
e.g.: SmartIdent

Redirect Url

This is already set and has to be white listed on SignD side. We already provided this URL in the request in Step 1.

Client Id

your "Application (client) ID" from Step 1

Client Secret:

your secret's value from Step 1

Scope:

openid flat

Authorization URI:

https://openid.signd.id/v1/oauth/authorize

Token URI:

https://openid.signd.id/v1/oauth/token

Logout URI:

can be blank

JWKS URI:

https://openid.signd.id/.well-known/jwks.json

Issuer:

https://openid.signd.id

On-Off Sliders:

SmartIdent Validation



And then configure the following field mappings:

Field property path

Validate/Update

Data Field

Field property path

Validate/Update

Data Field

identification_individual_first_name

Update

Recipient First Name

identification_individual_last_name

Update

Recipient Last Name

identification_id_recognition_type

Update

Disposable Certificate document type

identification_id_type

Update

Disposable Certificate identification type

identification_id_number

Update

Disposable Certificate document number

identification_individual_mobile_number

Update

Disposable Certificate phone number

sub

Update

Disposable Certificate identification number

identification_id_issuing_country

Update

Disposable Certificate document issuing country

identification_id_expeditor

Update

Disposable Certificate document issued by

identification_id_issuing_country

Update

Disposable Certificate identification country

identification_id_issuing_date

Update

Disposable Certificate document issued on

identification_id_expiration_date

Update

Disposable Certificate document expiry date

(if you want to disallow proceeding with data corrected by the video identification agent, change additional mappings from "Update" to "Validate". But note that e.g. small deviations in the name might then disallow to proceed)


and then,

  1. Click on Update to save the configuration

  2. Click on the slider to enable the OAuth provider

Step 3: Send envelopes using SmartIdent identification

When sending an envelope using eSignAnyWhere Web UI, select the identification provider in the Envelope Create wizard's Recipients Page. The identification provider is listed in the expandable area of the recipient's activity, accessible through the "lock" symbol (Identification methods are listed in a separate section directly below the Authentication methods)

Identification using national eID implementations

Many eID implementations across EU are offering OAuth 2.0 based integration options.

ID Austria (Austria)

When talking about ID Austria, we have to distinguish 3 different environments which the Austrian government offers:

  • "E-ID Serviceprovider (Q)" environment, which is a test environment and therefore does not require complex accreditation process.

  • "E-ID Serviceprovider" environment, which is the production environment.

  • Early Adopters environment which was used as testing environment before E-ID Serviceprovider (Q) went online

Test Environment - USP Service "E-ID Serviceprovider (Q)"

Please also see the following documentation about ID Austria (German documentation only): https://eid.egiz.gv.at/anbindung/direkte-anbindung/anbindung-oidc/

Mind, that the test environment ("E-ID Serviceprovider (Q)") works just with test identities, not with your individual "Handysignatur" or "ID Austria". Read https://eid.egiz.gv.at/anbindung/testidentitaeten/ for more details.

Step 1: Create "Service Provider" in USP.GV.AT