Merge pull request #61 from cranberyxl/feature/updateExtensionAuthenticationRequest

wparad · web-flow · commit d46d7fc998b7 · 2025-12-21T12:20:58.000+01:00
port updateExtensionAuthenticationRequest
diff --git a/docs/AuthenticationRequest.md b/docs/AuthenticationRequest.md
@@ -0,0 +1,7 @@
+# AuthenticationRequest
+
+## Properties
+
+Name | Type | Description | Notes
+------------ | ------------- | ------------- | -------------
+**authenticationUrl** | **String** | The recommended next url for the user to navigate to complete the authentication and log in successfully. |
diff --git a/docs/LoginApi.md b/docs/LoginApi.md
@@ -0,0 +1,37 @@
+# Login API
+
+Method | HTTP request | Description
+------------- | ------------- | -------------
+[**updateAuthenticationrequest**](LoginApi.md#updateAuthenticationRequest) | **PATCH** /api/authentication/{authenticationRequestId} | Update authentication request
+
+## updateAuthenticationRequest
+
+> AuthenticationRequest updateAuthenticationRequest(authenticationRequestId, selfHostedLoginApplicationUrl, updateAuthenticationRequestParameters)
+
+Update authentication request
+
+Patch an authentication request and update the properties. Use this to add in a connection ID, tenant ID, or other parameters so the user can complete their authentication and log in. This method should always and only be called from your custom self-hosted login screen: https://authress.io/app/#/settings?focus=branding
+
+### Example
+
+```javascript
+import { AuthressClient, Tenant } from '@authress/sdk';
+
+const authenticationRequestId = request.body.state; // AuthenticationRequestId
+const updateAuthenticationRequestParameters = new UpdateAuthenticationRequestParameters();
+updateAuthenticationRequestParameters.connectionId = 'con_connectionID';
+await new AuthressClient().login.updateAuthenticationRequest(authenticationRequestId, selfHostedLoginApplicationUrl, updateAuthenticationRequestParameters);
+```
+
+### Parameters
+
+
+Name | Type | Description  | Notes
+------------- | ------------- | ------------- | -------------
+ **authenticationRequestId** | **String**| The ID of the authentication request. When redirected from the Authress authenticate() call, this value is found in the `state` parameter of the url. | 
+ **selfHostedLoginApplicationUrl** | **String**| The application url for the self hosted login screen specified in the advanced options: https://authress.io/app/#/settings?focus=branding. If you are not using a self hosted login screen then this method should not be called. | 
+ **updateAuthenticationRequestParameters** | [**UpdateAuthenticationRequestParameters**](UpdateAuthenticationRequestParameters.md)|  | The properties of the authentication request to updated.
+
+### Return type
+
+[**AuthenticationRequest**](AuthenticationRequest.md)
diff --git a/docs/UpdateAuthenticationRequestParameters.md b/docs/UpdateAuthenticationRequestParameters.md
@@ -0,0 +1,11 @@
+# UpdateAuthenticationRequestParameters
+
+## Properties
+
+Name | Type | Description | Notes
+------------ | ------------- | ------------- | -------------
+**connectionId** | **String** | Specify which provider connection that user would like to use to log in - see https://authress.io/app/#/manage?focus=connections | [optional]
+**tenantLookupIdentifier** | **String** | Instead of connectionId, specify the tenant lookup identifier to log the user with the mapped tenant - see https://authress.io/app/#/manage?focus=tenants | [optional]
+**hint** | **String** | Instead of connectionId or tenant lookup identifier, specify the user's domain or the full email for the user to dynamically identify and log the user with the mapped tenant. | [optional]
+**inviteId** | **String** | Invite to use to login, only one of the connectionId, tenantLookupIdentifier, or the inviteId is required. | [optional]
+**connectionProperties** | [**ConnectionDefaultConnectionProperties**](ConnectionDefaultConnectionProperties.md) | Overrides the connection specific properties from the Authress Identity Connection to pass to the identity provider | [optional]
diff --git a/index.d.ts b/index.d.ts
@@ -28,6 +28,8 @@ import { Statement, LinkedGroup, User } from './src/records/dtos';
 export * from './src/invites/api';
 export * from './src/invites/dtos';
 
+import { LoginApi } from './src/login/api';
+
 /**
  * The Authress SDK primary settings object to be used with new AuthressClient.
  * @export
@@ -1082,6 +1084,12 @@ export class AuthressClient {
    */
   tenants: TenantsApi;
 
+  /**
+   * @summary The Login api
+   * @type {LoginApi}
+   */
+  login: LoginApi;
+
   /**
    * @summary Verify an incoming Authress JWT request access token here.
    * @type {Function<Promise<Record<string, unknown>>>}
diff --git a/index.js b/index.js
@@ -12,6 +12,7 @@ const ExtensionsApi = require('./src/extensionsApi');
 const TenantsApi = require('./src/tenantsApi');
 const ServiceClientTokenProvider = require('./src/serviceClientTokenProvider');
 const TokenVerifier = require('./src/tokenVerifier');
+const LoginApi = require('./src/loginApi');
 
 class AuthressClient {
   constructor(settings, tokenProvider) {
@@ -30,6 +31,7 @@ class AuthressClient {
     this.connections = new ConnectionsApi(this.httpClient);
     this.extensions = new ExtensionsApi(this.httpClient);
     this.tenants = new TenantsApi(this.httpClient);
+    this.login = new LoginApi(this.httpClient);
   }
 
   /**
diff --git a/src/connections/api.ts b/src/connections/api.ts
@@ -11,15 +11,15 @@ export interface ConnectionsApi {
    * Specify identity connection details for Authress identity aggregation.
    * @summary Create SSO connection
    * @param {Connection} body
-   * @throws {RequiredError}
+   * @throws {ArgumentRequiredError}
    */
   createConnection(body: Connection): Promise<Response<Connection>>;
 
   /**
    * Delete an identity connection details for Authress identity aggregation.
    * @summary Delete SSO connection
    * @param {string} connectionId The connection identifier.
-   * @throws {RequiredError}
+   * @throws {ArgumentRequiredError}
    */
   deleteConnection(connectionId: string): Promise<Response<void>>;
 
@@ -28,22 +28,22 @@ export interface ConnectionsApi {
   * @summary Update SSO connection
   * @param {Connection} body
   * @param {string} connectionId The connection identifier.
-  * @throws {RequiredError}
+  * @throws {ArgumentRequiredError}
   */
   updateConnection(connectionId: string, body: Connection): Promise<Response<Connection>>;
 
   /**
    * Get the identity connection details for Authress identity aggregation.
    * @summary Retrieve SSO connection
    * @param {string} connectionId The connection identifier.
-   * @throws {RequiredError}
+   * @throws {ArgumentRequiredError}
    */
   getConnection(connectionId: string): Promise<Response<Connection>>;
 
   /**
    * Returns a paginated connection list for the account. Only connections the user has access to are returned.
    * @summary List SSO connections
-   * @throws {RequiredError}
+   * @throws {ArgumentRequiredError}
    */
   getConnections(): Promise<Response<ConnectionCollection>>;
 
diff --git a/src/extensions/api.ts b/src/extensions/api.ts
@@ -11,15 +11,15 @@ export interface ExtensionsApi {
    * Specify identity extension details for Authress identity aggregation.
    * @summary Create SSO extension
    * @param {Extension} body
-   * @throws {RequiredError}
+   * @throws {ArgumentRequiredError}
    */
   createExtension(body: Extension): Promise<Response<Extension>>;
 
   /**
    * Delete an identity extension details for Authress identity aggregation.
    * @summary Delete SSO extension
    * @param {string} extensionId The extension identifier.
-   * @throws {RequiredError}
+   * @throws {ArgumentRequiredError}
    */
   deleteExtension(extensionId: string): Promise<Response<void>>;
 
@@ -28,22 +28,22 @@ export interface ExtensionsApi {
   * @summary Update SSO extension
   * @param {Extension} body
   * @param {string} extensionId The extension identifier.
-  * @throws {RequiredError}
+  * @throws {ArgumentRequiredError}
   */
   updateExtension(extensionId: string, body: Extension): Promise<Response<Extension>>;
 
   /**
    * Get the identity extension details for Authress identity aggregation.
    * @summary Retrieve SSO extension
    * @param {string} extensionId The extension identifier.
-   * @throws {RequiredError}
+   * @throws {ArgumentRequiredError}
    */
   getExtension(extensionId: string): Promise<Response<Extension>>;
 
   /**
    * Returns a paginated extension list for the account. Only extensions the user has access to are returned.
    * @summary List SSO extensions
-   * @throws {RequiredError}
+   * @throws {ArgumentRequiredError}
    */
   getExtensions(): Promise<Response<ExtensionCollection>>;
 }
diff --git a/src/invites/api.ts b/src/invites/api.ts
@@ -26,7 +26,7 @@ export interface InvitesApi {
    * Accepts an invite by claiming this invite by this user. The user access token used for this request will gain the permissions associated with the invite.
    * @summary Accept invite
    * @param {string} inviteId The identifier of the invite.
-   * @throws {RequiredError}
+   * @throws {ArgumentRequiredError}
    */
   respondToInvite(inviteId: string): Promise<Response<void>>;
   /**
diff --git a/src/jwtManager.js b/src/jwtManager.js
@@ -1,4 +1,5 @@
 const base64url = require('base64url');
+const crypto = require('crypto');
 
 class JwtManager {
   decode(token) {
@@ -8,6 +9,23 @@ class JwtManager {
       return null;
     }
   }
+
+  calculateAntiAbuseHash(props) {
+    const timestamp = Date.now();
+    const valueString = Object.values(props).filter(v => v).join('|');
+
+    let fineTuner = 0;
+    let hash = null;
+    while (++fineTuner) {
+      const verifier = `${timestamp};${fineTuner};${valueString}`;
+      hash = base64url.encode(crypto.createHash('sha256').update(verifier).digest());
+      if (hash.match(/^00/)) {
+        return `v2;${verifier}`;
+      }
+    }
+
+    throw Error('Could not calculate a valid anti abuse hash.');
+  }
 }
 
 module.exports = new JwtManager();
diff --git a/src/login/api.ts b/src/login/api.ts
@@ -0,0 +1,20 @@
+/* eslint-disable node/no-missing-import */
+import { Response } from '../response';
+import { UpdateAuthenticationRequestParameters, AuthenticationRequest } from './dtos';
+
+/**
+ * LoginApi
+ * @export
+ */
+export interface LoginApi {
+  /**
+  * Patch an authentication request and update the properties. Use this to add in a connection ID, tenant ID, or other parameters so the user can complete their authentication and log in. This method should always and only be called from your custom self-hosted login screen: https://authress.io/app/#/settings?focus=branding
+  * @summary Update Authentication Request
+  * @param {string} authenticationRequestId The ID of the authentication request. When redirected from the Authress authenticate() call, this value is found in the `state` parameter of the url.
+  * @param {string} selfHostedLoginApplicationUrl The application url for the self hosted login screen specified in the advanced options: https://authress.io/app/#/settings?focus=branding. If you are not using a self hosted login screen then this method should not be called.
+  * @param {UpdateAuthenticationRequestParameters} authenticationRequest The properties of the authentication request to updated.
+  * @throws {ArgumentRequiredError}
+  */
+  updateAuthenticationRequest(authenticationRequestId: string, selfHostedLoginApplicationUrl: string, authenticationRequest: UpdateAuthenticationRequestParameters):
+    Promise<Response<AuthenticationRequest>>;
+}
diff --git a/src/login/dtos.ts b/src/login/dtos.ts
@@ -0,0 +1,29 @@
+/* eslint-disable no-shadow */
+/* eslint-disable no-redeclare */
+/* eslint-disable @typescript-eslint/no-namespace */
+
+/**
+ * @export
+ * @interface UpdateAuthenticationRequestParameters
+ */
+export interface UpdateAuthenticationRequestParameters {
+  /** Specify which provider connection that user would like to use to log in - see https://authress.io/app/#/manage?focus=connections */
+  connectionId?: string;
+  /** Instead of connectionId, specify the tenant lookup identifier to log the user with the mapped tenant - see https://authress.io/app/#/manage?focus=tenants */
+  tenantLookupIdentifier?: string;
+  /** Instead of connectionId or tenant lookup identifier, specify the user's domain or the full email for the user to dynamically identify and log the user with the mapped tenant. */
+  hint?: string;
+  /** Invite to use to login, only one of the connectionId, tenantLookupIdentifier, or the inviteId is required. */
+  inviteId?: string;
+  /** Overrides the connection specific properties from the Authress Identity Connection to pass to the identity provider */
+  connectionProperties?: Record<string, string>;
+}
+
+/**
+ * @export
+ * @interface AuthenticationRequest
+ */
+export interface AuthenticationRequest {
+  /** The recommended next url for the user to navigate to complete the authentication and log in successfully. */
+  authenticationUrl: string;
+}
diff --git a/src/loginApi.js b/src/loginApi.js
@@ -0,0 +1,57 @@
+const ArgumentRequiredError = require('./argumentRequiredError');
+const jwtManager = require('./jwtManager');
+
+const parseUrl = urlString => {
+  if (!urlString) {
+    return null;
+  }
+
+  try {
+    return new URL(urlString);
+  } catch {
+    return null;
+  }
+};
+
+class LoginApi {
+  constructor(client) {
+    this.client = client;
+  }
+
+  async updateAuthenticationRequest(authenticationRequestId, selfHostedLoginApplicationUrl, updateAuthenticationRequestParameters) {
+    // verify required parameter 'authenticationRequestId' is not null or undefined
+    if (authenticationRequestId === null || authenticationRequestId === undefined) {
+      throw new ArgumentRequiredError('authenticationRequestId', 'Required parameter authenticationRequestId was null or undefined when calling updateAuthenticationRequest.');
+    }
+    if (updateAuthenticationRequestParameters === null || updateAuthenticationRequestParameters === undefined) {
+      throw new ArgumentRequiredError('authenticationRequest', 'Required parameter authenticationRequest was null or undefined when calling updateAuthenticationRequest.');
+    }
+
+    if (!updateAuthenticationRequestParameters.connectionId && !updateAuthenticationRequestParameters.tenantLookupIdentifier && !updateAuthenticationRequestParameters.hint) {
+      throw new ArgumentRequiredError('connectionId', 'Either parameter connectionId and tenantLookupIdentifier must be defined in updateAuthenticationRequest.');
+    }
+
+    if (!parseUrl(selfHostedLoginApplicationUrl)) {
+      throw new ArgumentRequiredError('selfHostedLoginApplicationUrl', 'Required parameter selfHostedLoginApplicationUrl was not or undefined when calling updateAuthenticationRequest.');
+    }
+
+    const connectionId = updateAuthenticationRequestParameters.connectionId;
+    const resolvedTenantLookupIdentifier = updateAuthenticationRequestParameters.hint || updateAuthenticationRequestParameters.tenantLookupIdentifier;
+    const antiAbuseHash = await jwtManager.calculateAntiAbuseHash({ connectionId, tenantLookupIdentifier: resolvedTenantLookupIdentifier, authenticationRequestId });
+    const requestBody = {
+      antiAbuseHash,
+      connectionId,
+      tenantLookupIdentifier: resolvedTenantLookupIdentifier,
+      connectionProperties: updateAuthenticationRequestParameters.connectionProperties
+    };
+    const headers = {
+      origin: selfHostedLoginApplicationUrl
+    };
+    const response = await this.client.patch(`/api/authentication/${encodeURIComponent(String(authenticationRequestId))}`, requestBody, headers);
+    return {
+      authenticationUrl: response.data.authenticationUrl
+    };
+  }
+}
+
+module.exports = LoginApi;
diff --git a/src/tenants/api.ts b/src/tenants/api.ts
@@ -11,15 +11,15 @@ export interface TenantsApi {
    * Specify identity tenant details for Authress identity aggregation.
    * @summary Create SSO tenant
    * @param {Tenant} body
-   * @throws {RequiredError}
+   * @throws {ArgumentRequiredError}
    */
   createTenant(body: Tenant): Promise<Response<Tenant>>;
 
   /**
    * Delete an identity tenant details for Authress identity aggregation.
    * @summary Delete SSO tenant
    * @param {string} tenantId The tenant identifier.
-   * @throws {RequiredError}
+   * @throws {ArgumentRequiredError}
    */
   deleteTenant(tenantId: string): Promise<Response<void>>;
 
@@ -28,22 +28,22 @@ export interface TenantsApi {
   * @summary Update SSO tenant
   * @param {Tenant} body
   * @param {string} tenantId The tenant identifier.
-  * @throws {RequiredError}
+  * @throws {ArgumentRequiredError}
   */
   updateTenant(tenantId: string, body: Tenant): Promise<Response<Tenant>>;
 
   /**
    * Get the identity tenant details for Authress identity aggregation.
    * @summary Retrieve SSO tenant
    * @param {string} tenantId The tenant identifier.
-   * @throws {RequiredError}
+   * @throws {ArgumentRequiredError}
    */
   getTenant(tenantId: string): Promise<Response<Tenant>>;
 
   /**
    * Returns a paginated tenant list for the account. Only tenants the user has access to are returned.
    * @summary List SSO tenants
-   * @throws {RequiredError}
+   * @throws {ArgumentRequiredError}
    */
   getTenants(): Promise<Response<TenantCollection>>;
 }
