Okta .NET Authentication SDK

Release status
Need help?
Getting started
Usage guide
Configuration reference
Building the SDK
Contributing

This repository contains the Okta Authentication SDK for .NET which is used in your server-side code to interact with the Okta Authentication API.

For high level information about the features of the Okta Authentication product see Okta Authentication.

⚠️ NOTE: Using OAuth 2.0 or OpenID Connect to integrate your application instead of this library requires much less work, and has a smaller risk profile. Please see this guide to see if using this API is right for your use case. You could also use our ASP.NET Integration out of the box.

Okta's Authentication API is built around a state machine. In order to use this library you will need to be familiar with the available states.

For more information about multifactor authentication see the multifactor authentication guide.

We also publish these other libraries for .NET:

You can learn more on the Okta + .NET page in our documentation.

Release status

This library uses semantic versioning and follows Okta's library version policy.

✔️ The current stable major version series is: 2.x

Version	Status
1.x	⚠️ Retiring on 2021-03-29
2.x	✔️ Stable

The latest release can always be found on the releases page.

Need help?

If you run into problems using the SDK, you can

Ask questions on the Okta Developer Forums
Post issues here on GitHub (for code errors)

Getting Started

The SDK is compatible with:

.NET Standard 2.0 and 2.1
.NET Framework 4.6.1 or higher
.NET Core 3.0 or higher
.NET 5.0

Install using Nuget Package Manager

Right-click on your project in the Solution Explorer and choose Manage Nuget Packages...
Search for Okta. Install the Okta.Auth.Sdk package.

Install using The Package Manager Console

Simply run install-package Okta.Auth.Sdk. Done!

You'll also need:

An Okta account, called an organization (sign up for a free developer organization if you need one)

Construct a client instance by passing it your Okta domain name:

var client = new AuthenticationClient(new OktaClientConfiguration
{
    OktaDomain = "https://{{yourOktaDomain}}",
});

Hard-coding the Okta domain works for quick tests, but for real projects you should use a more secure way of storing your Organization values (such as environment variables). This library supports a few different configuration sources, covered in the configuration reference section.

Usage guide

These examples will help you understand how to use this library.

Once you initialize an AuthenticationClient, you can call methods to make requests to the Okta API.

Primary Authentication

var authnOptions = new AuthenticateOptions()
{
    Username = $"darth.vader@imperial-senate.gov",
    Password = "D1sturB1ng!",
};

var authnResponse = await authClient.AuthenticateAsync(authnOptions);

Primary Authentication with Activation Token

var authnOptions = new AuthenticateWithActivationTokenOptions()
{
    ActivationToken = "foo",
};

var authnResponse = await authClient.AuthenticateAsync(authnOptions);

Change Password

var changePasswordOptions = new ChangePasswordOptions()
{
    StateToken = "foo",
    OldPassword = "Okta4321!",
    NewPassword = "Okta1234!",
};

var authnResponse = await authClient.ChangePasswordAsync(changePasswordOptions);

Enroll Security Question Factor

var enrollOptions = new EnrollSecurityQuestionFactorOptions()
{
    Question = "name_of_first_plush_toy",
    Answer = "blah",
    StateToken = "foo",
};

var authnResponse = await authnClient.EnrollFactorAsync(enrollOptions);

Enroll SMS Factor

var enrollOptions = new EnrollSMSFactorOptions()
{
    PhoneNumber = "+1 415 555 5555",
    StateToken = "foo",
};

var authnResponse = await authnClient.EnrollFactorAsync(enrollOptions);

Enroll Call Factor

var enrollFactorOptions = new EnrollCallFactorOptions()
{
    PhoneNumber = "+1-555-415-1337",
    StateToken = "foo",
};

var authnResponse = await authnClient.EnrollFactorAsync(enrollFactorOptions);

Enroll Okta Verify TOTP Factor

var enrollOptions = new EnrollTotpFactorOptions()
{
    StateToken = "foo",
    Provider = OktaDefaults.GoogleProvider,
};

var authnResponse = await authnClient.EnrollFactorAsync(enrollOptions);

Enroll Okta Verify Push Factor

var enrollOptions = new EnrollPushFactorOptions()
{
    StateToken = "foo",
};

var authnResponse = await authnClient.EnrollFactorAsync(enrollOptions);

Enroll RSA SecurID Factor

var enrollOptions = new EnrollRsaFactorOptions()
{
    StateToken = "foo",
    CredentialId = "dade.murphy@example.com",
    PassCode = "bar",
};

var authnResponse = await authnClient.EnrollFactorAsync(enrollOptions);

Enroll Symantec VIP Factor

var enrollOptions = new EnrollSymantecFactorOptions()
{
    StateToken = "foo",
    CredentialId = "dade.murphy@example.com",
    PassCode = "bar",
    NextPassCode = "baz",
};

var authnResponse = await authnClient.EnrollFactorAsync(enrollOptions);

Enroll YubiKey Factor

var enrollOptions = new EnrollYubiKeyFactorOptions()
{
    PassCode = "bar",
    StateToken = "foo",
};

var authnResponse = await authnClient.EnrollFactorAsync(enrollOptions);

Enroll Duo Factor

var enrollOptions = new EnrollDuoFactorOptions()
{
    StateToken = "foo",
};

var authnResponse = await authnClient.EnrollFactorAsync(enrollOptions);

Enroll U2F Factor

var enrollOptions = new EnrollU2FFactorOptions()
{
    StateToken = "foo",
};

var authnResponse = await authnClient.EnrollFactorAsync(enrollOptions);

Activate U2F Factor

var activateFactorOptions = new ActivateU2fFactorOptions()
{
    FactorId = "ostf1fmaMGJLMNGNLIVG",
    StateToken = "foo",
    RegistrationData = "bar",
    ClientData = "baz",
};

var authResponse = await authnClient.ActivateFactorAsync(activateFactorOptions);

Activate Push Factor

var activatePushFactorOptions = new ActivatePushFactorOptions()
{
    StateToken = "foo",
    FactorId = "bar",
};

var authResponse = await authnClient.ActivateFactorAsync(activatePushFactorOptions);

Activate Other Factors

var activateFactorOptions = new ActivateFactorOptions()
{
    StateToken = "00xdqXOE5qDXX8-PBR1bYv8AESqIEinDy3yul01tyh",
    FactorId = "foo",
    PassCode = "bar",
};

var authResponse = await authnClient.ActivateFactorAsync(activateFactorOptions);

Verify SMS Factor

var verifyFactorOptions = new VerifySmsFactorOptions()
{
    StateToken = "foo",
    FactorId = "bar",
};

var authResponse = await authnClient.VerifyFactorAsync(verifyFactorOptions);

Verify Call Factor

var verifyFactorOptions = new VerifyCallFactorOptions()
{
    FactorId = "ostf1fmaMGJLMNGNLIVG",
    StateToken = "foo",
    PassCode = "bar",
    RememberDevice = true,
};

var authResponse = await authnClient.VerifyFactorAsync(verifyFactorOptions);

Verify Security Question Factor

var verifyFactorOptions = new VerifySecurityQuestionFactorOptions()
{
    FactorId = "ostf1fmaMGJLMNGNLIVG",
    StateToken = "foo",
    Answer = "bar",
};

var authResponse = await authnClient.VerifyFactorAsync(verifyFactorOptions);

Verify TOTP Factor

var verifyFactorOptions = new VerifySmsFactorOptions()
{
    FactorId = "ostf1fmaMGJLMNGNLIVG",
    StateToken = "foo",
    PassCode = "bar",
    RememberDevice = true,
};

var authResponse = await authnClient.VerifyFactorAsync(verifyFactorOptions);

Verify Push Factor

var verifyFactorOptions = new VerifyPushFactorOptions()
{
    FactorId = "ostf1fmaMGJLMNGNLIVG",
    StateToken = "foo",
    AutoPush = true,
    RememberDevice = true,
};

var authResponse = await authnClient.VerifyFactorAsync(verifyFactorOptions);

Verify Duo Factor

var verifyFactorOptions = new VerifyDuoFactorOptions()
{
    FactorId = "ostf1fmaMGJLMNGNLIVG",
    StateToken = "foo",
};

var authResponse = await authnClient.VerifyFactorAsync(verifyFactorOptions);

Verify U2F Factor

var verifyFactorOptions = new VerifyU2FFactorOptions()
{
    FactorId = "ostf1fmaMGJLMNGNLIVG",
    StateToken = "foo",
    ClientData = "bar",
    SignatureData = "baz",
    RememberDevice = true,
};

var authResponse = await authnClient.VerifyFactorAsync(verifyFactorOptions);

Unlock Account

var unlockAccountOptions = new UnlockAccountOptions()
{
    FactorType = new FactorType(factorType),
    RelayState = "/myapp/some/deep/link/i/want/to/return/to",
    Username = "dade.murphy@example.com",
};

await authnClient.UnlockAccountAsync(unlockAccountOptions);

Reset Password

var resetPasswordOptions = new ResetPasswordOptions()
{
    NewPassword = "1234",
    StateToken = "00xdqXOE5qDXX8-PBR1bYv8AESqIEinDy3yul01tyh",
};

var authResponse = await authnClient.ResetPasswordAsync(resetPasswordOptions);

Verify Recovery Token

var verifyFactorOptions = new VerifyRecoveryTokenOptions()
{
    RecoveryToken = "foo",
};

await authnClient.VerifyRecoveryTokenAsync(verifyFactorOptions);

Verify Recovery Factor

var verifyFactorOptions = new VerifyRecoveryFactorOptions()
{
    StateToken = "foo",
    PassCode = "bar",
    FactorType = new FactorType(factorType),
};

await authnClient.VerifyRecoveryFactorAsync(verifyFactorOptions);

Answer Recovery Question

var answerRecoveryQuestionOptions = new AnswerRecoveryQuestionOptions()
{
    StateToken = "foo",
    Answer = "bar",
};

await authnClient.AnswerRecoveryQuestionAsync(answerRecoveryQuestionOptions);

Get Transaction State

var transactionStateOptions = new TransactionStateOptions()
{
    StateToken = "foo",
};

await authnClient.GetTransactionStateAsync(transactionStateOptions);

Previous Transaction State

var transactionStateOptions = new TransactionStateOptions()
{
    StateToken = "foo",
};

await authnClient.GetPreviousTransactionStateAsync(transactionStateOptions);

Skip Transaction State

var transactionStateOptions = new TransactionStateOptions()
{
    StateToken = "foo",
};

await authnClient.SkipTransactionStateAsync(transactionStateOptions);

Cancel Transaction State

var transactionStateOptions = new TransactionStateOptions()
{
    StateToken = "foo",
};

await authnClient.CancelTransactionStateAsync(transactionStateOptions);

Send information via request's headers.

The scenarios described in this section require you to send additional information in the user-agent, x-forwarded-for and x-device-fingerprinting headers. This SDK allows you to define these headers via method parameters or construct and send custom requests using the AuthenticationClient.