OAuth2

Additionally to (or instead of) a user based authentication, your webPDF server may accept OAuth2 authorization tokens to establish the permissions of your session.

Such a token may be requested from an authorization provider (currently the webPDF server supports Azure AD and Auth0).

To pass such a token to the wsclient, you must implement the OAuth2Provider accordingly.

The usage is identical for REST and SOAP - hence only REST usage examples shall be provided.

Simplified the following examples both implement the wsclient interface OAuth2Provider and pass an instance of such an AuthProvider to:

await SessionFactory.createInstance(sessionContext, authProvider);

Azure AD - using the @azure/msal-node library

Provider implementation

// An implementation of "OAuth2Provider" is used to provide an access token
export class AzureProvider implements OAuth2Provider {
   private token?: OAuth2Token;
   private readonly authority: string;
   private readonly clientId: string;
   private readonly clientSecret: string;
   private readonly scope: string;

   public constructor(authority: string, clientId: string, clientSecret: string, scope: string) {
      this.authority = authority;
      this.clientId = clientId;
      this.clientSecret = clientSecret;
      this.scope = scope;
   }

   public async provide(session: Session): Promise<OAuth2Token> {
      // return access token if already requested
      if (typeof this.token !== "undefined") {
         return this.token;
      }

      try {
         // Request an access token from the Azure authorization provider:
         let app: ConfidentialClientApplication = new ConfidentialClientApplication({
            auth: {
               authority: this.authority,
               clientId: this.clientId,
               clientSecret: this.clientSecret
            }
         });

         let response: AuthenticationResult | null = await app.acquireTokenByClientCredential({
            scopes: [this.scope]
         });

         if (response === null) {
            throw new ClientResultException(WsclientErrors.AUTHENTICATION_FAILURE);
         }

         // Create and return the OAuth2 access Token.
         this.token = new OAuth2Token(response.accessToken);
      } catch (e: any) {
         // Occurring exceptions can and should be wrapped as AuthResultExceptions. 
         throw new AuthResultException(e);
      }

      return this.token;
   }

   refresh(session: Session): Promise<OAuth2Token> {
      // Refresh implementation
   };
}

usage

// ...
let session: RestSession<RestDocument> = await SessionFactory.createInstance(
   new SessionContext(WebServiceProtocol.REST, testServer.getServer(ServerType.LOCAL)),
   new AzureProvider(
      "URL of the authority to request authorization from.",
      "The ID of the client to authorize",
      "The client secret",
      "The scope to claim authorization for."
   )
);

Auth0 - using the auth0 library

Provider implementation

// An implementation of "OAuth2Provider" is used to provide an access token
export class Auth0Provider implements OAuth2Provider {
   private token?: OAuth2Token;
   private readonly authority: string;
   private readonly clientId: string;
   private readonly clientSecret: string;
   private readonly audience: string;

   public constructor(
      authority: string, clientId: string, clientSecret: string, audience: string
   ) {
      this.authority = authority;
      this.clientId = clientId;
      this.clientSecret = clientSecret;
      this.audience = audience;
   }

   public async provide(session: Session): Promise<OAuth2Token> {
      // return access token if already requested
      if (typeof this.token !== "undefined") {
         return this.token;
      }

      try {
         // Request an access token from the Auth0 authorization provider:
         let auth: AuthenticationClient = new AuthenticationClient({
            domain: this.authority,
            clientId: this.clientId,
            clientSecret: this.clientSecret
         });

         let token: TokenResponse = await auth.clientCredentialsGrant({
            audience: this.audience
         })

         // Create and return the OAuth2 access Token.
         this.token = new OAuth2Token(token.access_token);
      } catch (e: any) {
         // Occurring exceptions can and should be wrapped as AuthResultExceptions. 
         throw new AuthResultException(e);
      }

      return this.token;
   }

   refresh(session: Session): Promise<OAuth2Token> {
      // Refresh implementation
   };
}

usage

// ...
let session: RestSession<RestDocument> = await SessionFactory.createInstance(
   new SessionContext(WebServiceProtocol.REST, testServer.getServer(ServerType.LOCAL)),
   new Auth0Provider(
      "URL of the authority to request authorization from.",
      "The ID of the client to authorize",
      "The client secret",
      "The Audience to aquire the token for."
   )
);

Neither the webPDF server nor the wsclient library automatically refresh such access tokens and your implementation of OAuth2Provider is also required to recognize the necessity and provide the means to do this.