OAuth2 Authentication Samples

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.

OAuth 2.0 (Azure AD)

Step 1: Register a new Application in your Azure AD

Link to Microsoft documentation: https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-register-app

1. Sign in to the Azure portal.

2. If you have access to multiple tenants, use the Directories + subscriptions filter  in the top menu to switch to the tenant in which you want to register the application.

3. Search for and select Azure Active Directory.

4. Under Manage, select App registrations > New registration.

5. Enter a display Name for your application (e.g. "my-eSAW-Authenticator").
   Users of your application might see the display name when they use the app, for example during sign-in.
   You can change the display name at any time and multiple app registrations can share the same name.

6. Specify who can use the application (e.g.: "Accounts in this organizational directory only")

7. Don't enter anything for Redirect URI (optional). You'll configure a redirect URI in the next section.

8. Select Register to complete the initial app registration.

When registration finishes, the Azure portal displays the app registration's Overview pane.

You need two details from that page that you should now copy for later usage:

• Application (client) ID
• Directory (tenant) ID

Step 2: Configure platform settings

1. In the Azure portal, in App registrations, select your application.

2. Under Manage, select Authentication.

3. Under Platform configurations, select Add a platform.

4. Under Configure platforms, select the tile "Web" to configure a web app.

5. Enter the following Redirect URI: https://<eSignAnyWhere URL>/Account/ValidateOAuth (e.g.: https://demo.esignanywhere.net/Account/ValidateOAuth)

6. Select Configure to complete the platform configuration.

7. Under Implicit grant and hybrid flows (still on the Authentication page) make sure "ID tokens (used for implicit and hyprid flows)" is enabled
8. Leave Allow public client flows disabled, this is not needed.
9. Click Save to complete the configuration

Step 3: Add a client secret

1. In the Azure portal, in App registrations, select your application.
2. Select Certificates & secrets > Client secrets > New client secret.
3. Add a description for your client secret.
4. Select an expiration for the secret or specify a custom lifetime.
   • Client secret lifetime is limited to two years (24 months) or less. You can't specify a custom lifetime longer than 24 months.
   • Microsoft recommends that you set an expiration value of less than 12 months.
5. Select Add.
6. Record the secret's value for use in eSignAnyWhere later on. This secret value is never displayed again after you leave this page.

(Optional) Step 4: OpenID Connect discovery document

Link to Microsoft documentation: https://docs.microsoft.com/en-us/azure/active-directory/develop/userinfo

This step is optional as Microsoft doesn't change it's OAuth configuration very often, but it's good to know where to find your OpenID Connect discovery document.
You need the Directory (tenant) ID from Step 1, then call the following URL (no authentication needed):

https://login.microsoftonline.com/<Directory (tenant) ID>/v2.0/.well-known/openid-configuration

For the eSignAnywhere configuration you need the following properties:

• token_endpoint

• authorization_endpoint

• userinfo_endpoint

Step 5: 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 User Authentication.

1. Click on Update to save the configuration
2. Click on the slider to enable the OAuth provider

Step 6: Add OAuth provider to existing users 

1. Login to eSignAnyWhere with a user that has administrative permissions on your Organization.
2. Open the Settings > Users page and edit the user you want to add the OAuth provider to
3. Under OAuth assignments click on the + icon and choose your previously created OAuth provider
4. The user will now get a validation email to finish the setup.

Step 7: Login to eSignAnyWhere using OAuth 2.0

The OAuth provider might not be visible on the login page, depending on the setting "Share on login page" in Step 5.
Use the "Direct access url" instead.

OAuth 2.0 (eID)

ID Austria

Step 1: Configure eSignAnyWhere

Open Settings > Identity Providers and add a new OAuth2 provider. Enter the ID Austria credentials as below.

Please also see the next figures for the OAuth2 configuration and the JWT configuration:

Please note that the disposable certificate identification number will be updated with this configuration. If you want to override the identification number as it is shown in the configuration please also make sure to add a disposable certificate for the signer.

OAuth 2.0  (LinkedIn)

Step 1: Create a new LinkedIn App

Go to your LinkedIn Account 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.

Ressources

LinkedIn and OAuth2: https://developer.linkedin.com/docs/oauth2

OAuth 2.0 (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).

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).

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/

OAuth 2.0 (eSAW)

Step 1: Create a new App

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
• Name
• Description
• Redirect Urls
• 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 eSignAnyWhere

Open the Settings > Organization page and add a new OAuth 2.0 provider. Enter the eSAW app credentials as below. Please see the following figure for more information about the configuration in eSAW:

We recommend to configure Resource Uris. If you configure a resource Uri it 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). 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. You can find a sample configuration in the next figure:

In the figure shown above the resource URI will return data of the profile with the following URI: https://demo.esignanywhere.net/api/v5/user/me. 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 birth date) to authenticate. Other users are not accepted. In the figure above we configured one filed with the email address of the user and added the field in the URI. As response for this URI we get the following data shown in the audit trail:

{
"id": "39cbe455xxxxxx",
"email": "some@email.com",  
"first_name": "Firstname",
"last_name": "Lastname",
}

If the user is not allowed to authenticate the following error will appear:

If authentication was successful you can find the app in Settings->Api Tokens and Apps in the section Apps and Connectors. Please see the next figure:
 

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

Force a specific user to authentication

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>