Skip to main content
Version: Current

Okta

Configure workforce identity with Okta.

Step 1: Install the package​

dotnet add package PrimusSaaS.Identity.Broker

Step 2: Configure Program.cs and middleware​

using PrimusSaaS.Identity.Broker;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddPrimusAuthBroker(builder.Configuration, builder.Environment.IsDevelopment());
builder.Services.AddControllers();

var app = builder.Build();
app.UseAuthentication();
app.UseAuthorization();
app.UsePrimusCsrfProtection();
app.MapControllers();
app.MapPrimusAuthBroker();
app.Run();

Step 3: Configure appsettings.json​

{
  "Okta": {
    "Domain": "https://dev-123456.okta.com",
    "ClientId": "YOUR_CLIENT_ID",
    "ClientSecret": "YOUR_CLIENT_SECRET"
  }
}
How to get configuration values
  1. Log in to the Okta Admin Console.
  2. Go to Applications > Create App Integration.
  3. Select OIDC - Web Application.
  4. Sign-in redirect URI: https://your-api.com/api/auth/okta/callback
  5. Copy Client ID and Client Secret.

Step 4: Configure endpoint​

Broker endpoints are mapped by app.MapPrimusAuthBroker().

  • GET /api/auth/providers
  • GET /api/auth/okta
  • GET /api/auth/me

Step 5: Test the endpoint​

  1. Call GET /api/auth/providers once on app startup to seed the CSRF cookie.
  2. Navigate to GET /api/auth/okta and sign in.
  3. Call GET /api/auth/me to confirm the session.

SAML 2.0 SSO​

Okta supports both OIDC and SAML 2.0. SAML is common for workforce identity federation.

Create a SAML app in Okta​

  1. In the Okta Admin Console, go to Applications → Create App Integration.
  2. Select SAML 2.0.
  3. Set the Single sign-on URL (ACS) to: 
    https://app.example.com/api/auth/saml/okta-saml/Acs
  4. Set Audience URI (SP Entity ID) to https://app.example.com.
  5. Under App embed link, copy the Identity Provider metadata URL.

Configure appsettings.json​

{
  "PrimusAuth": {
    "Saml": {
      "EntityId": "https://app.example.com",
      "IdentityProviders": [
        {
          "Scheme": "okta-saml",
          "DisplayName": "Okta Workforce",
          "IdpType": "Okta",
          "MetadataUrl": "https://dev-123456.okta.com/app/abc123/sso/saml/metadata"
        }
      ]
    }
  }
}

SAML endpoints​

EndpointDescription
GET /api/auth/saml/okta-samlReturns SP metadata XML — configure as the SP Entity ID in Okta
GET /api/auth/saml/okta-saml/SignInInitiates SP-initiated SSO — redirects the browser to Okta
POST /api/auth/saml/okta-saml/AcsAssertion Consumer Service — handled automatically

Advanced features​

The following features work with Okta exactly the same way as any other provider:

Next Steps​