Authorization Using The Cedarling#
This quick start guide shows how to quickly test authorization of a user action using the Cedarling. We will be using the application asserted identity approach in this guide to implement role based access control(RBAC). Refer to this section to understand how to use Cedarling with TBAC approach.
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.
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 (a JSON file). To aid in this quick start guide, we have already created a policy store at quick start GitHub repository. We will use this policy store to allow/deny the incoming authorization request.
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 master branch only
option
- Click on
- 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 onAdd 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_USER_AUTHZ": "enabled", "CEDARLING_WORKLOAD_AUTHZ": "disabled", "CEDARLING_PRINCIPAL_BOOLEAN_OPERATION": { "===": [{"var": "Jans::User"}, "ALLOW"] }, "CEDARLING_JWT_SIG_VALIDATION": "enabled", "CEDARLING_JWT_STATUS_VALIDATION": "disabled", "CEDARLING_MAPPING_USER": "Jans::User", "CEDARLING_MAPPING_WORKLOAD": "Jans::Workload", "CEDARLING_JWT_SIGNATURE_ALGORITHMS_SUPPORTED": [ "HS256", "RS256" ], "CEDARLING_ID_TOKEN_TRUST_MODE": "never" }
- 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 onCedarling Unsigned Authz Form
- Input the following in respective input boxes:
[
{
"type": "Jans::User",
"id": "some_id",
"sub": "some_sub",
"role": ["SupremeRuler"]
}
]
Jans::Action::"Read"
{
"entity_type": "resource",
"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.
{
"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.
[
{
"type": "Jans::User",
"id": "some_id",
"sub": "some_sub",
"role": [""]
}
]
And click Cedarling Authz Request
again. Cedarling will return a new result:
{
"decision": false,
...
}
The top-level decision: false
shows Cedarling denying authorization.
Implement TBAC Using Cedarling#
In this guide, we will use Token-Based Access Control (TBAC) to implement role-based access control (RBAC).
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 valueSupremeRuler
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.
The policy store has a policy
that grants access to all actions and all the resources,
to the users with the SupremeRuler
role. The policy is as follows:
@id("allow_supreme_ruler")
permit(
principal in Jans::Role::"SupremeRuler",
action,
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 policy store 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
key in the policy store JSON file named449805c83e13f332b1b35eac6ffa93187fbd1c648085.json
in the fork. Set the value to the.well-known/openid-configuration
endpoint of your IDP.For instance:
"openid_configuration_endpoint": "https://test-jans.gluu.info/.well-known/openid-configuration"
-
Copy the link of the policy store file's raw content. This is the same file that you edited in the step above. The URI would be similar to the shown below. This URI will be used in the next step when we configure Tarp.
https://raw.githubusercontent.com/JanssenProject/CedarlingQuickstart/refs/heads/main/449805c83e13f332b1b35eac6ffa93187fbd1c648085.json
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 master branch only
option
- Click on
- 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 clickAdd 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_USER_AUTHZ": "enabled", "CEDARLING_WORKLOAD_AUTHZ": "disabled", "CEDARLING_PRINCIPAL_BOOLEAN_OPERATION": { "===": [{"var": "Jans::User"}, "ALLOW"] }, "CEDARLING_JWT_SIG_VALIDATION": "enabled", "CEDARLING_JWT_STATUS_VALIDATION": "disabled", "CEDARLING_MAPPING_USER": "Jans::User", "CEDARLING_MAPPING_WORKLOAD": "Jans::Workload", "CEDARLING_JWT_SIGNATURE_ALGORITHMS_SUPPORTED": [ "HS256", "RS256" ], "CEDARLING_ID_TOKEN_TRUST_MODE": "never" }
- 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 ⚡ 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
- ACR:
-
Click the
Trigger auth flow
button - Login using username and password of a user who has the
SupremeRuler
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 selectCedarling 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::"Read"
- Resource:
{ "entity_type": "resource", "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.