REST API: System Integrator's Guide

Web Central implementation

Web Central REST API calls are authenticated using JWT access tokens.

Applications calling Web Central REST API must obtain the access token from their OAuth2 or OpenID Connect identity provider.

Access tokens should:

  • contain claims: sub, expiration, issuer, audience.

  • be signed with a cryptographic key using the JWK (JSON Web Key) standard.

Web Central:

  • does not accept unsigned access tokens.

  • uses "sub" claim as username. This claim name is specified in /WEB-INF/config/oidc.properties file.

  • verifies signature (downloads from IdP and caches public key) and claims: expiration, issuer, audience.

  • uses the jose4j library ( https://bitbucket.org/b_c/jose4j/wiki/Home ) to implement token verification.

REST APIs are hosted on a separate, dedicated instance of Tomcat. This instance has a different URL (for example, https://archibus-worker.serranew.com/archibus/ ), and does not handle requests from web UI clients, mobile clients, or Smart Client . The same instance runs scheduled workflow rules.

API requests are encrypted using TLS (HTTPS).

API parameters are validated. Each parameter has a type, such as string, number, JSON array. The Java implementation validates the types and rejects invalid values.

Example Values of WEB-INF/config/oidc.properties

Site-configurable properties for OIDC SSO configuration are:

oidc.projectId=hq-sqlserver

  • If autoCreateUserAccount is true, if user account does not exist, WebCentral creates user account with values specified in request header and here.

    • oidc.autoCreateUserAccount=true

  • The values for auto-created UserAccount are expected to come from:
    • email - request header
    • role - this file
    • homePage - this file

  • Keys for values to be extracted from the request header. The values will be used to create user account.

  • oidc.emailKey=email

  • oidc.roleKey=role

  • oidc.homePageKey=homePage

  • The values below will be used to create user account. The values below are used if those values are not supplied in the request header.

    • oidc.role=4 - API USER

    • oidc.homePage=navigator-details.axvw

oidc.usernameClaim=sub

oidc.audience=api://default

oidc.issuer=https://dev-302796.oktapreview.com/oauth2/default

oidc.jwksUrl=https://dev-302796.oktapreview.com/o...efault/v1/keys<<<