Skip to main content

Okta

Integration Guide​

Step 1: Installing the Package​

Install the PrimusSaaS.Identity.Validator package via NuGet:

dotnet add package PrimusSaaS.Identity.Validator

Step 2: Configuring Program.cs​

Register the Primus Identity services and middleware in your Program.cs:

using PrimusSaaS.Identity.Validator;

var builder = WebApplication.CreateBuilder(args);

// Add Primus Identity Validator
builder.Services.AddPrimusIdentity(opts => 
    builder.Configuration.GetSection("PrimusIdentity").Bind(opts));

builder.Services.AddControllers();
builder.Services.AddAuthorization();

var app = builder.Build();

app.UseAuthentication();
app.UseAuthorization();

app.MapControllers();

app.Run();

Step 3: Configuring App Settings​

Configure the Okta provider in your appsettings.json:

{
  "PrimusIdentity": {
    "RequireHttpsMetadata": true,
    "ValidateLifetime": true,
    "ClockSkew": "00:05:00",
    "Issuers": [
      {
        "Name": "Okta",
        "Type": "Okta",
        "Issuer": "https://dev-123456.okta.com/oauth2/default",
        "Authority": "https://dev-123456.okta.com/oauth2/default",
        "Audiences": [ "api://your-app-client-id" ]
      }
    ]
  }
}
How to create Okta application and get configuration values

1. Create an Okta Developer Account​

  1. Go to Okta Developer and sign up for a free account
  2. After verification, you'll get an Okta domain like dev-123456.okta.com

2. Create an API Application​

  1. In the Okta Admin Console, go to Applications Applications
  2. Click Create App Integration
  3. Select:
    • Sign-in method: OIDC - OpenID Connect
    • Application type: API Services (for machine-to-machine)
  4. Click Next
  5. Enter a name (e.g., My API)
  6. Click Save

3. Get Configuration Values​

After creating the app:

ValueWhere to Find
DomainTop right of Okta console (e.g., dev-123456.okta.com)
Client IDApplication General tab Client ID
Client SecretApplication General tab Client Secrets

4. Configure Authorization Server​

To allow your application to request a token, you need to define a Scope.

  1. Go to Security API.
  2. Select the default Authorization Server (or create a new one).
  3. Go to the Scopes tab and click Add Scope.
  4. Fill in the details:
    • Name: access (or your preferred scope name)
    • Display phrase: Access to API
    • Description: Allows machine-to-machine access
    • User consent: Implicit
  5. Click Create.

5. Grant Scope to Application​

After creating the scope, you must allow your application to use it:

  1. Go to Applications Applications.
  2. Select your application (e.g., Primus Validator Test).
  3. Go to the Okta API Scopes tab.
  4. Find your new scope (e.g., access) and click Grant.

Your issuer URL will be: https://dev-123456.okta.com/oauth2/default

6. Generate Access Token (for testing)​

curl -X POST https://dev-123456.okta.com/oauth2/default/v1/token \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -d "grant_type=client_credentials" \
     -d "client_id=YOUR_CLIENT_ID" \
     -d "client_secret=YOUR_CLIENT_SECRET" \
     -d "scope=api://your-app-client-id"

Step 4: Configuring Endpoint​

Create a protected endpoint to test the authentication.

[HttpGet("okta")]
[Authorize]
public IActionResult Get()
{
    return Ok(new { 
        validated = true,
        issuer = User.FindFirst("iss")?.Value,
        subject = User.FindFirst("sub")?.Value
    });
}

Step 5: Testing the Endpoint​

Get a token from Okta and test the endpoint:

curl -k -X GET "https://localhost:5001/okta" \
     -H "Authorization: Bearer <ACCESS_TOKEN>"

Alternative: Fluent API Configuration​

You can also configure Okta using the fluent API:

builder.Services.AddPrimusIdentity(opts =>
{
    opts.UseOkta(
        domain: "dev-123456.okta.com",
        audience: "api://your-app-client-id",
        authorizationServerId: "default"
    );
});