Okta

The Okta Connector provides a way for Maverics to interact with an Okta organization. The Connector uses the Okta User API to create users or query for attributes and OpenID Connect to authenticate users and perform session validation.

Configuration options

The following values can be provided to the Okta Connector via the Maverics configuration file.

Auth Type

authType defines the protocol used to authenticate against Okta. The Okta connector supports both saml or oidc for user authentication. When not defined, a default of oidc is used.

OIDC Well-known URL

oidcWellKnownURL defines the location at which the client requests configuration from Okta's OpenID Provider.

OAuth Client ID

oauthClientID defines the client ID used to identify the Maverics application to Okta.

OAuth Client Secret

oauthClientSecret defines the client secret used to authenticate the Maverics application with Okta.

OAuth Login Redirect

oauthLoginRedirect is used to define login redirect callback URLs.

It defines the urls that the OIDC provider will use to redirect the client back to after authentication. The urls must be absolute URLs and match exactly with one of the registered URLs on the provider. If no matches are found during the auth flow, the first URL from the urls list will be used.

The orchestrator will serve the callback handlers on all URLs specified in the urls field under this section.

The urls paths should not conflict with the path of any application resources. The path can be arbitrary (e.g. /maverics-oidc or /oidc-handler).

OAuth Logout Redirect

oauthLogoutRedirect is used to define urls that an OIDC provider will use to redirect the client back to the application after logging out the user.

The urls must be absolute URLs and match exactly with one of the registered URLs on the provider. If no matches are found during the logout flow, the first URL from the urls list will be used.

The orchestrator will serve the callback handlers on all URLs specified in the urls field under this section.

The urls paths should not conflict with the path of any application resources. The path can be arbitrary (e.g. /oidc-logout or /logout-handler).

Disable PKCE

disablePKCE is an optional field used to disable the OIDC Proof Key for Code Exchange (PKCE) extension (enabled by default).

OIDC Scopes

scopes is an optional field that defines the scopes which are requested as part of the OIDC authentication flow. The scopes should be delimited with a space character. If not defined, a defaults of openid profile email are used.

SAML Entity ID

samlEntityID is the unique application entity ID assigned to the application.

SAML Metadata URL

samlMetadataURL is the metadata URL from the application configured in the SAML provider. The samlMetadataURL setting will accept a file:/// URI if the metadata file is saved on a filesystem accessible to the Orchestrator user.

SAML Consumer Service URL

samlConsumerServiceURL is the URL that the SAML provider will use to POST the SAML response back to. The Maverics SAML ACS handler will be served on this URL, as such it should not conflict with the path of any application resources. The samlConsumerServiceURL path can be arbitrary (e.g. /maverics-saml or /saml-handler), but must match the provider's configuration for the specified samlEntityID.

SAML Logout Callback URL

samlLogoutCallbackURL is an optional field used to define the URL to which the SAML provider will call back once logout is successful. This will initialize an endpoint on Maverics to listen for the callback. The URL's domain must match the domain Maverics is on. The samlLogoutCallbackURL path can be arbitrary (e.g. /logout-maverics-saml or /logout-saml-handler), but must match the provider's configuration for the specified samlEntityID.

SAML SP Cert Path

samlSPCertPath is an optional configuration to the path to the certificate that will be used to sign SAML authentication requests. Must be used with samlSPKeyPath.

SAML SP Key path

samlSPKeyPath is an optional configuration to the path to the private key that will be used to sign SAML authentication requests. Must be used with samlSPCertPath.

IDP-Initiated Login

samlIDPInitiatedLogin is an optional field used to define the IDP-initiated login settings.

Enabled

enabled defines whether the connector will accept unsolicited SAML responses from the configured IDP. IDP-initiated login is disabled by default as it is inherently less secure than the alternative SP-initiated flow.

Allowed Redirect URLs

allowedRedirectURLs are the set of URLs that the connector can redirect to after processing an IDP-initiated SAML response. The IDP must pass one of the listed URLs via the relay state when it initiates a login. For more info on why a set of URLs are required, please see the OWASP guide on IdP Initiated SSO and the importance of mitigating the Open Redirect attack.

API Token

apiToken is the token used to authenticate the Maverics client with the Okta API.

The okta.users.manage and okta.users.read API Scopes must be granted on the registered application in order to interact with the Okta API.

Domain

domain is the URL of your Okta tenant. For example, https://yourtenant.okta.com. This field is required in order to interact with the Okta API.

Error Page

errorPage is the page presented to users if an error occurs.

Cache

cache is an optional field that defines the cache settings for the connector. If left undefined, the connector will use the default in-memory cache.

Cache is currently only supported for SAML connectors.

Health Check

healthCheck defines an optional health check for the connector. This option is required when using the connector in an IDP-continuity scenario. For more info on how to define the health check, please see the docs.

Examples

OIDC Connector Configuration

connectors:
  - name: oktaIDP
    type: okta
    authType: oidc
    oidcWellKnownURL: https://yourtenant.okta.com/.well-known/openid-configuration
    oauthClientID: <okta-client-id>
    oauthClientSecret: <okta-client-secret>
    oauthLoginRedirect:
      urls:
        - https://host1.example.com/oidc
        - https://host2.example.com/oidc
    oauthLogoutRedirect:
      urls:
        - https://host1.example.com/logout
        - https://host2.example.com/logout
    disablePKCE: false
    scopes: openid profile email okta.users.read
    errorPage: https://example.com/error-401.html

SAML Connector Configuration

connectors:
  - name: okta
    type: okta
    authType: saml
    samlMetadataURL: https://yourtenant.okta.com/app/1234/sso/saml/metadata
    samlConsumerServiceURL: https://example.com/saml/acs
    samlLogoutCallbackURL: https://example.com/saml/logout
    samlEntityID: https://example.com
    samlSPCertPath: /etc/maverics/certs/example.com.crt.pem
    samlSPKeyPath: /etc/maverics/certs/example.com.key.pem
    samlIDPInitiatedLogin:
      enabled: true
      allowedRedirectURLs:
        - https://example.com
    cache: redis

Attribute Provider Configuration

connectors:
  - name: oktaAttrProvider
    type: okta
    apiToken: <oktaAPIToken>
    domain: https://yourtenant.okta.com