Skip to content
  • There are no suggestions because the search field is empty.

OAUTH Configuration Steps

Step-by-step guide to setting up OAUTH for Innoslate Enterprise.

Innoslate supports OAuth authentication by validating JSON Web Tokens (JWTs) using two cryptographic hashing algorithms: HS256 (HMAC with SHA-256) and RS256 (RSA with SHA-256). These algorithms provide distinct key management and security models to accommodate varying deployment requirements.

  • HS256: Utilizes a shared secret key, manually configured in the settings.properties file.
  • RS256: Employs a public certificate retrieved from a specified URL (e.g., a JSON Web Key Set, or JWKS), supporting certificate rotation for improved security.

Innoslate also supports discovery documents (e.g., OpenID Connect configuration JSON files) to automatically populate key fields in settings.properties, such as AUTHORIZATION_ENDPOINT, JWKS_URI, ISSUER, SCOPE, and TOKEN_ENDPOINT. Manually defined values in settings.properties override discovery document data, and any missing fields can be manually specified.

Configuration Methods

Innoslate offers three methods to configure OAuth authentication, detailed below with examples for the settings.properties file.

1. Discovery Document

This method retrieves OAuth configuration details from a well-known URL.

Properties:
WELL_KNOWN_URL = https://accounts.google.com/.well-known/openid-configuration
  • The JSON object at the specified URL is parsed during Innoslate startup.
  • Changes to the discovery document require an application restart to take effect.

2. Manual Configuration

This method allows explicit definition of all required endpoints and parameters.

Properties:
AUTHORIZATION_ENDPOINT = https://accounts.google.com/o/oauth2/v2/auth
ISSUER = https://accounts.google.com
JWKS_URI = https://www.googleapis.com/oauth2/v3/certs
SCOPE = email profile openid
TOKEN_ENDPOINT = https://oauth2.googleapis.com/token

 

3. HS256 Configuration

This method uses a shared secret key for token verification, ideal for simpler deployments.

Properties:
HS256_SECRET = secret 
 

Example settings.properties with Common Parameters

Properties:
AUDIENCE = 7856705403.apps.googleusercontent.com
AUTHENTICATION_TYPE = OAUTH
CLIENT_ID = 7856705403.apps.googleusercontent.com
CLIENT_SECRET_KEY = <SECRET_KEY>
HOSTED_DOMAIN = specinnovations.com
USERNAME_MAPPING = name
 

Optional OAuth Parameters

Additional parameters can enhance user profile integration or customize authentication behavior:

Properties
OAUTH_COMPANY = company
OAUTH_EMAIL = email
OAUTH_FIRST_NAME = given_name
OAUTH_LAST_NAME = family_name
OAUTH_PHONE_NUMBER = phoneNumber
AUTHENTICATION_HEADER = true
AUTHENTICATION_HEADER_PREFIX = Basic

 

Parameter Definitions

AUDIENCE: The identifier used to verify the token, typically matching the CLIENT_ID.

AUTHENTICATION_HEADER: Enables an authentication header (e.g., for CLIENT_ID and CLIENT_SECRET_KEY) instead of passing them in the request body.

AUTHENTICATION_HEADER_PREFIX: Specifies the header prefix (default: Basic).

AUTHENTICATION_TYPE: Set to OAUTH to enable OAuth authentication.

AUTHORIZATION_ENDPOINT: The URL redirecting users to the authentication provider to obtain an OAuth code.

CLIENT_ID: The identifier for the client application.

CLIENT_SECRET_KEY: A secret key from the authentication provider (e.g., Keycloak) to verify the client’s identity. Keep this confidential.

HOSTED_DOMAIN: The domain hosting the Innoslate application.

HS256_SECRET: The secret key for HS256 token signature verification (required only for HS256).

ISSUER: The authentication provider’s URL, used in token verification.

JWKS_URI: The URL hosting the JSON Web Key Set (JWKS) with certificates for RS256 token verification.

OAUTH_COMPANY: Maps to the user’s company name in their profile (optional).

OAUTH_EMAIL: Maps to the user’s email in their profile (optional).

OAUTH_FIRST_NAME: Maps to the user’s first name in their profile (optional).

OAUTH_LAST_NAME: Maps to the user’s last name in their profile (optional).

OAUTH_PHONE_NUMBER: Maps to the user’s phone number in their profile (optional).

SCOPE: A space-separated list of permissions (e.g., email profile openid) defining Innoslate’s access rights. At least one scope is required.

TOKEN_ENDPOINT: The URL for obtaining the OAuth token from the authentication provider.

USERNAME_MAPPING: Defines the token field(s) used to create the username (e.g., name, email, given_name family_name). Multiple fields are concatenated with a period (e.g., john.doe).

WELL_KNOWN_URL: The URL of the discovery document containing OAuth configuration details, parsed at startup.