Authorization Using The Cedarling#

This quick start guide shows how to test authorization of a user action using the Cedarling. We cover two authorization approaches:

RBAC using signed tokens (TBAC) — the recommended starting point for most production deployments. Uses authorize_multi_issuer to validate real JWT tokens from trusted identity providers.
RBAC using application-asserted identity — uses authorize_unsigned for scenarios where the application has already verified the principal. Useful for testing, custom auth flows, or service-to-service calls.

Not sure which to choose? See the decision guide below.

To see authorization using Cedarling in action, we need 3 things:

An authorization policy
A request for user action
A running instance of the Cedarling

For 1 above, we will use a ready demo policy.

For 2 and 3, we will use Janssen Tarp. Janssen Tarp is an easy to install browser plug-in that comes with embedded Cedarling instance (WASM). Janssen Tarp also provides user interface to build authorization and authentication requests for testing purpose.

Which authorization method should I use?#

	`authorize_multi_issuer`	`authorize_unsigned`
When to use	You have JWT tokens from trusted IDPs and want Cedarling to validate them	Your application has already authenticated the principal and wants to pass raw entity data directly
JWT validation	Yes — full signature, expiration, and status validation	No — accepts raw entity data as-is
Principal source	Derived from JWT token claims	Supplied directly by the application
Typical scenarios	Production apps with OIDC/OAuth IDPs, federation, API gateways, multi-issuer environments	Custom auth flows, testing, service-to-service with upstream verification, local development
Security model	Higher — Cedarling independently verifies token authenticity	Lower — trusts the calling application to have verified the principal
Recommended for	Most production deployments	Prototyping, or when authentication is handled externally

Recommendation: Start with authorize_multi_issuer if you have an identity provider that issues JWTs. Use authorize_unsigned only when you have a specific reason not to pass tokens to Cedarling.

Implement RBAC using signed tokens (TBAC)#

In this guide, we will use Token-Based Access Control (TBAC) to implement role-based access control (RBAC). This is the recommended approach for most production deployments since it includes actual JWT validation against trusted issuers.

For better understanding of the TBAC flow, see the diagram below.

TBAC Sequence diagram

sequenceDiagram
    title Cedarling and Tarp

    participant Browser
    participant Tarp
    participant Auth Server

    Browser->>Tarp: Enter Auth Server config
    Tarp->>Auth Server: Dynamic Client Registration
    Auth Server->>Tarp: Client ID and Secret
    Browser->>Tarp: Enter Cedarling bootstrap config
    Tarp->>Auth Server: GET /jans-auth/restv1/jwks
    Auth Server->>Tarp: JWKS
    Tarp->>Tarp: Initialize Cedarling
    Browser->>Tarp: Start authentication flow
    Tarp->>Auth Server: GET /jans-auth/restv1/authorize?...
    Auth Server->>Tarp: /callback?code=...
    Tarp->>Auth Server: GET /jans-auth/restv1/token
    Auth Server->>Tarp: {"access_token": <JWT>}

    Browser->>Tarp: Cedarling authorization flow(principal, action, resource, context)
    Tarp->>Browser: Cedarling Decision

Prerequisites#

Install the Janssen Tarp on Chrome or Firefox.
Instance of Janssen Server or any other IDP with following configuration in place.
- Allow dynamic client registration
- Allow registered clients to request the role scope
- Have a user with the role claim set to the value Teacher and return this claim in the userinfo token

Step-1: Create Cedar Policy and Schema#

For this guide, we have created a policy store in the demo GitHub repository, under the tarpDemo directory.

The policy store has two policies relevant to this guide. The first grants access to all actions and all resources to the users with the Teacher role. The second allows only Read permission to students with the Student role to any resource. The two policies are as follows:

@id("allow_teacher")
permit(
  principal in Jans::Role::"Teacher",
  action,
  resource
);

@id("allow_student_read")
permit(
  principal in Jans::Role::"Student",
  action in [Jans::Action::"Read"],
  resource
)

Step-2 Update the IDP information#

The policy store in the demo repository has information about the IDP that released the tokens. You'll need to fork the demo repository and update the trusted issuer configuration to point it to your IDP instance. Follow the steps below to do this.

Fork the demo repository. While creating the fork, uncheck the Copy the main branch only checkbox.
Update the openid_configuration_endpoint value in the trusted issuer file tarpDemo/trusted-issuers/jans.json in the fork. Set it to the .well-known/openid-configuration endpoint of your IDP.

For instance:
```
"openid_configuration_endpoint": "https://your-idp.example.com/.well-known/openid-configuration"
```
Package the policy store as a .cjar archive (a ZIP file of the directory contents) and host it somewhere accessible via URL. The CEDARLING_POLICY_STORE_URI property requires either a .cjar URL or a legacy JSON URL — it does not support raw directory URLs.

To create a .cjar archive from the tarpDemo directory:
```
cd tarpDemo && zip -r ../tarpDemo.cjar .
```
Then host the .cjar file (e.g., as a GitHub release asset, on a web server, or in cloud storage) and use its URL in the next step. For example:
```
https://github.com/<your-username>/CedarlingQuickstart/releases/download/v1/tarpDemo.cjar
```

Agama Lab: For authoring policies and managing the policy store

Alternatively, you can also use the Agama Lab For authoring policies and managing the policy stores.

Agama Lab is a free web tool provided by Gluu. This tool makes it very easy to author, update policies and schema using an user interface. Follow the steps below to make changes to the policy that we are using above.

Go to the CedarlingQuickstart repository where the demo policy store is hosted
- Click on Fork
- uncheck the Copy the main branch only option
Install Agama Lab app and allow access to forked repository
Open the Agama Lab policy designer.
Click on Change Repository.
Select the option Manually Type Repository URL.
Paste the URL of your forked repository, then click the Select button.
This will open the dashboard with two policy stores listed. Open the policy store named tarpDemo.
Now you can update the policy and schema using the policy designer

Step-3: Configure Tarp with the policy store#

We will now add the policy store details in the Janssen Tarp that is installed in the browser. The Cedarling instance embedded in the Tarp will use the policy from the store (from step-1) to evaluate the authorization request.

Open Tarp installed in the Chrome browser
Click Add Client. Use details below to add a new client.
- Issuer: The hostname of your IDP
- Expiry: The day after today
- Scopes: openid, profile, role
Click Register to register a new client on your IDP.
Go to Cedarling tab and click Add Configurations

Select JSON configuration type and Paste the config as given below. Remember to replace <Policy Store URI> with the URI of your policy store:

      {
        "CEDARLING_APPLICATION_NAME": "My App",
        "CEDARLING_POLICY_STORE_URI": "<Policy Store URI>",
        "CEDARLING_LOG_TYPE": "std_out",
        "CEDARLING_LOG_LEVEL": "INFO",
        "CEDARLING_JWT_SIG_VALIDATION": "enabled",
        "CEDARLING_JWT_STATUS_VALIDATION": "disabled",
        "CEDARLING_JWT_SIGNATURE_ALGORITHMS_SUPPORTED": [
          "HS256", "RS256"
        ]
      }

!!! note CEDARLING_JWT_STATUS_VALIDATION is disabled here because most quick-start setups don't have a token status list endpoint configured. In production, enable it for full token revocation checking.

Click Save to initialize Cedarling.

This will start the embedded Cedarling instance in the Tarp.

Step-4: Test the policy using the Cedarling#

Since we are implementing TBAC, we have to authenticate the user first to get the tokens.

In Tarp, under Authentication flow tab, click the lightning icon to begin authentication
Use the following inputs to fill the form:
- ACR: basic
- Scopes: openid, profile, role
- Check the Display access and ID token after authentication checkbox
Click the Trigger auth flow button
Login using username and password of a user who has the Teacher role assigned in the IDP
Click Allow on the consent screen
If the authentication is successful, Tarp will show you a page with token details
Move to Cedarling tab and select Cedarling Signed Authz Form tab
Use the details below as an input to this form:
- Principal: select all 3 tokens. In TBAC approach here, we are passing tokens (i.e signed JWTs) in place of JSON string.
- Action: Jans::Action::"Write"
- Resource:
```
{
  "cedar_entity_mapping": {
    "entity_type": "Jans::SecretDocument",
    "id": "some_id"
  }
}
```
- Leave the context as default

Click Cedarling Authz Request

Sample Response

{
  ...
  "decision": true,
  "request_id": "019602f1-c964-7dbb-8a07-5b66b642e502"
}

The top-level decision: true confirms successful authorization.

To test the negative case, we will do the following:

Modify the user in the IDP to have the Student role instead of Teacher
Logout from the Cedarling if you are logged in and rerun the authorization flow with the same parameters to obtain new tokens
Run signed authorization using the same inputs
The top-level decision: false confirms failed authorization. The first policy in the store allowed full access to users in the Teacher role, but the second policy only allowed Read access, which fails since our request was Write access.
Repeat the authorization with action Jans::Action::"Read" to confirm that the user has Read access but not Write access

Implement RBAC using application-asserted identity#

In this section, we will see how to implement role-based access control using the Cedarling when the information about the principal is supplied by the host application. We can call this approach the application-asserted identity approach.

This method uses authorize_unsigned — no JWT validation is performed. Use this when your application has already authenticated the principal through other means, or for testing and prototyping.

Prerequisite#

Install the Janssen Tarp on Chrome or Firefox.

Step-1: Create the Cedar Policy and Schema#

The Cedarling needs policies and a schema to authorize access. These are bundled in a policy store. To aid in this quick start guide, we have already created a policy store in the quick start GitHub repository, under the tarpUnsignedDemo directory. We will use this policy store to allow/deny the incoming authorization request.

Since Tarp runs in a WASM environment, the policy store must be loaded via URL as a .cjar archive (a ZIP of the directory contents). To create one:

cd tarpUnsignedDemo && zip -r ../tarpUnsignedDemo.cjar .

Host the .cjar file somewhere accessible (e.g., GitHub release, web server, cloud storage) and use its URL as the <Policy Store URI> in Step-2.

Agama Lab: For authoring policies and managing the policy store

Alternatively, you can also use the Agama Lab For authoring policies and managing the policy stores.

Agama Lab is a free web tool provided by Gluu. This tool makes it very easy to author, update policies and schema using a web interface. Follow the steps below if you want to make changes to the demo policy that we are using above.

Go to the CedarlingQuickstart repository where the demo policy store is hosted
- Click on Fork
- uncheck the Copy the main branch only option
Install Agama Lab app and allow access to forked repository
Open the Agama Lab policy designer.
Click on Change Repository.
Select the option Manually Type Repository URL.
Paste the URL of your forked repository, then click the Select button.
This will open the dashboard with two policy stores listed. Open the policy store named tarpUnsignedDemo.
Now you can update the policy and schema using the policy designer

Step-2: Configure Tarp#

In this step, we will add the policy store details in the Janssen Tarp that is installed in the browser. The Cedarling instance embedded in the Tarp will use the policy stored in the store (from Step-1) to evaluate the authorization result.

Open the Janssen Tarp installed in the browser
Navigate to the Cedarling tab and click on Add Configurations

Paste the following configuration parameters as JSON. Make sure to update the <Policy Store URI> value to point to your policy store

{
    "CEDARLING_APPLICATION_NAME": "My App",
    "CEDARLING_POLICY_STORE_URI": "<Policy Store URI>",
    "CEDARLING_LOG_TYPE": "std_out",
    "CEDARLING_LOG_LEVEL": "INFO",
    "CEDARLING_PRINCIPAL_BOOLEAN_OPERATION": {
      "===": [{"var": "Jans::User"}, "ALLOW"]
    },
    "CEDARLING_JWT_SIG_VALIDATION": "disabled",
    "CEDARLING_JWT_STATUS_VALIDATION": "disabled",
    "CEDARLING_JWT_SIGNATURE_ALGORITHMS_SUPPORTED": [
      "HS256", "RS256"
    ]
}

CEDARLING_PRINCIPAL_BOOLEAN_OPERATION controls how per-principal decisions are combined in authorize_unsigned. Here it checks only the Jans::User principal. See Principal Boolean Operations for details.

Click Save to initialize the Cedarling. The Cedarling will fetch and validate your policy store during the initialization.

The Cedarling is ready to receive and evaluate authorization requests at this stage.

Step-3: Test authorization using the Cedarling#

Go to Tarp's Cedarling tab, click on Cedarling Unsigned Authz Form
Input the following in respective input boxes:

Principal

    [
      {
        "cedar_entity_mapping": {
          "entity_type": "Jans::User",
          "id": "some_id"
        },
        "sub": "some_sub",
        "role": [
          "Teacher"
        ]
      }
    ]

Actions

Jans::Action::"Read"

Resource

    {
      "cedar_entity_mapping": {
        "entity_type": "Jans::SecretDocument",
        "id": "some_id"
      }
    }

Leave the Context blank.

The request is ready to be sent. Click Cedarling Authz Request to send the request to the embedded Cedarling. After evaluation of the authorization request, the Cedarling will respond with a JSON payload. Similar to what is shown below.

Sample Response

    {
      "decision": true,
      "request_id": "019602e5-b148-7d0b-9d15-9d000c0d370b",
      ...
    }

The top-level decision: true confirms successful authorization.

Let's check a scenario where authorization is denied. Remove the role from the Principal entity and test the authorization.

Principal

[
  {
    "cedar_entity_mapping": {
      "entity_type": "Jans::User",
      "id": "some_id"
    },
    "sub": "some_sub",
    "role": []
  }
]

And click Cedarling Authz Request again. Cedarling will return a new result:

Sample Response

{
  "decision": false,
  ...
}

The top-level decision: false shows Cedarling denying authorization.