Setting up SSO with Okta

This article takes an administrator through the process of setting up SSO with Okta.

Create an app in Okta¶

1. Log in to your Okta Admin portal, e.g. aptecotest.okta.com.
2. Switch to the Applications tab.

3. Click Add Application.

   

4. Click Create New App.

App setup¶

1. For Platform, choose Web. For Sign on method, choose SAML 2.0. Click Create.

   

2. Choose an App name, optional App logo, and set App visibility options, then click Next.

   

   Configure the following fields:

   Field	Value
   Single sign on URL	https://[your-server]/OrbitAPI/ExternalLogin/AssertionConsumerService
   Audience URI (SP Entity ID)	https://AptecoLoginAPI/
   Default RelayState	https://[your-server]/Orbit/external-login
   Name ID format	Unspecified (default, unless the application requires a specific format)
   Application username	Determines the default value for the SAML assertion's subject statement
   Update application username on	Create and update

   Note

   external-login is case-sensitive and will not work if entered in any other case.

3. Click Next.

Certificates¶

1. Make a note of the Identity Provider Single Sign-On URL and Identity Provider Issuer.
2. Click View Setup Instructions to open a new tab showing the URLs and x.509 certificate.

3. Click Download Certificate and save as Okta.cert in the Certificates folder on your web server:

   Text Only

   C:\Program Files (x86)\Apteco\OrbitLoginService\Certificates\Okta.cert
   

Configure the Orbit Login Service¶

See Orbit login service to install and configure the Login Service first.

Edit the Orbit Login Service configuration file with the following JSON, substituting your actual values:

{
  "Serilog": {
    "MinimumLevel": {
      "Default": "Debug",
      "Override": {
        "Microsoft": "Warning",
        "System": "Warning",
        "ComponentSpace.Saml2": "Warning"
      }
    },
    "WriteTo": [
      { "Name": "Trace" },
      {
        "Name": "RollingFile",
        "Args": { "pathFormat": "C:\\temp\\Orbit\\Logs\\OrbitLogin-{Date}.txt" }
      }
    ],
    "Enrich": ["FromLogContext", "WithMachineName", "WithThreadId"]
  },
  "Kestrel": {
    "Endpoints": {
      "Http": { "Url": "http://localhost:5005" }
    }
  },
  "AllowedHosts": "*",
  "SAML": {
    "$schema": "https://www.componentspace.com/schemas/saml-config-schema-v1.0.json",
    "Configurations": [
      {
        "LocalServiceProviderConfiguration": {
          "Name": "https://AptecoLoginApi/",
          "Description": "Apteco Orbit Login API",
          "AssertionConsumerServiceUrl": "https://example.com/OrbitAPI/ExternalLogin/AssertionConsumerService",
          "LocalCertificates": [
            { "FileName": "certificates/sp.pfx", "Password": "password" }
          ]
        },
        "PartnerIdentityProviderConfigurations": [
          {
            "Name": "http://www.okta.com/exkjee2b8slkcYPAk5d5",
            "Description": "Okta",
            "SignAuthnRequest": true,
            "SingleSignOnServiceUrl": "https://dev-8040522.okta.com/app/aptecodev8040522_aptecoorbit_2/exkjee2b8slkcYPAk5d5/sso/saml",
            "PartnerCertificates": [
              { "FileName": "certificates/okta.cert" }
            ]
          }
        ]
      }
    ]
  },
  "PartnerName": "http://www.okta.com/exkjee2b8slkcYPAk5d5",
  "JWT": {
    "Key": "VerySecretAptecoJWTKey",
    "Issuer": "https://AptecoLoginApi/"
  },
  "AllowedReturnUrlOrigins": "https://example.com/"
}

You must provide values in three sections:

Within localserviceproviderconfiguration:

• AssertionConsumerServiceUrl—same value set during SAML configuration, e.g. https://[your-server]/OrbitAPI/ExternalLogin/AssertionConsumerService

Within partneridentityproviderconfigurations:

At root level:

Start (or restart) the Orbit Updater Service to pick up the configuration changes.

Assigning the app to users¶

Before users can access Orbit through Okta, assign the application to them.

1. In the Okta Admin Portal, select the Applications page.
2. Click Assign Users to App.

3. Select the correct application in the left panel and choose the user(s) in the right panel, then click Next.

   

4. Okta defaults to passing its username to the configured application. To override this (e.g. to map an Okta identity to a FastStats username), type the value in the Username field for each user.

5. Click Confirm Assignments.

   

6. The application is now configured for use.

   

Users can now access the application from their User Home page within Okta.