Basic application integration

    Overview

    This document describes how to achieve the simplest form of integration of an Application with Chemaxon Cloud: single sign-on (SSO).

    A successful integration consists of 2 main parts:

    • Application implements the required code changes
    • Application is registered in Chemaxon Cloud

    {info} Chemaxon Cloud uses Okta for IAM (Identity and Access Management).

    {info} Chemaxon Cloud uses the OpenID Connect (OIDC) protocol to handle both authentication and authorization.

    High level overview

    1. Application is prepared for integration with Chemaxon Cloud
      • Application MUST be ready to use Okta via OIDC for authentication and authorization
      • Application MAY want to use metadata included in the ID and access tokens obtained via OIDC, to make authorization decisions
      • Application MUST provide app-info metadata endpoint to be consumed by Chemaxon Cloud
    2. Application is registered under a Team in Chemaxon Cloud
      • Requires the app-info metadata provided by Application to be accessible

    Integration results

    1. SSO is functional across Chemaxon Cloud and Application
    2. Token metadata can be used to make authorization decisions in Application

    Detailed overview

    To better understand what we want to achieve, we should expand the above steps a bit more:

    1. Chemaxon Cloud System Administrator pre-registers application under a Team in Chemaxon Cloud
    2. Chemaxon Cloud System Administrator sends client_id and client_secret to application development team
    3. Application development team implements/configures integration with the Okta OAuth Authorization Server used by Chemaxon Cloud
    4. Application exposes app-info endpoint
    5. Application is deployed with correct Okta integration and app-info endpoint
    6. Application development team sends the URI for the application app-info endpoint to Chemaxon Cloud System Administrator
    7. Chemaxon Cloud System Administrator configures the pre-registered application in Chemaxon Cloud with the app-info endpoint URI received from application development team
    8. Chemaxon Cloud System Administrator triggers fetching of Application metadata from app-info endpoint
    9. Chemaxon Cloud System Administrator finishes application registration
    10. Application can be accessed by members of the Chemaxon Cloud Team under which the Application was registered

    Architecture

    Obtaining app-info

    Login / logout

    Step-by-step instructions

    1. Application is prepared for basic integration with Chemaxon Cloud

    Prerequisites

    Important Chemaxon Cloud URIs
    Name URI
    Chemaxon Cloud base URI https://cloud.chemaxon.com/
    Okta OAuth Authorization Server URI https://auth.cloud.chemaxon.com/oauth2/aus3qkblpwzIDQBJF417
    Okta OAuth Authorization Server Metadata URI https://auth.cloud.chemaxon.com/oauth2/aus3qkblpwzIDQBJF417/.well-known/oauth-authorization-server

    Implementing Okta OIDC integration

    To provide a consistent login User Experience and SSO capability, Chemaxon Cloud relies on the "Okta redirect authentication model".

    {warning} Chemaxon Cloud only supports integrating: server-side web applications; SPAs that rely on their own backend for handling authentication.

    {warning} Chemaxon Cloud currently does NOT support integrating: SPAs where authentication would be handled by client side code directly interacting with Okta.

    Exact implementation depends on the technologies used by the Application. Please refer to the appropriate documentation in Okta:

    Configuration examples
    Spring Boot

    Example of Oauth Client configuration - token, authorization, and JWKS URI:

    security.oauth2:
  client:
    clientId: <yourClientID - obtain from Chemaxon>
    clientSecret: <yourClientSecret - obtain from Chemaxon>
    accessTokenUri: https://auth.cloud.chemaxon.com/oauth2/aus3qkblpwzIDQBJF417/v1/token
    userAuthorizationUri: https://auth.cloud.chemaxon.com/oauth2/aus3qkblpwzIDQBJF417/v1/authorize
    scope:
      - openid
      - profile
      - email
      - offline_access
  resource:
    jwk.key-set-uri: https://auth.cloud.chemaxon.com/oauth2/aus3qkblpwzIDQBJF417/v1/keys
    Node Express

    Example of passport-openidconnect configuration:

    {
  "issuer": "https://auth.cloud.chemaxon.com/oauth2/aus3qkblpwzIDQBJF417",
  "authorizationURL": "https://auth.cloud.chemaxon.com/oauth2/aus3qkblpwzIDQBJF417/v1/authorize",
  "tokenURL": "https://auth.cloud.chemaxon.com/oauth2/aus3qkblpwzIDQBJF417/v1/token",
  "userInfoURL": "https://auth.cloud.chemaxon.com/oauth2/aus3qkblpwzIDQBJF417/v1/userinfo",
  "clientID": "${yourClientID - obtain from Chemaxon}",
  "clientSecret": "${yourClientSecret - obtain from Chemaxon}",
  "callbackURL": "http://localhost:3000/authorization-code/callback",
  "scope": "openid profile email offline_access"
}

    {info} The offline_access scope is optional, and results in a refresh token being issued by Okta.

    Implementing authorization logic based on token metadata

    For details about custom claims included in Okta tokens, and about the scopes required for them to be included, please refer to Custom Claims in Okta tokens.

    {warning} Certain scopes are required for these custom claims to be included in the tokens, please make sure to request the appropriate scopes.

    Based on these custom claims, your application should be able to make access control and authorization decisions, as needed.

    Implementing the app-info endpoint

    The response of the endpoint should adhere to the specification according to sf-001-application-info.

    {warning} Two features are especially important to include in the response: synergy/login and synergy/logout.

    • synergy/login - Callback URL to add to the "Sign-in redirect URIs" allowlist in Okta
    • synergy/logout - Callback URL to add to the "Sign-out redirect URIs" allowlist in Okta

    These are necessary to ensure that the required configuration changes in Okta can be made by Chemaxon Cloud, so that Login/Logout initiated in the Application works.

    {info} Sign-in redirect URI: The sign-in redirect URI is where Okta sends the authentication response and ID token for the sign-in request. (The URI must be absolute URI.)

    {info} Sign-out redirect URI: After your application contacts Okta to close the user session, Okta redirects the user to this URI. (The URI must be absolute URI.)

    {info} Source: Okta Help Center / Create OIDC app integrations / Task 2: Configure initial settings

    Example request/response
    GET https://example-application.com/api/app-info
    {
  "displayName": "Example Chemaxon Cloud app",
  "address": "https://example-application.com/",
  "identities": [{ "category": "application", "type": "web" }],
  "features": [
    {
      "namespace": "synergy/health",
      "attributes": {
        "url": "https://example-application.com/api/health"
      }
    },
    {
      "namespace": "synergy/icon",
      "attributes": {
        "url": "https://example-application.com/app-icon.svg"
      }
    },
    {
      "namespace": "synergy/login",
      "attributes": {
        "url": "https://example-application.com/authorization-code/callback"
      }
    },
    {
      "namespace": "synergy/logout",
      "attributes": {
        "url": "https://example-application.com/logout"
      }
    }
  ]
}

    2. Application is registered under a Team in Chemaxon Cloud

    Prerequisites

    • Application development team provides app-info endpoint URI to Chemaxon Cloud System Administrator.

    Application registration

    Please refer to System Administrator guide on Registering Applications.