API Authentication via JSON Web Tokens

Owned by alain.bloch
Last updated: Oct 29, 2024
9 min read

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

  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:

Configuration in the ScopeAR CMS

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”

image-20241028-221523.png

Step 2: Create an SSO Integration

Use the following link to setup your SSO integration: CMS: Edit Single Sign On (SSO) Company Settings

Step 3: Enable API Authentication via JSON Web Token

Click on the toggle to enable the feature.

 

Screen Shot 2024-10-08 at 9.22.09 AM.png
The enabled toggle is at the bottom

 

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-known endpoint). 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_uri endpoint. 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 userinfo endpoint. 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:

  1. Set the audience to your Auth0 audience API identifier.

  2. Define valid algorithms, e.g., RS256.

  3. Optionally, specify an alternative JWKS endpoint or explicit validation key if required by your security setup.

  4. Assuming everything is correctly set up on you Auth0 account, get an API token for your user:

  1. Pass the obtained Auth0 access token to the ScopeAR API as usual (make sure the permalink parameter is included in the URL):

Use Case 2: Azure Integration

If your company uses Microsoft Azure:

  1. Keep the audience at its default or enter your custom value if required.

  2. Adjust the validation interval according to your security needs (e.g., 120 seconds for stricter security).

  3. Assuming everything is correctly set up on you Microsoft Azure account, get an API token for your user:

 

 

  1. Pass the obtained Microsoft Azure access token to the ScopeAR API as usual (make sure the permalink parameter 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.