Skip to content

OpenLicensingProtocolImplementation.md

Latest commit

 

History

History
319 lines (252 loc) · 15.4 KB

OpenLicensingProtocolImplementation.md

File metadata and controls

319 lines (252 loc) · 15.4 KB
Raw

Project Specification.

I want you to implement a frontend web interface that will allow a user to manage oauth apps and allow them to set what is need to provide a simple OIDC provider as part of the Oauth flow. I am looking for a very simple solution that I can use to replace Google as an OAuth idp.

I already have an MCPAuth middleware that works by inspect traffic and enforces the OAuth tokens and redirects the user to the Idp. I have this working for Google Idp but I now want my own Idp that I can provide to my users. I want to be able to allow users to create an OAuth application which allows them to set the redirect url etc. I want the user to be able to manage scopes per Oauth application. It would also be good to have a very basic user database where a user can be created and the Oauth can take place against those user credentials. I dont need access control for the administrator for this front end as I can manage that myself with Traefik.

My current MCPAuth project can provide the basis for this to be extended. MCPAUth provides the intermediate middleware. Here are the curl commands that can be used to test the provided Go code, along with an explanation of what each one does. 💻

Please note that you'll need to replace localhost:8080 with the actual address and port where your server is running. These commands assume your server is running on http://localhost:8080.

1. Health Check

This command is for testing the basic health of the server. It makes a GET request to the /health endpoint.

  • Command: 
    curl -X GET http://localhost:8080/health
  • Expected Output: The server should return a JSON object with a status of 200 and a message of "OK", indicating that it's up and running. 
    {"status":200,"message":"OK"}

2. OAuth Authorization Server Metadata

This command retrieves the server's OAuth configuration. It makes a GET request to the .well-known endpoint. This is a standard endpoint for OAuth server discovery.

  • Command: 
    curl -X GET http://localhost:8080/.well-known/oauth-authorization-server
  • Expected Output: The server should return a JSON object containing key endpoints and supported features like authorization_endpoint, token_endpoint, and response_types_supported. This is useful for clients to automatically configure themselves.

3. OAuth Client Registration

This command registers a new OAuth client with the server. It's a POST request to the /register endpoint with a JSON payload in the request body.

  • Command: 
    curl -X POST http://localhost:8080/register \
-H "Content-Type: application/json" \
-d '{
  "client_name": "My Test App",
  "redirect_uris": [
    "http://localhost:3000/callback",
    "https://example.com/callback"
  ]
}'
  • Required Info:
    • client_name: A human-readable name for your client application.
    • redirect_uris: An array of URLs where the authorization server can send the user back after authentication. This is crucial for security.
  • Expected Output: A successful registration will return a JSON response containing the newly generated client_id and the redirect_uris. You will need this client_id for subsequent steps.

4. Initiate the OAuth Authorization Flow

This command starts the authorization process. It simulates a user's browser being redirected to the authorization server's /authorize endpoint. This command will print the redirect URL in the terminal.

  • Command: 
    curl -i -X GET "http://localhost:8080/authorize?client_id=YOUR_CLIENT_ID&redirect_uri=http://localhost:3000/callback&response_type=code&scope=openid%20profile%20email&state=some-random-state"
  • Required Info:
    • client_id: The ID you received from the client registration step.
    • redirect_uri: A URI from the list you registered. It must match exactly.
    • response_type: The type of response requested, which must be code for this flow.
    • scope: The permissions your client is requesting. The provided code supports openid, profile, and email.
    • state: A random value used to maintain state between the request and the callback, preventing CSRF attacks.
  • Expected Output: The server will respond with a 307 Temporary Redirect and a Location header that points to the OAuth provider's authorization URL (e.g., Google's sign-in page), containing a state and nonce parameter. 
    HTTP/1.1 307 Temporary Redirect
...
Location: https://accounts.google.com/o/oauth2/v2/auth?...
...
    This redirect URL is what you'd manually paste into your browser to complete the authentication with the external provider.

5. Exchange Authorization Code for Tokens

This command is the final step in the authorization flow. It simulates your client application receiving the authorization code and state from the callback and then exchanging it for an access_token and id_token. It's a POST request to the /token endpoint with a form-encoded body.

  • Command: 
    curl -X POST http://localhost:8080/token \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=authorization_code&code=THE_CODE_FROM_CALLBACK&redirect_uri=http://localhost:3000/callback&client_id=YOUR_CLIENT_ID"
  • Required Info:
    • grant_type: Must be authorization_code.
    • code: The authorization code that your callback handler received from the previous step (Step 4's callback). You can find this in the Location header of the callback redirect response.
    • redirect_uri: The same URI used in the initial authorization request.
    • client_id: The client ID from Step 3.
  • Expected Output: A successful response will be a JSON object containing the access_token, id_token, token_type (Bearer), and expires_in (token lifetime in seconds). This is the key payload your client application needs to access protected resources.

When you have created the simple OIDC provider web interface and database. I would then like to extend the overall solution to provide the functionality for an Open Licensing Protocol Server. Here is what I know about this licensing server:

RSL Open License Protocol (OLP) Version 1.0 Draft. Last updated: 2025-08-14.

The RSL Open Licensing Protocol (OLP) is an extension of the OAuth 2.0 authorization framework. OLP introduces a new OAuth 2.0 grant type, rsl, to support using RSL licenses as credentials for controlling access to digital assets.

The OLP protocol suite includes

a protocol for acquiring an RSL license for a digital asset a protocol for checking if an RSL license grants access to a digital asset a protocol for retrieving a license key to encrypt or decrypt a digital asset file Other server capabilities, including license registration, management, payment, and service-level policies, are outside the scope of this specification and are left to the implementation of individual license server operators.

Client Authentication OLP uses standard OAuth 2.0 client authentication to verify the identity of clients that want to interact with an RSL License Server. Each client is assigned a unique client_id and client_secret by the license server operator when the client registers with the server, and the client must use these credentials to authenticate itself when making requests to the server.

If the client is not authorized for a request, the server responds with an error as defined in RFC 6749 Section 5.2.

Example: Client Credentials Flow

POST /token Host: rslstandard.org/api Content-Type: application/x-www-form-urlencoded Authorization: Basic base64(client_id:client_secret) Acquire an RSL License for a Digital Asset To acquire an RSL license for a digital asset, the client submits a request to the license server using the OAuth 2.0 token endpoint with the grant type rsl. The request must include a complete RSL element that describes the terms under which the client wants to license the digital asset, and a resource parameter specifying the URL of the digital asset to be licensed.

This grant type allows a client to obtain an RSL License Token that serves as proof that the client has acquired an RSL license for a digital asset. The license token may later be introspected or used to retrieve encryption keys, as described in subsequent sections.

Endpoint

POST /token Request Parameters Parameter Type Description grant_type string Must be set to rsl license string A complete RSL XML element of the requested licensing terms resource string The URL of the digital asset for which the license is being requested Response Fields If the request is valid and authorized, the license server responds with a license token that represents the acquired RSL license. The license token is returned in the form of an OAuth access token, with the token type set to rsl.

Field Type Description access_token string A token representing the acquired RSL license token_type string Always rsl expires_in integer Lifetime of the token, in seconds Example Request

POST /token Authorization: Basic base64(client_id:client_secret) Content-Type: application/x-www-form-urlencoded

grant_type=rsl& license=%3Clicense%3E...%3C%2Flicense%3E& resource=https%3A%2F%2Fexample.com%2Farticle%2F123 Response

{ "access_token": "rsl_cnNsLWNsaWVudC0xMjM6czNjcjN0S0VZ", "token_type": "rsl", "expires_in": 0 } Error Responses If the request is invalid or unauthorized, the license server responds with an HTTP 400 status code and a JSON object describing the error.

Error Format

{ "error": "invalid_request", "error_description": "The request is missing a required parameter." } Error Code Description invalid_request The request is missing a required parameter, includes an invalid parameter value, or is otherwise malformed invalid_client Client authentication failed (e.g., bad credentials or unknown client) unauthorized_client The client is not authorized to use the rsl grant type invalid_license The license is invalid or not available for the specified resource invalid_resource The resource is invalid or not managed by this license server unsupported_grant_type The grant_type value is not supported by the token endpoint server_error The server encountered an unexpected condition that prevented it from fulfilling the request Validate Access to a Digital Asset This protocol allows a resource server or client to determine whether the terms of a previously issued license token permit access to a digital asset. This check is typically performed by a website before serving license-restricted content (see also Authenticating Web Crawlers) or by a client to verify that they are in compliance with license terms.

Validation is performed by submitting the license token and the digital asset URL to the license server’s introspection endpoint. This endpoint conforms to the OAuth 2.0 token introspection specification (RFC 7662), with OLP-specific extensions.

Endpoint

POST /introspect Request Parameters Parameter Type Description token string The RSL license token to be validated resource string The URL of the digital asset whose access is being validated against the license token Response Fields Field Type Description active boolean Indicates whether the license token is valid and recognized by the license server token_type string Always rsl license string RSL XML element represented by the license token resource string URL of the digital asset covered by the RSL license permitted boolean Indicates whether the license permits access to the specified resource reason string (Optional) Human-readable explanation if access is denied Example Request

{ "token": "rsl_cnNsLWNsaWVudC0xMjM6czNjcjN0S0VZ", "resource": "https://example.com/article/abc" } Successful Response

{ "active": true, "token_type": "rsl", "license": "...", "resource": "https://example.com/", "permitted": true } Denied Response

{ "active": true, "token_type": "rsl", "license": "...", "resource": "https://test.com/", "permitted": false, "reason": "License does not cover this resource" } Expired or Invalid Token

{ "active": false } Error Responses If the request is malformed or unauthorized, the server responds with HTTP 400 or 401 status codes and an error object conforming to RFC 7662 Section 2.3.

Error Code Description invalid_request Missing token or resource, or invalid parameter encoding invalid_token License token is expired, revoked, or unrecognized unauthorized_client Client authentication failed or is not permitted to use this endpoint server_error The server encountered an unexpected condition Example Error

{ "error": "invalid_request", "error_description": "Missing required parameter: resource" } Retrieve License Key to Encrypt or Decrypt a Digital Asset This protocol allows a client to retrieve a JSON Web Key (JWK) to encrypt or decrypt a digital asset governed by an RSL license. This capability enables content owners to securely license nonpublic, proprietary content to client applications, including paywalled articles, books, videos, and datasets.

When an RSL license is registered for a digital asset, the license server provisions an associated encryption key. A client with a valid RSL license token can retrieve this key using the /key endpoint.

Endpoint

POST /key Request Parameters Parameter Type Description token string A valid RSL license token previously obtained via the /token endpoint resource string The URL of the encrypted digital asset file Response Fields Field Type Description key object A symmetric encryption key represented in JWK format resource string The URL of the encrypted digital asset file The key object will include the following fields:

JWK Field Type Description kty string Key type — always "oct" for symmetric keys kid string A unique identifier for the key (e.g., UUID) k string Base64url-encoded symmetric key (e.g., 128-bit AES key) alg string Encryption algorithm identifier, such as "A128CTR" Example Request

{ "token": "rsl_cnNsLWNsaWVudC0xMjM6czNjcjN0S0VZ", "resource": "https://example.com/media/episode-1.mp4.aes" } Successful Response

{ "key": { "kty": "oct", "kid": "7e0d5c22-1234-4567-b89c-aabbccddeeff", "k": "L8sX8V3vB8r-k7oSdhZMQw", "alg": "A128CTR" }, "resource": "https://example.com/media/episode-1.mp4.aes" } Error Responses If the license token is invalid or the license does not permit access to the requested asset, the server responds with an appropriate error.

Error Code Description invalid_token The license token is expired, revoked, or unrecognized insufficient_scope The license does not permit access for the specified resource invalid_request Missing or malformed token or resource parameter unauthorized_client Client authentication failed server_error The server encountered an unexpected condition Example Error

{ "error": "access_denied", "error_description": "License does not permit access to this resource" }

Can you adapt my solution to provide an open source implementation of the Open Protocol Licensing Server

You must think hard about the right way to architect this solution so that it reuses as much as possible of MCPAuth and doesnt break that functionality but can also be extended. You need to fully test the solution using curl commands and fake the OAUth flows to make sure that they work.