Setting up SSO with Okta

Introduction

Apteco offers single sign-on (SSO) with a few different providers, and this article takes an administrator through the process of getting it setup to use with Okta.

Create your Okta account

You can sign up for an Okta developer account here: developer.okta.com/signup.

Once you have created and verified your Okta account, you can then create the app.

Create app

To create your app in Okta:

  1. Login to your Admin portal, e.g. aptecotest.okta.com.

  2. Switch to the Applications tab.

  3. Click Add Application.

  4. Click Create New App.

You can configure this SSO provider to use OpenID Connect.

This is a much simpler configuration than SAML as it does not require installation of an Orbit login service. See the article Setting up SSO with OpenID Connect for more information. To instead use SAML, follow the steps below.

App setup

To set up your app:

  1. For the Platform, choose Web. For the 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.

  3. Configure the SAML settings.

    • Single sign on URL - the location where the SAML assertion is sent with a HTTP POST. It is often referred to as the SAML Assertion Consumer Service URL.

      e.g. https://<yourWebSite>/OrbitAPI/ExternalLogin/AssertionConsumerService

    • Audience URI (SP Entity ID) - The application-defined unique identifier that is the intended audience of the SAML assertion. This is most often the SP Entity ID of your application.

      e.g. https://AptecoLoginAPI/

    • Default RelayState -Identifies a specific application resource in an IDP Initiated Single Sign-on scenario. This is the location that Okta will redirect authenticated user.

      https://<yourWebSite>/Orbit/external-login

    Note: 'external-login' is case sensitive and will not work unless entered in lower case

    • Name ID format -Identifies the SAML processing rules and constraints for the assertion's subject statement. This should be kept to the default value of 'Unspecified' unless the application explicitly requires a specific format.

    • Application username - Determines the default value for a user's application username. The application username will be used for the assertion's subject statement.

    • Update application username on -Determines when the application username will be updated. There is only a single option of 'Create and update'.

  4. Click Next.

Certificates

You should now see the following in Okta:

  1. Make a note of the Identity Provider Single Sign-On URL, Identity Provider Issuer.

  2. Click on the View Setup Instructions button which will open a new tab showing:

    • Identity Provider Single Sign-On URL

    • Identity Provider Issuer

    • x.509 Certificate

    • Identity Provider metadata

  3. Click Download Certificate and save as Okta.cert in the Certificates folder of the OrbitLoginService on your Web Server.

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

Orbit configuration

How to configure Orbit to use a Login Service.

See Orbit login service.

Configure Orbit Login Service

The Okta settings in the Orbit Login API config file. Where the <> tags are, the settings need to be updated.

Copy 
{
  "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",
          "SingleLogoutServiceUrl": "https://example.com/OrbitAPI/ExternalLogin/SingleLogoutService",
          "LocalCertificates": [
            {
              "FileName": "certificates/sp.pfx",
              "Password": "password"
            }
          ]
        },
        "PartnerIdentityProviderConfigurations": [
          {
            "Name": "http://www.okta.com/exkjee2b8slkcYPAk5d5",
            "Description": "Okta",
            "SignAuthnRequest": true,
            "SignLogoutRequest": true,
            "SignLogoutResponse": true,
            "SingleSignOnServiceUrl": "https://dev-8040522.okta.com/app/aptecodev8040522_aptecoorbit_2/exkjee2b8slkcYPAk5d5/sso/saml",
            "SingleLogoutServiceUrl": "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/"
}

Substitute instances of https://example.com with your own website address.

You must provide URLs within three sections.

Within the 'LocalServiceProviderConfiguration' section

Enter the same values as were set during the SAML configuration.

  • AssertionConsumerServiceUrl

    e.g. https://<yourWebsite>/OrbitAPI/ExternalLogin/AssertionConsumerService

  • SingleLogoutServiceUrl

    e.g. https://<yourWebsite>/OrbitAPI/ExternalLogin/SingleLogoutService

Within the 'PartnerIdentityProviderConfigurations' section

  • Name - The Identity Provider Issuer URL

  • Description - Okta

  • SingleSignOnServiceUrl -The Identity Provider Single Sign-On URL from the SAML 2.0 configuration Metadata

  • SingleLogoutServiceUrl -The Identity Provider Single Sign-On Logout URL from the SAML 2.0 configuration Metadata

  • PartnerCertificates—>FileName -relative path to the Okta certificate created earlier

    e.g. certificiates/okta.cert

  • PartnerName -the Identity Provider Metadata URL

  • AllowedReturnUrlOrigins - the base URL of the website hosting Orbit

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

Assigning the app to users

Before users can begin to access Orbit through Okta, you must assign it to them for access.

  1. When logged into the Okta Admin Portal, select the Applications page.

  2. Click Assign Users to App.

  3. From the left-hand panel, select the correct application and choose the user(s) that will be assigned this application in the right-hand panel, then click Next.

  4. Okta will default to passing through its username to the configured application. If you need to override this e.g. to map an Okta identity to a FastStats username, type this in the Username field for each user.

  5. Click Confirm Assignments.

  6. You will be taken back to the main Applications page, the application is now configured for use.

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

You must now Configure Apteco to use SSO to complete the setup process.