API Authentication via JSON Web Tokens

ScopeAR has implemented 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.

Key Benefits of Using Self-Issued Tokens

1. Increased Control and Flexibility
   With RFC 9068, organizations can issue their own JWT tokens, giving them the ability to define how and when access is granted to the Worklink API. This is especially useful for organizations with a centralized identity provider or specific access policies for different teams or projects.

2. Simplified Identity Management
   By using self-issued tokens, organizations can integrate access to the Worklink API with their existing Single Sign-On (SSO) provider or identity management system. This ensures that users have a consistent login experience across all applications, eliminating the need to rely on ScopeAR for token issuance and authentication.

3. Streamlined Integration
   Using self-issued tokens avoids the need to obtain and manage separate tokens from ScopeAR for each user or service, reducing administrative overhead. This simplifies the process of integrating existing systems with the Worklink API, making the authentication flow more efficient.

4. Enhanced Security and Compliance
   With control over token generation and validation, organizations can enforce their own security policies, such as stricter rules around token expiration and revocation. This flexibility allows organizations to tailor security practices to meet their specific compliance requirements, adding an extra layer of protection.

5. Compatibility and Seamless Transition
   RFC 9068 is designed to be compatible with existing OAuth 2.0 and JWT-based systems. Organizations can integrate the Worklink API into their current security infrastructure with minimal changes, making the transition smooth and hassle-free.

How Does It Work?

When using RFC 9068, an organization’s system generates a JWT access token containing the necessary claims, such as:

• iss (Issuer): Identifies the organization’s system as the token issuer.

• aud (Audience): Specifies that the token is intended for the Worklink API.

• sub (Subject): Ties the token to a specific user or service within the organization.

• exp (Expiration): Defines how long the token is valid, reducing the risk of misuse.

• Signature: Ensures that the token was created by the organization’s system and has not been altered.

This self-issued token is then sent with each request to the Worklink API, where it is validated according to the standard’s guidelines. If the token’s claims match the expected values and the signature is valid, the Worklink API will accept the token and grant access to the requested resources.

Breakdown of JWT Structure and Claims

A JSON Web Token (JWT) is composed of three parts: the header, the payload (claims), and the signature. Each part plays a role in ensuring the token’s authenticity, integrity, and validity.

A JWT is represented as a string with three Base64-encoded segments separated by periods (.):

header.payload.signature

1. Header
   The header contains metadata about the token, including the type of token and the algorithm used for signing.
   Example:

   {
     "alg": "RS256",  // Algorithm used to sign the token, e.g., RS256 (RSA Signature with SHA-256)
     "typ": "JWT"     // Type of the token, always "JWT"
   }

2. Payload (Claims)
   The payload contains the actual claims, which are statements about an entity (typically the user) and additional data. These are predefined claims in the JWT specification that are necessary:

   1. iss (Issuer): Identifies who issued the token.
      Validation: The API server checks that the iss value matches the expected issuer URL. This ensures that the token was generated by a trusted source.

   2. sub (Subject): Identifies the subject of the token (the user).
      Validation: The API server uses the sub value to identify the user or service making the request and link it to the correct permissions. This should map to a username of a user record in ScopeAR.

   3. aud (Audience): Specifies the recipient(s) that the JWT is intended for.
      Validation: The API server checks that the aud value matches the Worklink API’s identifier. This ensures that the token is intended for the Worklink API and not for another resource or service.

   4. exp (Expiration Time): Specifies the time after which the token must not be accepted.
      Validation: The API server checks that the current time is before the exp timestamp. This ensures that the token is still valid and has not expired.

   5. iat (Issued At): Indicates when the JWT was issued.
      Validation: The API server checks that the iat value is a reasonable time in the past. This can help detect tokens that might have been created too far in the past or future, adding protection against certain timing attacks.

   6. jti (JWT ID): A unique identifier for the token, used to prevent token replay attacks.
      Validation: The API server checks if the jti has already been used. If it has, the token may be rejected to prevent replay attacks.
      Example:

   {
     "iss": "<https://example.com>",   // Issuer of the token
     "sub": "1234567890",            // Subject (user or system identifier)
     "aud": "<https://worklink.api>",  // Audience (intended recipient of the token)
     "exp": 1633036800,              // Expiration time (timestamp)
     "iat": 1632950400,              // Issued at time (timestamp)
     "jti": "abc123def456"           // JWT ID (unique identifier for the token)
   }

3. Signature
   The signature ensures that the token’s data has not been tampered with. The signature is created by taking the encoded header and payload, hashing them with a secret or public/private key, and appending it to the token.

   Example:

   HMACSHA256(
     base64UrlEncode(header) + "." + base64UrlEncode(payload),
     secret
   )

Configuration in the ScopeAR CMS

You can use the following instructions to set up JSON Web Token API Auth.

Step 1: 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 2: Enable API Authentication via JSON Web Token

Click on the toggle to enable the feature.

Step 3: Fill in the Audience field

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 4 (Optional): Change the Valid Algorithms

This is the encryption algorithm used to encrypt the JSON Web Token. By default it is set RS256 which is the standard.

Step 5 (Optional): Add JSON Web Key Set Endpoint

The JSON Web Key Set Endpoint (JWKS URI) can be automatically retrieved from the IdP’s discovery URL (typically the .well-known endpoint). However, this endpoint can also be manually set with this field.

Step 6 (Optional): Add Validation Key

The Worklink API verifies access token signatures using a public key. This public key is automatically retrieved from the jwks_uri endpoint. However, the public key can be manually set by placing the key into this field.