Deploying Orbital

Enabling authentication

Overview

Orbital supports authentication through:

  • An OpenID Connect authentication service, via the Authorization Flow with PKCE pattern.

OR

  • SAML Identity Provider which performs authentication and passes the user’s identity and authorization level to the service provider

OpenID Connect Setup

To enable OpenId Connect Authentication, pass the following config options to Orbital on the command line:

ParameterSample valuesDescription
vyne.security.openIdp.enabledtrue / false (default)Set to true to enable OpenId Connect Authentication.
vyne.security.openIdp.issuerUrlhttps://auth-service/auth/realms/orbitalThe openIdp issuer endpoint. The browser will redirect to this endpoint, so ensure the DNS entry is accessible via browser traffic
vyne.security.openIdp.clientIdorbitalThe client id to present to OpenID server. Defaults to orbital if not provided.
vyne.security.openIdp.jwks-urihttps://auth-service/certsA url to load the set of JWK’s used to verify signatures of presented tokens. This url is called by Orbital’s server, so ensure that the DNS entry is accessible to Orbital
vyne.security.openIdp.require-httpstrue (default) / falseIndicates if auth must be performed over https. Defaults to true
vyne.security.openIdp.account-management-urlhttps://auth-service/accountOptional. A url where authenticated users may be redirected, to manage their account
vyne.security.openIdp.org-management-urlhttps://auth-service/orgOptional. A url where authenticated users may be redirected, to manage their organisation. Generally, this is where roles are assigned to users.

A typical docker config might look as follows:

  vyne:
    image: orbitalhq/orbital:${ORBITAL_VERSION}
    volumes:
      - ./vyne-config:/opt/service/config
    environment:
      OPTIONS: >-
        --vyne.security.openIdp.enabled=true
        --vyne.security.openIdp.jwks-uri=http://keycloak-server/realms/orbital/protocol/openid-connect/certs
        --vyne.security.openIdp.issuerUrl=http://keycloak-server/realms/orbital
        --vyne.security.openIdp.clientId=orbital

When a user attempts to access Orbital, they will be redirected to the login page as configured with the OpenId connect provider.

Orbital doesn’t provide a UI for managing users or roles, it’s expected this is handled through the OIDC service.

The presented JWT

The presented JWT is expected to have the following attributes:

ClaimRequiredDescription
subrequiredSubject - Identifier for the End-User at the Issuer.
issrequiredIssuer - the OIDC provider who authenticated the user
One of preferred_username or first_name and last_namerequiredShorthand name by which the End-User wishes to be referred to at the RP, such as janedoe or j.doe.
One of email or clientIdrequiredSomething that uniquely identifies the user
One of picture or picture_urloptionalThe users avatar
nameoptionalEnd-User’s full name in displayable form including all name parts, possibly including titles and suffixes, ordered according to the End-User’s locale and preferences.

Additionally, role information must be present. See the docs on Authorization for more information.

Configuring OpenID Providers

Keycloak

Keycloak is the default IDP (it’s what the Orbital team tests with), so requires the least configuration.

# Set to true to enable Auth
--vyne.security.openIdp.enabled=true
--vyne.security.openIdp.clientId=orbital

# The url that the browser will redirect to for authentication.
# Ensure this is accessible from browsers
--vyne.security.openIdp.issuerUrl=http://keycloak-server/realms/orbital

# The url that Orbital will connect to, to validate the JWT's presented.
# Ensure this is accessible from the Orbital server
# This normally follows the convention of ${issuerUrl}/protocol/openid-connect/certs
--vyne.security.openIdp.jwks-uri=http://keycloak-server/realms/orbital/protocol/openid-connect/certs

AWS Cognito

The following instructions step through configuring AWS Cognito using AWS Console. These docs aren’t intended to be exhaustive around AWS Congito - refer to AWS for more detailed instructions.

Preparing AWS Congito

  1. Create an AWS Cognito User pool, and users (if not already present)
    • Take note of the User Pool Id.
  2. Create an App Integration, and click to create an App Client:
    • Under App Client:
      • Create a Public Client
      • Don’t generate a client secret
      • Under “Authentication Flows”, ensure that the ALLOW_USER_PASSWORD_AUTH flow is selected
    • Under Hosted UI Settings:
      • Specify the callback URL of where you’re running Orbital. (For testing, you can additionally add localhost here too)
      • For OAuth 2.0 Grant types, ensure “Authorization code grant” is selected
      • For OIDC Connect scopes, ensure email, openid and profile are selected
    • Click Create app client
  3. Take note of the Client Id, which you’ll need in the next step

Configuring Orbital

Use the following config settings in Orbital:

# Set to true to enable Auth
--vyne.security.openIdp.enabled=true
# Replace YOUR_CLIENT_ID with the clientId noted earlier
--vyne.security.openIdp.clientId=YOUR_CLIENT_ID

# In the below, replace REGION and USER_POOL_ID accordingly
# Eg: https://cognito-idp.eu-west-2.amazonaws.com/eu-west-2_xxxxx
--vyne.security.openIdp.issuerUrl=https://cognito-idp.REGION.amazonaws.com/USER_POOL_ID
--vyne.security.openIdp.jwks-uri=https://cognito-idp.REGION.amazonaws.com/USER_POOL_ID/.well-known/jwks.json
# Use the scopes openid email profile
--vyne.security.openIdp.scope="openid email profile"
# Must be set to Id
--vyne.security.openIdp.identity-token-kind=Id

Don't forget!

You must also configure AWS Cognito role based access control

Azure

Azure AD B2C Not Supported

Unfortunately, at this time Azure AD B2C is not supported, as it does not provide support for exposing roles in the published JWT.

However, Azure Active Directory (Entra) is supported, as described below.

  • Log into Azure, and ensure you have an Azure AD directory active (not an Azure AD B2C directory)
  • Navigate to Microsoft Entra ID, and select “App registrations” from the left navbar
  • Click “New Registration” in the top navbar
  • Provide a name for the application - eg: “Orbital”
  • For the Redirect URI, select Single-Page Application, and paste the URL of where Orbital is hosted. (eg: https://mycompany/orbital)
  • Click Register

You are taken to the settings for your newly created Azure AD application

  • Click “Overview” in the left Navbar.
    • Take note of the Application (client) ID - you’ll need this shortly
  • From the top navbar, select “Endpoints”
    • Take note of the OpenID Connect metadata document value - you’ll need this shortly.
    • It should look like this: https://login.microsoftonline.com/YOUR-APP-ID/v2.0/.well-known/openid-configuration

Don't forget!

You must also configure Azure role based access control

Launch Orbital passing the following parameters:

--vyne.security.openIdp.enabled=true

## Use the URL copied above
--vyne.security.openIdp.oidcDiscoveryUrl=https://login.microsoftonline.com/YOUR-APP-ID/v2.0/.well-known/openid-configuration
## Use the ClientId copied above
--vyne.security.openIdp.clientId=xxxxx
--vyne.security.openIdp.scope="openid profile email"
--vyne.security.openIdp.identity-token-kind=Id
## These relate to RBAC, after following the docs for enabling RBAC with Azure
--vyne.security.open-idp.roles.format=path
--vyne.security.open-idp.roles.path=roles

Other IDP's

In general, Orbital supports OpenID Connect authentication and authorization, and should be compatible with most platforms that implement OIDC protocol. Orbital uses the Authorization Code + PKCE flow.

The following parameters (passed to Orbital on startup) are used to configure OpenID Connect support:

ParameterDescription
vyne.security.openIdp.enabledSet to true to turn on support for OIDC
vyne.security.openIdp.client-idThe ClientId as set by the OIDC provider.
vyne.security.openIdp.issuer-urlSets the issuerUrl, as provided by the OIDC provider.
vyne.security.openIdp.oidc-discovery-urlSets where the OpenID discovery document is loaded from. If not provided, will default to ${issuerUrl}/.well-known/openid-configuration, which is the convential url, and normally ok.
vyne.security.openIdp.scopeOptional The OIDC scopes to be requested. Defaults to openid profile email offline_access. Changing this will affect the claims presented in the JWT, which may affect Oribtal’s ability to read the token
vyne.security.openIdp.require-httpsOptional Defines if requests must be made over https. Defaults to true
vyne.security.openIdp.identity-token-kindOptional Either Access (default) or Id. Defines which token the browser should present to Orbital after authentication by the IDP. The token should contain the required claims
vyne.security.openIdp.account-management-urlOptional Provides a url that is presented to the user within the UI to manage their account

For most scenarios, you need to set either the issuer-url or oidc-discovery-url, but not both. However, if your OIDC provider uses non-standard configuration, both may be required.

Troubleshooting OpenID

Ensure DNS entries are accessible

When testing with Docker / k8s, it’s common to be accessing the browser via localhost, but services are operating in a different, isolated DNS networks. Pay particular attention to the two following settings, which are accessed in different contexts:

ParameterDescription
vyne.security.openIdp.issuerUrlRedirected from the browser. If you’re running keycloak (or similar), localhost is possibly ok here.
vyne.security.openIdp.jwks-uriRequested from the Orbital server. If both Orbital and your IDP (eg Keycloak) are running within Docker, make sure you use a DNS entry that is accessible to Orbital. (ie., localhost is unlikely to work here)

SAML Authentication

SAML stands for Security Assertion Markup Language. It is an XML-based open-standard for transferring identity data between two parties: an identity provider (IdP) and a service provider (SP).

  • Identity Provider — Performs authentication and passes the user’s identity and authorization level to the service provider.

  • Service Provider — Trusts the identity provider and authorizes the given user to access the requested resource.

To configure Orbital as a Service Provider and authenticate users against a SAML Identiy Provider, pass the following config options to Orbital on the command line:

ParameterSample valuesDescription
vyne.security.saml.enabledtrue / false (default)Set to true to enable SAML Authentication.
vyne.security.saml.keyStorePath/opt/service/orbital/saml.jksSAML protocol requires signing various SAML protocol messages. This is the full path of corresponding key store accessible by Orbital. Please note that, If the key store file does not exists at the specified location, Orbital will create the key store for you.
vyne.security.saml.keyStorePasswordorbitalPassword for your key store
vyne.security.saml.privateKeyPasswordorbitalPassword for your private key contained in the key store.
vyne.security.saml.idpMetadataFilePath/opt/service/orbital/saml-idp-metadata.xmlFull path of your SAML Idp metadata xml. The path should be accessible by Orbital.
vyne.security.saml.serviceProviderEntityIdhttp://foo.orbitalhq.ioService Provider Entity Id of the Orbital.
vyne.security.saml.callbackBaseUrlhttp://foo.orbitalhq.ioOrbital URL which is accessible by SAML Idp.
vyne.security.saml.serviceProviderMetadataResourcePath/opt/service/orbita/sp-metadata.xmlFull path of the service provider metadata xml file, This file will be generated automatically by the Orbital!
vyne.security.saml.maximumAuthenticationLifetime3600Once you have an authenticated web session on the Identity Provider, usually it won’t prompt you again to enter your credentials and it will automatically generate a new assertion for you. By default, the SAML client will accept assertions based on a previous authentication for one hour. If you want to change this behavior, set the maximumAuthenticationLifetime parameter.

Example SAML Setup with Okta

  • To begin, you’ll need an Okta developer account. You can create one at developer.okta.com/signup or install the Okta CLI and run okta register.
  • Log in to your Okta account and go to Applications > Create App Integration. Select SAML 2.0 and click Next. Name your app something like OrbitalSaml and click Next
  • Assuming the Orbital will be running on your local with its default port. Set the Single sign-on URL as
http://localhost:9022/saml?client_name=SAML2Client
  • Use Single sign-on Url for Recipient URL and Destination URL.

  • Set Audience URI (SP Entity ID) to http://okta-sample.orbital.io

  • Click on Next

  • Set App type to This is an internal app that we have created

  • Okta will create your app, and you will be redirected to its Sign On tab. Scroll down to the SAML Signing Certificates and go to SHA-2 > Actions > View IdP Metadata. You can right-click and copy this menu item’s link or open its URL. Copy the resulting link to your clipboard. It should look something like the following:

  • Save the View Idp Data to a patch that is accessible to Orbital, you’ll set the value of vyne.security.saml.idpMetadataFilePath configuration value.

  • Go to your app’s Assignment tab and assign access to the Everyone group.

  • Here is the list of orbital arguments for your setup:

    --vyne.security.saml.enabled=true
    --vyne.security.saml.keyStorePath=/opt/serviuce/orbital/saml.jks
    --vyne.security.saml.keyStorePassword=orbital
    --vyne.security.saml.privateKeyPassword=orbital
    --vyne.security.saml.idpMetadataFilePath=/op/service/orbital/okta-idp-metadata.xml
    --vyne.security.saml.serviceProviderEntityId=http://okta-sample.orbital.io
    --vyne.security.saml.callbackBaseUrl=http://localhost:9022
    --vyne.security.saml.serviceProviderMetadataResourcePath=/opt/service/orbital/sp-orbital-metadata.xml
    

See also

Previous
Managing secrets
Next
Authorization within Orbital