Skip to content

MIGRATING.md

Latest commit

 

History

History
225 lines (154 loc) · 15.2 KB

MIGRATING.md

File metadata and controls

225 lines (154 loc) · 15.2 KB
Raw

Okta .NET management SDK migration guide

This library uses semantic versioning and follows Okta's library version policy. In short, we don't make breaking changes unless the major version changes!

Migrating from 4.x to 5.x

In previous versions, null resource properties would result in a resource object with all its properties set to null. Now, null resource properties will result in null property value.

Before:

{                                                 deserializedResource.Prop1.Should().Be("Hello World!");          
    prop1 : "Hello World!",         =>            deserializedResource.NestedObject.Should().NotBeNull();
    nestedObject: null                            deserializedResource.NestedObject.Prop1.Should().BeNull();
}

Now:

{                                                 deserializedResource.Prop1.Should().Be("Hello World!");          
    prop1 : "Hello World!",         =>            deserializedResource.NestedObject.Should().BeNull();
    nestedObject: null                            
}

Since this is a breaking change in the default behavior, the major version of Okta.Sdk was incremented to 5; the latest version is now 5.0.0.

If you were relying on this behavior, make sure to update your code and verify the resource is not null before accessing its properties.

Migrating from 3.x to 4.x

The 3.x series of this library introduced a new client for Authorization Servers. This client had an issue when trying to retrieve policy rules for given Authorization Server Policy. In order to fix this issue, new policy models were created to represent both policies and policy rules for Authorization Servers.

Because this was a breaking change, Okta.Sdk was published with version numbers starting from 4.0.0.

All Authorization Server methods that manipulate Policies and/or Policy Rules have changed:

AuthorizationServer

Below APIs has undergone a signature change.

  • public ICollectionClient<IPolicy> ListPolicies() changed to public ICollectionClient<IAuthorizationServerPolicy> ListPolicies()

Note that the method returns now an IAuthorizationServerPolicy.

  • public Task<IPolicy> CreatePolicyAsync(IPolicy policy, CancellationToken cancellationToken = default(CancellationToken)) changed to public Task<IAuthorizationServerPolicy> CreatePolicyAsync(IAuthorizationServerPolicy policy, CancellationToken cancellationToken = default(CancellationToken))

Note that the method expects and returns now an IAuthorizationServerPolicy.

  • public Task<IPolicy> GetPolicyAsync(string policyId, CancellationToken cancellationToken = default(CancellationToken)) changed to public Task<IAuthorizationServerPolicy> GetPolicyAsync(string policyId, CancellationToken cancellationToken = default(CancellationToken))

Note that the method returns now an IAuthorizationServerPolicy.

AuthorizationServersClient

Below APIs has undergone a signature change.

  • public ICollectionClient<IPolicy> ListAuthorizationServerPolicies(string authServerId) changed to public ICollectionClient<IAuthorizationServerPolicy> ListAuthorizationServerPolicies(string authServerId)

Note that the method returns now an ICollectionClient of IAuthorizationServerPolicy.

  • public async Task<IPolicy> CreateAuthorizationServerPolicyAsync(IPolicy policy, string authServerId, CancellationToken cancellationToken = default(CancellationToken)) change to public async Task<IAuthorizationServerPolicy> CreateAuthorizationServerPolicyAsync(IAuthorizationServerPolicy policy, string authServerId, CancellationToken cancellationToken = default(CancellationToken))

Note that the method expects and returns now an IAuthorizationServerPolicy.

  • public async Task<IPolicy> GetAuthorizationServerPolicyAsync(string authServerId, string policyId, CancellationToken cancellationToken = default(CancellationToken)) changed to public async Task<IAuthorizationServerPolicy> GetAuthorizationServerPolicyAsync(string authServerId, string policyId, CancellationToken cancellationToken = default(CancellationToken))

Note that the method returns now an IAuthorizationServerPolicy.

  • public async Task<IPolicy> UpdateAuthorizationServerPolicyAsync(IPolicy policy, string authServerId, string policyId, CancellationToken cancellationToken = default(CancellationToken)) changed to public async Task<IAuthorizationServerPolicy> UpdateAuthorizationServerPolicyAsync(IAuthorizationServerPolicy policy, string authServerId, string policyId, CancellationToken cancellationToken = default(CancellationToken))

Note that the method expects and returns now an IAuthorizationServerPolicy.

You now can get policy rules given an Authorization Server Policy:

var authorizationServerPolicy = await authorizationServer.GetPolicyAsync(policy.Id);
var authorizationServerPolicyRules = await authorizationServerPolicy.ListPolicyRules(authorizationServer.Id).ToListAsync();

Migrating from 2.0.0 to 3.x

Version 3.0.0 of this library introduces a number of breaking changes from previous versions; in addition to new classes some class definitions are no longer backward compatible due to method renames and signature changes, see Breaking Changes.

Breaking Changes

The following is a list of changes that break backward compatibility in version 3.0.0.

Okta.Sdk.OktaClient

  • CreatedScoped(Okta.Sdk.RequestContext requestContext)
    — Renamed CreateScoped(Okta.Sdk.RequestContext requestContext)

Okta.Sdk.GroupsClient

  • ListGroups(string q, string filter, string after, int limit, string expand)
    — Signature changed ListGroups(string q, string filter, string after, int limit)
  • ListRules(int limit, string after, string expand)
    — Renamed with new signature ListGroupRules(int limit, string after, string search, string expand)
  • CreateRuleAsync(Okta.Sdk.IGroupRule groupRule, CancellationToken cancellationToken)
    — Renamed CreateGroupRuleAsync(Okta.Sdk.IGroupRule groupRule, CancellationToken cancellationToken)
  • DeleteRuleAsync(string ruleId, bool removeUsers, CancellationToken cancellationToken)
    — Renamed with new signature DeleteGroupRuleAsync(string ruleId, CancellationToken cancellationToken)
  • GetRuleAsync(string ruleId, string expand, CancellationToken cancellationToken)
    — Renamed GetGroupRuleAsync(string ruleId, string expand, CancellationToken cancellationToken)
  • UpdateRuleAsync(Okta.Sdk.IGroupRule groupRule, string ruleId, CancellationToken cancellationToken)
    — Renamed UpdateGroupRuleAsync(Okta.Sdk.IGroupRule groupRule, string ruleId, CancellationToken cancellationToken)
  • ActivateRuleAsync(string ruleId, CancellationToken cancellationToken)
    — Renamed ActivateGroupRuleAsync(string ruleId, CancellationToken cancellationToken)
  • DeactivateRuleAsync(string ruleId, CancellationToken cancellationToken)
    — Renamed DeactivateGroupRuleAsync(string ruleId, CancellationToken cancellationToken)
  • GetGroupAsync(string groupId, string expand, CancellationToken cancellationToken)
    — Signature changed GetGroupAsync(string groupId, CancellationToken cancellationToken)
  • ListGroupUsers(string groupId, string after, int limit, string managedBy)
    — Signature changed ListGroupUsers(string groupId, string after, int limit)
  • RemoveGroupUserAsync(string groupId, string userId, CancellationToken cancellationToken)
    — Renamed RemoveUserFromGroupAsync(string groupId, string userId, CancellationToken cancellationToken)

Okta.Sdk.PoliciesClient

  • ListPolicies(string type, string status, string after, int limit, string expand)
    — Signature changed ListPolicies(string type, string status, string expand)
  • AddPolicyRuleAsync(Okta.Sdk.IPolicyRule policyRule, string policyId, bool activate, CancellationToken cancellationToken)
    — Signature changed AddPolicyRuleAsync(Okta.Sdk.IPolicyRule policyRule, string policyId, CancellationToken cancellationToken)

Okta.Sdk.UserFactorsClient

  • AddFactorAsync(Okta.Sdk.IFactor factor, string userId, bool updatePhone, string templateId, int tokenLifetimeSeconds, bool activate, CancellationToken cancellationToken)
    — Renamed with new signature EnrollFactorAsync(Okta.Sdk.IUserFactor body, string userId, bool updatePhone, string templateId, int tokenLifetimeSeconds, bool activate, CancellationToken ca ncellationToken)
  • ActivateFactorAsync(Okta.Sdk.IVerifyFactorRequest verifyFactorRequest, string userId, string factorId, CancellationToken cancellationToken)
    — Renamed with new signature ActivateFactorAsync(Okta.Sdk.IActivateFactorRequest body, string userId, string factorId, CancellationToken cancellationToken)

Okta.Sdk.UsersClient

  • ListUsers(string q, string after, int limit, string filter, string format, string search, string expand)
    — Signature changed ListUsers(string q, string after, int limit, string filter, string search, string sortBy, string sortOrder)
  • CreateUserAsync(Okta.Sdk.IUser user, bool activate, bool provider, Okta.Sdk.UserNextLogin nextLogin, CancellationToken cancellationToken)
    — Signature changed CreateUserAsync(Okta.Sdk.ICreateUserRequest body, bool activate, bool provider, Okta.Sdk.UserNextLogin nextLogin, CancellationToken cancellationToken)
  • ListAppLinks(string userId, bool showAll)
    — Signature changed ListAppLinks(string userId)
  • ListUserGroups(string userId, string after, int limit)
    — Signature changed ListUserGroups(string userId)
  • ExpirePasswordAsync(string userId, bool tempPassword, CancellationToken cancellationToken)
    — Signature changed ExpirePasswordAsync(string userId, CancellationToken cancellationToken)
  • ResetAllFactorsAsync(string userId, CancellationToken cancellationToken)
    — Renamed ResetFactorsAsync(string userId, CancellationToken cancellationToken)
  • ResetPasswordAsync(string userId, Okta.Sdk.AuthenticationProviderType provider, bool sendEmail, CancellationToken cancellationToken)
    — Removed; instead use any of the following:
    • ForgotPasswordGenerateOneTimeTokenAsync(string userId, bool sendEmail, CancellationToken cancellationToken)
    • ForgotPasswordSetNewPasswordAsync(Okta.Sdk.IUserCredentials user, string userId, bool sendEmail, CancellationToken cancellationToken)
    • ExpirePasswordAsync(string userId, CancellationToken cancellationToken)
    • ExpirePasswordAndGetTemporaryPasswordAsync(string userId, CancellationToken cancellationToken)
  • ListAssignedRoles(string userId, string expand)
    — Renamed ListAssignedRolesForUser(string userId, string expand)
  • EndAllUserSessionsAsync(string userId, bool oauthTokens, CancellationToken cancellationToken)
    — Renamed ClearUserSessionsAsync(string userId, bool oauthTokens, CancellationToken cancellationToken)

New Okta Clients

The following is a list of context specific clients that are new in version 3.0.0. Instances of each are available as properties of an OktaClient instance where the name of the property is the name of the type with the "Client" suffix removed.

Migrating from 0.3.3 to 1.x

The previous version of this library, Okta.Core.Client, has been rewritten from the ground up as Okta.Sdk (this project). This was done to improve stability and to add support for .NET Core alongside .NET Framework.

Because this was a breaking change, Okta.Sdk was published with version numbers starting from 1.0. The last published version of Okta.Core.Client is 0.3.3.

New configuration model

This library now supports a flexible configuration model that allows you to provide configuration in code, via a JSON or YAML file, or via environment variables.

The simplest way to construct a client is via code:

var client = new OktaClient(new OktaClientConfiguration
{
    OrgUrl = "https://{{yourOktaDomain}}",
    Token = "{{yourApiToken}}"
});

New method organization

In version 0.3.3, you had to create a new UsersClient() or call client.GetUsersClient() to get access to methods that operated on a User (for example). This has now been simplified to client.Users:

var vader = await client.Users.CreateUserAsync(...);

The Users object acts as a collection, so you can also do:

var allUsers = await client.Users.ToArray();

The readme in this repository contains a number of usage examples.

Async by default

In version 1.0 and above, every method that makes a network call is Task-returning and awaitable. Use await when calling these methods, and avoid using .Result or .Wait() unless absolutely necessary.

Authentication API support moved

In version 0.3.3, the AuthClient class provided the ability to call the Authentication API to log a user in with a username and password, or perform other tasks like enrolling and challenging factors during authentication. The object and security model of the Authentication API compared the rest of the management APIs (Users, Factors, Groups, etc.) is different enough that it made sense to split it into two libraries.

Starting with version 1.0, Authentication has been broken out into a separate library, the Okta .NET Authentication SDK.

Many applications can use our ASP.NET and ASP.NET Core middleware to log users in without needing to call the Authentication API directly, and we recommend only using the Authentication SDK in complex scenarios that can't be handled with the middleware or widget.

Getting help

If you have questions about this library or about the Okta APIs, post a question on our Developer Forum.

If you find a bug or have a feature request for this library specifically, post an issue here on GitHub.