OpenID Connect (OIDC) / Oauth Authentication

Simscope can configured to authenticate users via Oauth 2.0 OpenID Connect (OIDC) for Single Sign-On authentication (aka SSO).

• Overview of the OIDC protocol.
• Note: OIDC and SAML are different authentication protocols (JSON vs XML), and Simscope currently only supports OIDC.

Supported Providers

The current tested providers with Simscope are:

• Okta (with Directory API support)
• Google
  • Google OAuth2 docs
• Microsoft Azure
  • Microsoft Azure Portal

Note: any OIDC-compliant provider should work with Simscope.

• Please contact payton@verops.com if you need to use an alternate OIDC provider.

Directory API

Simscope supports User Provisioning from Okta, using Directory API polling.

This is an optional feature, which allows enabling/disabling of Simscope users from Okta, by adding or removing them from your Okta Simscope Group.

• To enable in Simscope, set the configuration field directoryapi to "okta"
  • Also, you need to get an Okta API token for Simscope to be able to query the directory.
• Currently, directories are refreshed from Simscope once per hour.

Okta App integration instructions

Simscope needs Okta to be configured as an App integration.

To get an Okta Client ID and Client Secret:

→ see Okta App integration.

Issuer: OpenID Discovery Protocol

Simscope uses OpenID Connect Provider Discovery protocol, to automatically configure settings upon connection.

To test that you have a valid domain value, append this to the URL and open inside your browser:

DOMAIN/.well-known/openid-configuration

# For example
https://login.salesforce.com/.well-known/openid-configuration

If the domain is valid, you should get a JSON response similar to this in your browser:

{
  "issuer": "https://login.salesforce.com",
  "authorization_endpoint": "https://login.salesforce.com/services/oauth2/authorize",
  "token_endpoint": "https://login.salesforce.com/services/oauth2/token",
  "revocation_endpoint": "https://login.salesforce.com/services/oauth2/revoke",
  "userinfo_endpoint": "https://login.salesforce.com/services/oauth2/userinfo",
  "jwks_uri": "https://login.salesforce.com/id/keys",
  "registration_endpoint": "https://login.salesforce.com/services/oauth2/register",
  "introspection_endpoint": "https://login.salesforce.com/services/oauth2/introspect",
  "scopes_supported": [
  ...
  ]
}

→ If you want to see an example valid Domain JSON, click here.

Optional: Authorization Server Issuer

If you are using a custom authorization server (instead of the default blank issuer), you can set the issuer field in your config file.

Here is an Okta example, setting the issuer to oauth2/default:

[oidc]
issuer = "oauth2/default"

Refresh Tokens

Oauth normally sends out 60-minute session authentication tokens for users after a successful login.

If you enable refresh tokens, this allows the tokens to be refreshed automatically after they expire, without a login prompt.

It is recommended to enable this for users.

• If using Okta authentication, make sure to enable the offline_access scope to enable refresh tokens. Note that Google authentication does not allow this scope.

Secure Browser Cookies

For the best security with OIDC, Simscope should be run via https.

If https is enabled, the browser cookies used for OIDC authenticaton will be set with additional flags automatically:

• Secure
• Partitioned

OIDC Configuration

Config: clientid and clientsecret

Simscope requires an application clientid and clientsecret to connect to the OIDC server, in order to authenticate users.

Each OIDC provider will issue these when you register Simscope as a client.

Prompt

OIDC uses a prompt configuration option, to configure the User Login Prompt.

Each provider has different allowed values, but here are some common choices:

OIDC configuration file

Note: replace the UPPERCASE fields with your OIDC (ie Okta) configuration.

[oidc]
# NOTE: the Domain is also called Provider Issuer URL
# Common examples:
# domain = "https://COMPANY.okta.com"
# domain = "https://accounts.google.com"
# domain = "https://login.salesforce.com"

# Azure
# domain = "https://login.microsoftonline.com/{TENANT_ID}/v2.0"

domain = "https://COMPANY.okta.com"
# Or alternatively via Okta developer domain
#domain = "https://dev-12345.okta.com"

# Optional: Authorization Server Issuer URL
# Example:
#issuer = "oauth2/default"

# Client ID (issued by your provider)
clientid = "YOUR_APP_CLIENTID"
# Client Secret (issued by your provider)
clientsecret = "YOUR_APP_CLIENTSECRET"

# Optional: change OIDC scopes
# scopes = "openid"
# scopes = "profile"
# scopes = "email"
# scopes = "offline_access" # for auto-renewal of tokens

# Optional: require login consent.  Some providers require this set, to return refresh_tokens
prompt = "consent"

# Optional: use the OIDC user email address as username field (to prevent blank usernames).
# (needed for OIDC providers like Google, which do not have a separate username field)
#linkemailusername = true

# NOTE: comment the following out, unless using Okta provider

# Optional but recommended: if using a Directory API (user management).
# Directory API enables remote provisioning of Simscope user accounts.
# This allows you to add or remove users from Okta groups, and Simscope will automatically
# refresh its user directory once per hour.
directoryapi = "okta"

# Note: if using Okta, create an Okta API token from this URL:
# > https://COMPANY-admin.okta.com/admin/access/api/tokens

apitoken = "MY-OKTA-APITOKEN"

Workflow: Integrating OIDC within Simscope

To use OIDC within Simscope:

1. Get the oidcapp test app working.
2. Copy the OIDC configuration used in oidcapp into your simscope.config file.
3. In your simscope.config file, make sure the serverurl variable is the BASE_URL of your Simscope address.

[server]
serverurl = "https://simscope.company.com"

4. When Simscope starts, check that the terminal line redirect-uri matches your OIDC (Okta) Redirect URI configuration. Here is an example:

[INFO ] OIDC User Authentication enabled redirect-uri=https://simscope.company.com/oidc-callback

Admin account access

When OIDC is enabled in Simscope, this disables all LDAP and local user accounts, except for the admin account.

The admin account is a failsafe local account in Simscope, which can always be logged in.

• In case your OIDC provider goes out, you can always still log into Simscope locally via your admin credentials.
• If you forget or lose the admin password, you can reset the admin account password.