Skip to content

MIGRATING.md

Latest commit

 

History

History
227 lines (163 loc) · 7.77 KB

MIGRATING.md

File metadata and controls

227 lines (163 loc) · 7.77 KB
Raw

Okta Node.js SDK — Migration Guide

This document covers upgrading between major and minor versions of @okta/okta-sdk-nodejs.

From 8.0 to 8.1

Version 8.1.0 contains no breaking API changes. The following TypeScript type corrections may require minor updates in TypeScript codebases:

1. IdentityProviderProtocol discriminant type is now required

The type property on the five IdentityProviderProtocol subtypes (ProtocolOidc, ProtocolSaml, ProtocolMtls, ProtocolOAuth, ProtocolIdVerification) is now correctly marked as required (was incorrectly optional due to a code-generator bug). This matches the Okta API spec. If your TypeScript code constructs a Protocol object without an explicit type field, add the appropriate discriminant literal:

// Before (compiled without error in 8.0 even though 'type' was required by the API)
const protocol: ProtocolOidc = { /* no type field */ };

// After (8.1) — add the required discriminant
const protocol: ProtocolOidc = { type: 'OIDC', /* ... */ };

2. ProfileMapping.properties and ProfileMappingRequest.properties type corrected

The TypeScript type of the properties field has changed from ProfileMappingProperty (single object, incorrect) to { [key: string]: ProfileMappingProperty } (map, correct). This was a bug fix — the old type caused all custom attribute keys to be silently dropped when serializing.

// Before (8.0) — incorrect type caused silent data loss at runtime
const request: ProfileMappingRequest = {
  properties: { expression: 'user.login', pushStatus: 'PUSH' } as ProfileMappingProperty
};

// After (8.1) — correct map type, custom attributes are preserved
const request: ProfileMappingRequest = {
  properties: {
    login: { expression: 'user.login', pushStatus: 'PUSH' },
    email: { expression: 'user.email', pushStatus: 'PUSH' }
  }
};

From 7.x to 8.0

Breaking Changes

Version 8.0 includes several breaking changes due to updates in the Okta OpenAPI specification:

1. Email Server API — Property Renamed

The EmailTestAddresses model has been updated with renamed properties:

Old (v7.x):

await client.emailServerApi.testEmailServer({
  emailServerId: emailServer.id,
  emailTestAddresses: {
    _from: 'test@example.com',
    to: 'recipient@example.com'
  }
});

New (v8.0):

await client.emailServerApi.testEmailServer({
  emailServerId: emailServer.id,
  emailTestAddresses: {
    fromAddress: 'test@example.com',  // Changed from '_from'
    to: 'recipient@example.com'
  }
});

2. Custom Role API — Model Renamed

The CustomRole model has been renamed to IamRole:

Old (v7.x):

import { CustomRole } from '@okta/okta-sdk-nodejs';

let customRole: CustomRole;

New (v8.0):

import { IamRole } from '@okta/okta-sdk-nodejs';

let customRole: IamRole;  // Changed from CustomRole

3. Role Assignment API — Model Renamed

The AssignRoleRequest model has been renamed to StandardRoleAssignmentSchema:

Old (v7.x):

import { AssignRoleRequest } from '@okta/okta-sdk-nodejs';

const roleRequest: AssignRoleRequest = {
  type: 'USER_ADMIN'
};

await client.userApi.assignRoleToUser({
  userId: user.id,
  assignRoleRequest: roleRequest
});

New (v8.0):

import { StandardRoleAssignmentSchema } from '@okta/okta-sdk-nodejs';

const roleRequest: StandardRoleAssignmentSchema = {  // Changed from AssignRoleRequest
  type: 'USER_ADMIN'
};

await client.userApi.assignRoleToUser({
  userId: user.id,
  assignRoleRequest: roleRequest
});

New APIs Added in 8.0

  • AgentConnectionsApi — Manage agent connections
  • AgentPotentialConnectionsApi — Discover potential agent connections
  • AgentPublicKeyApi — Manage agent public keys
  • AgentRegistrationApi — Handle agent registration
  • ApplicationCrossAppAccessConnectionsApi — Manage cross-app access connections
  • ApplicationInterclientTrustMappingsApi — Configure interclient trust mappings
  • ApplicationSSOPublicKeysApi — Manage application SSO public keys
  • AssociatedDomainCustomizationsApi — Customize associated domains
  • CustomTelephonyProviderApi — Configure custom telephony providers
  • GroupPushMappingApi — Manage group push mappings
  • OAuth2ResourceServerCredentialsKeysApi — Manage OAuth2 resource server credentials
  • OktaManagedUserAccountApi — Manage Okta managed user accounts
  • OperationsIntegrationApi — Handle operations integrations
  • UserAuthenticatorEnrollmentsApi — Manage user authenticator enrollments

API Enhancements in 8.0

  • ApplicationApi — Enhanced with additional methods for improved application management
  • AuthenticatorApi — Expanded authenticator management capabilities
  • IdentitySourceApi — Significantly enhanced with extensive new methods for identity source operations
  • YourOinIntegrationsApi — Enhanced integration management features

From 6.x to 7.0

Breaking changes

  • Methods are invoked on scoped clients
  • Method params are passed as a single object
  • Models no longer have CRUD methods
  • Methods which return Collection become async
  • Enums are replaced with union types
  • Model properties are optional
- await client.getUser('ausmvdt5xg8wRVI1d0g3')
+ await client.userApi.getUser({ userId: 'ausmvdt5xg8wRVI1d0g3' })
- await user.deactivate()
+ await client.userApi.deactivateUser({ userId: user.id })

From 5.x to 6.0

Breaking changes

Enum types from the spec are accounted for: respective JS models are converted to enum-like modules.

Following Client method signatures have changed:

  • listPolicies returns Promise<Policy>
  • activateNetworkZone returns Promise<NetworkZone>
  • deactivateNetworkZone returns Promise<NetworkZone>
  • listGroups no longer accepts filter parameter through queryParameters

From 4.x to 5.0

The version 5.0 of this SDK dropped support for Node 10, which is EOL (End-of-Life) since 2021-04-30. Current supported minimal Node version is 12.0.0.

Breaking changes

Following Client method signatures have changed:

  • createAuthorizationServerPolicy: added authorizationServerPolicy: AuthorizationServerPolicyOptions parameter
  • listAuthorizationServerPolicies: returns Collection<AuthorizationServerPolicy>
  • getAuthorizationServerPolicy: returns Promise<AuthorizationServerPolicy>
  • updateAuthorizationServerPolicy: second parameter type changed to AuthorizationServerPolicyOptions, returns Promise<AuthorizationServerPolicy>
  • listPolicies returns Promise<AuthorizationServerPolicy>

Following models' method signatures have changed:

  • AuthorizationServer

Change details are listed in CHANGELOG.md.

All required method parameters in Client are now checked at runtime in JS code.

From 3.x to 4.0

The version 4.0 of this SDK dropped support for Node 8, which is EOL (End-of-Life) since 2019-12-31. Current supported minimum Node version is 10.0.0.

This version 4.0 release also updated APIs to the latest @okta/openapi (v2.0.0) which includes added, changed and deprecated factories/models/client methods. Change details are listed in CHANGELOG.md. For each change item:

  • Add — newly added factories/models/client methods.
  • Change (breaking changes) — renamed factories/models/client methods.
  • Remove (breaking changes) — deprecated factories/models/client methods.

Main breaking changes

  • Renamed Factor related factories/models/client methods to UserFactor
  • Renamed client.sessionApi.endAllUserSessions to client.sessionApi.clearUserSessions
  • Model and Client methods change for User related operations
  • Model and Client methods change for Rule related operations