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:

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:

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

​

Azure

• 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

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:

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:

​

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:

​

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

• Role based authorization