# Setting up single sign-on with Okta

This article takes an administrator through the process of setting up Single Sign-On (SSO) with Okta. It uses Security Assertion Markup Language (SAML) for authentication.

## 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. Select **Add Application**.
4. Select **Create New App**.

## App setup

1. For **Platform**, choose **Web**. For **Sign on method**, choose **SAML 2.0**. Select **Create**.
2. Choose an **App name**, optional **App logo**, and set **App visibility** options, then select **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 won't work if entered in any other case.
3. Select **Next**.

### Certificates

1. Make a note of the **Identity Provider Single Sign-On URL** and **Identity Provider Issuer**.
2. Select **View Setup Instructions** to open a new tab showing the URLs and x.509 certificate.
3. Select **Download Certificate** and save as `Okta.cert` in the Certificates folder on your web server:

   Text Only

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

## Configure the Orbit Login Service

See [Orbit login service](<https://help.apteco.com/en/admin/configuration/single-sign-on/login-service/index.md>) to install and configure the Login Service first.

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

JSON

```json
{
  "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`:**

| Field | Value |
| --- | --- |
| `Name` | The Identity Provider Issuer URL |
| `Description` | `Okta` |
| `SingleSignOnServiceUrl` | The Identity Provider Single Sign-On URL from the SAML 2.0 configuration metadata |
| `PartnerCertificates.FileName` | Relative path to the Okta certificate (e.g. `certificates/okta.cert`) |

**At root level:**

| Field | Value |
| --- | --- |
| `PartnerName` | The Identity Provider Metadata URL |
| `AllowedReturnUrlOrigins` | The base address of the website hosting Orbit |

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. Select **Assign Users to App**.
3. Select the correct application in the left panel and choose the users in the right panel, then select **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. Select **Confirm Assignments**.
6. The application is now configured for use.

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