ScopeAR has implemented Our CMS now supports API Authentication via Identity Provider (IDP) JSON Web Token for companies that use Single Sign-On (SSO) for user authentication instead of the default CMS API login. This is an OAuth2.0 standard called RFC 9068. RFC 9068 enables organizations to securely access the ScopeAR Worklink API using their own self-issued tokens instead of relying on tokens issued by ScopeAR.
This provides greater control over how systems and users authenticate with the Worklink API, allowing organizations to leverage their existing identity management and security protocols.
With this feature, users can use their IDP’s access token directly when interacting with the CMS API, bypassing the usual CMS login process. This is particularly helpful if companies have custom integrations or scripts accessing our CMS.
The feature is compatible with IDPs that support Oauth (OpenID) (e.g., Auth0) or Microsoft Azure SSO. Below is a guide on how company admins can enable and configure this feature based on their IDP type.
Key Benefits of Using Self-Issued Tokens
...
You can use the following instructions to set up JSON Web Token API Auth.
Step 1: Go to Company Info page and access the SSO tab
Click on the “Edit” icon of your SSO provider or “Add SSO Provider”
...
Step 2: Create an SSO Integration
Use the following link to setup your SSO integration: https://help.scopear.com/hc/en-us/articles/10775534184205-CMS-Edit-SSO-Single-Sign-On
Step
...
3: Enable API Authentication via JSON Web Token
Click on the toggle to enable the feature.
Step
...
4: Fill in the Audience field
This is an identifier (usually a URL or unique string) that the access token is intended for. It tells the CMS API that the token was issued for this specific audience, ensuring the token’s validity for our system.
This step is necessary. Every Oauth2 integration has it’s own audience. If you want to have multiple audiences, you will need to create multiple SSO integrations.
Step
...
5 (Optional): Change the Valid Algorithms
Specify which encryption algorithms are valid for your tokens. Enter them as a comma-separated list (e.g.,
RS256, ES256). This helps ensure that only tokens with trusted encryption are accepted.This is the encryption algorithm used to encrypt the JSON Web Token. By default it is set RS256 which is the standard.
Step
...
6 (Optional): Add JSON Web Key Set Endpoint
The JWKS (JSON Web Key Set) endpoint is used to fetch public keys that validate the token's signature. By default, this is taken from the OpenID discovery endpoint, but you can specify an alternative if needed.
The JSON Web Key Set Endpoint (JWKS URI) can be automatically retrieved from the IdP’s discovery URL (typically the
.well-knownendpoint). However, this endpoint can also be manually set with this field.
Step
...
7 (Optional): Add Validation Key
If you have a specific public key you want to use, enter it here. This is useful if your IDP provides a unique key that doesn’t change or if you need a specific encoded key for validation.
The Worklink API verifies access token signatures using a public key. This public key is automatically retrieved from the
jwks_uriendpoint. However, the public key can be manually set by placing the key into this field.
Note: Currently, only access tokens following the RFC 9068 JWT Profile are supported for Oauth providers.
...
Configuration for Azure
Azure requires slightly different configuration:
Audience: This defaults to
00000003-0000-0000-c000-000000000000, which is the CMS GraphQL API ID. This can be customized if your Azure configuration requires it.Validation Interval: Sets how frequently the CMS API will validate tokens against Azure’s OpenID userinfo endpoint. The default is 300 seconds (5 minutes). A shorter interval enhances security by re-checking token validity more often but may impact performance.
Tenant: For API token validation, make sure the Tenant field is set in the SSO configuration. When left unset, it defaults to
"common", which works for regular SSO authentication. However, a specific tenant ID is required for API token validation.
...
Important: Azure tokens cannot be validated directly with a JWKS key. Instead, our system validates the token by making a request to the Azure OpenID
userinfoendpoint. Results are cached and only checked per the set interval to avoid performance issues.
Security vs. Performance
For both configurations, remember:
Shorter validation intervals increase security by checking token validity more frequently but may slow response times.
Longer validation intervals improve response speed by reducing validation checks but may reduce security.
...
Example Use Cases
Use Case 1: Auth0 Integration
If your company uses Auth0 as the IDP:
Set the audience to your Auth0 audience API identifier.
Define valid algorithms, e.g.,
RS256.Optionally, specify an alternative JWKS endpoint or explicit validation key if required by your security setup.
Assuming everything is correctly set up on you Auth0 account, get an API token for your user:
...
Pass the obtained Auth0 access token to the ScopeAR API as usual (make sure the
permalinkparameter is included in the URL):
...
Use Case 2: Azure Integration
If your company uses Microsoft Azure:
Keep the audience at its default or enter your custom value if required.
Adjust the validation interval according to your security needs (e.g., 120 seconds for stricter security).
Assuming everything is correctly set up on you Microsoft Azure account, get an API token for your user:
Pass the obtained Microsoft Azure access token to the ScopeAR API as usual (make sure the
permalinkparameter is included in the URL):
This new feature offers flexibility and security by allowing access tokens from your existing SSO IDP to authenticate directly with our CMS API. Feel free to contact our support team for further setup assistance.